v0.8.3: WebUI models, providers and keys; garbled thinking fixed

Streaming: Chinese reasoning showed up garbled in the WebUI. The agent
loop now feeds visible/thinking text in runs instead of byte by byte,
and the WebUI holds an incomplete UTF-8 tail until the next chunk
(cst_utf8_hold_feed), so every think_delta/assistant_delta is whole.

src/provider_switch.c: model list fetch/cache, key verify-and-save and
provider switching moved out of tui.c and shared by TUI and WebUI.

WebUI API:
- GET /api/providers, GET /api/models[?refresh=1] (401 on a rejected
  key, still listing built-ins), POST /api/provider, POST /api/key
  (key checked against /v1/models, saved to credentials 0600, never
  echoed in replies, events or logs)
- /api/config validates everything before applying, persists model,
  effort and approval (not yolo), warns when effort does not apply;
  plan_mode no longer forces read-only
- state: turn_usage, api_base, key_set/key_from, model_info,
  effort_applies, sees_images, max_steps, tool_profile, perm_timeout;
  permission events carry their timeout

Frontend: searchable model picker with refresh and manual entry,
provider picker and key dialog, effort/vision hints, toasts instead of
silent failures, Chinese error text, real protocol in the settings and
usage panels, approval countdown from the server's timeout.

Tests: utf8 hold unit test, scripts/e2e_webui_settings.py (fake
/v1/models, wrong key, switching, persistence, Chinese thinking) run
from e2e_webui.sh, scripts/tui_keys/provider.py.

.gitea/workflows/ci.yml

@@ -54,6 +54,8 @@ jobs:
           ./cst-agent --help
           ./cst-agent --workspace "$PWD" --list-sessions
           ./cst-agent --demo-ctl --workspace .
+      - name: WebUI end-to-end (recorded stream, no API key)
+        run: sh scripts/e2e_webui.sh
 
   musl:
     runs-on: ubuntu-latest

.gitignore

@@ -30,3 +30,5 @@ vendor/sashidown/*.o
 vendor/sashidown/src/*.o
 vendor/sashidown/libsashidown.a
 vendor/sashidown/libsashidown-mingw.a
+.gen/
+.build-tmp/

CMakeLists.txt

@@ -5,6 +5,7 @@ set(CMAKE_C_STANDARD 11)
 set(CMAKE_C_STANDARD_REQUIRED ON)
 
 option(CST_BUILD_TUI "Build ncurses/PDCurses TUI" ON)
+option(CST_BUILD_WEBUI "Build the HTTP/SSE WebUI (--web)" ON)
 option(CST_NATIVE_ARCH "Pass -march=native to sashidown" OFF)
 option(CST_BUNDLE_BUSYBOX "Install placeholder/scripts for busybox beside binary" ON)
 
@@ -92,6 +93,8 @@ set(CST_CORE_SOURCES
   src/plugins.c
   src/mcp.c
   src/subagent.c
+  src/attach.c
+  src/clipboard.c
   src/session.c
   src/tools/tools.c
   src/tools/patch.c
@@ -108,10 +111,64 @@ set(CST_CORE_SOURCES
   src/agent_store.c
   src/json_baseline.c
   src/creds.c
+  src/provider_switch.c
   src/mm_tool.c
   src/models.c
+  src/model_registry.c
   src/metrics.c
+  src/net.c
+  src/http_srv.c
+  src/web_md.c
 )
+
+# Built-in model data as a C byte list (included by model_registry.c).
+set(CST_GEN_DIR "${CMAKE_CURRENT_BINARY_DIR}/gen")
+set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS
+  "${CMAKE_CURRENT_SOURCE_DIR}/src/models_builtin.json")
+
+# The WebUI shell (web/*) as C byte arrays, the same trick as the model data.
+file(GLOB CST_WEB_ASSETS "${CMAKE_CURRENT_SOURCE_DIR}/web/*")
+set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${CST_WEB_ASSETS})
+set(_cst_web_inc "/* Generated by CMake from web/ - do not edit. */\n")
+set(_cst_web_table "")
+foreach(_f ${CST_WEB_ASSETS})
+  if(IS_DIRECTORY "${_f}")
+    continue()
+  endif()
+  get_filename_component(_name "${_f}" NAME)
+  string(REGEX REPLACE "[^A-Za-z0-9]" "_" _var "wui_asset_${_name}")
+  file(READ "${_f}" _hex HEX)
+  string(REGEX REPLACE "([0-9a-f][0-9a-f])" "0x\\1," _hex "${_hex}")
+  set(_ctype "application/octet-stream")
+  if(_name MATCHES "\\.html$")
+    set(_ctype "text/html; charset=utf-8")
+  elseif(_name MATCHES "\\.js$")
+    set(_ctype "text/javascript; charset=utf-8")
+  elseif(_name MATCHES "\\.css$")
+    set(_ctype "text/css; charset=utf-8")
+  elseif(_name MATCHES "\\.svg$")
+    set(_ctype "image/svg+xml")
+  endif()
+  string(APPEND _cst_web_inc "static const unsigned char ${_var}[] = {${_hex}0x00};\n")
+  string(APPEND _cst_web_table "  {\"${_name}\", \"${_ctype}\", ${_var}, sizeof(${_var}) - 1},\n")
+endforeach()
+string(APPEND _cst_web_inc "static const wui_asset_t wui_assets[] = {\n${_cst_web_table}};\n")
+string(APPEND _cst_web_inc "static const int wui_asset_count = (int)(sizeof(wui_assets) / sizeof(wui_assets[0]));\n")
+file(WRITE "${CST_GEN_DIR}/web_assets.inc" "${_cst_web_inc}")
+if(NOT CST_BUILD_WEBUI)
+  list(APPEND CST_CORE_SOURCES src/webui_stub.c)
+else()
+  list(APPEND CST_CORE_SOURCES src/webui.c)
+endif()
+
+file(READ "${CMAKE_CURRENT_SOURCE_DIR}/src/models_builtin.json" _cst_models_hex HEX)
+string(REGEX REPLACE "([0-9a-f][0-9a-f])" "0x\\1," _cst_models_hex "${_cst_models_hex}")
+file(WRITE "${CST_GEN_DIR}/models_builtin.inc" "${_cst_models_hex}\n")
+include_directories("${CST_GEN_DIR}")
+
+if(NOT CST_BUILD_WEBUI)
+  add_compile_definitions(CST_NO_WEBUI=1)
+endif()
 if(WIN32)
   # MinGW has no <regex.h>: musl's TRE engine, UTF-8 aware (vendor/tre-regex)
   include_directories(vendor/tre-regex)
@@ -257,16 +314,26 @@ foreach(t ${_CST_SMALL_TESTS})
 endforeach()
 
 # Tests that link the whole core (no TUI).
-foreach(t test_llm_body test_sse_decode test_apply_patch test_session_roundtrip
-          test_shell test_diff test_tools_fs test_registry
-          test_undo test_config test_models test_sandbox
-          test_keymap test_shell_compact test_skills
-          test_plugins test_mcp test_subagent test_lowil
-          test_win_utf8 test_os_dir test_tmpdir)
+set(_CST_CORE_TESTS test_llm_body test_prefix_stable test_sse_decode
+    test_apply_patch test_session_roundtrip test_attach
+    test_shell test_diff test_tools_fs test_registry
+    test_undo test_config test_models test_model_registry test_sandbox
+    test_keymap test_shell_compact test_skills
+    test_plugins test_mcp test_subagent test_lowil
+    test_win_utf8 test_os_dir test_tmpdir)
+if(CST_BUILD_WEBUI)
+  # test_webui drives the real server; the stub has nothing to test.
+  list(APPEND _CST_CORE_TESTS test_webui)
+endif()
+foreach(t ${_CST_CORE_TESTS})
   add_executable(${t} tests/${t}.c ${CST_CORE_SOURCES})
-  target_include_directories(${t} PRIVATE include "${CJSON_DIR}")
+  # The core now contains src/web_md.c, which needs sashidown's header and
+  # archive exactly like the Makefile build does.
+  target_include_directories(${t} PRIVATE include "${CJSON_DIR}" "${SD_DIR}/include")
   target_compile_definitions(${t} PRIVATE _GNU_SOURCE)
-  target_link_libraries(${t} PRIVATE CURL::libcurl Threads::Threads)
+  target_link_libraries(${t} PRIVATE
+    "${SASHIDOWN_A}" CURL::libcurl Threads::Threads)
+  add_dependencies(${t} sashidown)
   if(NOT WIN32)
     target_link_libraries(${t} PRIVATE m)
   else()

Makefile

@@ -43,13 +43,28 @@ ifeq ($(strip $(CURL_LIBS)),)
 CURL_LIBS := -lcurl
 endif
 
+# WebUI (HTTP + SSE front end): src/net.c src/http_srv.c src/web_md.c
+# src/webui.c. CST_WEBUI=0 swaps in the stub (--web then prints a hint).
+CST_WEBUI ?= 1
+
 PKG_CFLAGS := $(CURL_CFLAGS) $(CURSES_CFLAGS)
 PKG_LIBS := $(CURL_LIBS) $(CURSES_LIBS)
 
-CPPFLAGS += -Iinclude -I$(SD_DIR)/include -I$(CJSON_DIR) -D_XOPEN_SOURCE_EXTENDED $(PKG_CFLAGS)
+CPPFLAGS += -Iinclude -I.gen -I$(SD_DIR)/include -I$(CJSON_DIR) -D_XOPEN_SOURCE_EXTENDED $(PKG_CFLAGS)
 LDFLAGS += -L$(SD_DIR)
 LDLIBS += -lsashidown -lm $(PKG_LIBS) $(PTHREAD_LIBS)
 
+WEB_DIR := web
+WEB_ASSETS := $(wildcard $(WEB_DIR)/*.html) $(wildcard $(WEB_DIR)/*.js) \
+	$(wildcard $(WEB_DIR)/*.css) $(wildcard $(WEB_DIR)/*.svg)
+ifeq ($(CST_WEBUI),0)
+WEB_SRC := src/net.c src/http_srv.c src/web_md.c src/webui_stub.c
+# The stub body is guarded by this, so the switch has to define it too.
+CPPFLAGS += -DCST_NO_WEBUI=1
+else
+WEB_SRC := src/net.c src/http_srv.c src/web_md.c src/webui.c
+endif
+
 CORE_SRC = \
 	$(CJSON_DIR)/cJSON.c \
 	src/util.c \
@@ -60,7 +75,7 @@ CORE_SRC = \
 	src/sandbox_exec.c \
 	src/keymap.c \
 	src/skills.c \
-	src/extensions.c src/plugins.c src/mcp.c src/subagent.c \
+	src/extensions.c src/plugins.c src/mcp.c src/subagent.c src/attach.c src/clipboard.c \
 	src/session.c \
 	src/tools/tools.c \
 	src/tools/patch.c \
@@ -76,14 +91,16 @@ CORE_SRC = \
 	src/agent_loop.c \
 	src/agent_store.c \
 	src/json_baseline.c \
-	src/creds.c \
+	src/creds.c src/provider_switch.c \
 	src/mm_tool.c \
-	src/models.c \
-	src/metrics.c
+	src/models.c src/model_registry.c \
+	src/metrics.c \
+	$(WEB_SRC)
 
 SRC = $(CORE_SRC) src/textsel.c src/tui.c src/main.c
 OBJ = $(SRC:.c=.o)
-HDRS = $(wildcard include/*.h) $(wildcard src/tools/*.h) $(CJSON_DIR)/cJSON.h
+HDRS = $(wildcard include/*.h) $(wildcard src/tools/*.h) $(CJSON_DIR)/cJSON.h \
+	.gen/models_builtin.inc .gen/web_assets.inc
 
 TESTS = \
 	tests/test_ctl_frontier \
@@ -93,9 +110,11 @@ TESTS = \
 	tests/test_replay_real \
 	tests/test_mm_tool \
 	tests/test_llm_body \
+	tests/test_prefix_stable \
 	tests/test_sse_decode \
 	tests/test_apply_patch \
 	tests/test_session_roundtrip \
+	tests/test_attach \
 	tests/test_shell \
 	tests/test_diff \
 	tests/test_tools_fs \
@@ -103,6 +122,7 @@ TESTS = \
 	tests/test_undo \
 	tests/test_config \
 	tests/test_models \
+	tests/test_model_registry \
 	tests/test_sandbox \
 	tests/test_keymap \
 	tests/test_textsel \
@@ -116,8 +136,12 @@ TESTS = \
 	tests/test_win_utf8 \
 	tests/test_os_dir \
 	tests/test_tmpdir
+# test_webui drives the real server; there is nothing to test with the stub.
+ifneq ($(CST_WEBUI),0)
+TESTS += tests/test_webui
+endif
 
-TEST_LIBS = -lm $(CURL_LIBS) $(PTHREAD_LIBS)
+TEST_LIBS = -L$(SD_DIR) -lsashidown -lm $(CURL_LIBS) $(PTHREAD_LIBS)
 
 .PHONY: all clean check demo sashidown-lib FORCE cmake-gcc cmake-clang asan install uninstall
 
@@ -144,6 +168,16 @@ FORCE:
 cst-agent: $(OBJ) $(SD_DIR)/libsashidown.a
 	$(CC) $(CFLAGS) -o $@ $(OBJ) $(LDFLAGS) $(LDLIBS)
 
+# Built-in model data as a C byte list (included by model_registry.c).
+.gen/models_builtin.inc: src/models_builtin.json
+	@mkdir -p .gen
+	od -An -v -tx1 $< | sed 's/\([0-9a-f][0-9a-f]\)/0x\1,/g' > $@.tmp && mv $@.tmp $@
+
+# The WebUI shell is embedded the same way, one array per file.
+.gen/web_assets.inc: $(WEB_ASSETS) scripts/embed_web.sh
+	@mkdir -p .gen
+	@sh scripts/embed_web.sh $@ $(WEB_DIR)
+
 %.o: %.c $(HDRS)
 	$(CC) $(CFLAGS) $(CPPFLAGS) -c -o $@ $<
 
@@ -177,10 +211,14 @@ tests/test_markdown: tests/test_markdown.c $(SD_DIR)/libsashidown.a
 tests/test_%: tests/test_%.c $(CORE_SRC) $(HDRS)
 	$(CC) $(CFLAGS) $(CPPFLAGS) -o $@ $< $(CORE_SRC) $(TEST_LIBS)
 
+$(TESTS): sashidown-lib
+
 check: $(TESTS)
 	@set -e; for t in $(TESTS); do echo "== $$t"; ./$$t; done
 
 # AddressSanitizer + UBSan build of the agent and all tests.
+# Under a ptrace-based sandbox (some Termux setups) LeakSanitizer aborts with
+# "Tracer caught signal 11"; add ASAN_OPTIONS=detect_leaks=0 there.
 asan:
 	$(MAKE) clean
 	$(MAKE) sashidown-lib
@@ -190,7 +228,7 @@ demo: cst-agent
 	./cst-agent --demo-ctl --workspace .
 
 clean:
-	rm -f $(OBJ) cst-agent $(TESTS)
+	rm -f $(OBJ) cst-agent $(TESTS) .gen/models_builtin.inc .gen/web_assets.inc
 
 install: cst-agent
 	install -d "$(DESTDIR)$(PREFIX)/bin"

README.md

@@ -126,6 +126,23 @@ API Key：TUI 里输入并按 provider 保存到配置目录的 `credentials`（
 | Android Termux | aarch64 / … | Clang (Termux) | yes | ncurses（Termux 包） | `$PREFIX/bin/sh`；可旁路 busybox |
 | Windows 10 1903+ | x86_64 | MinGW-w64 GCC（UCRT） | yes | ncurses 6.6（Windows 控制台） | **捆绑 busybox-w32** |
 
+### WebUI（`--web`）
+
+同一个二进制内置一个 HTTP + SSE 前端：`cst-agent --web`（默认 `http://127.0.0.1:8787/`）。
+它和 TUI 是同一引擎的两个前端，浏览器里能流式看回答、点审批、切会话、贴图。
+协议是一份稳定的 JSON + SSE 接口，供以后的专用客户端复用。详见 [docs/webui.md](docs/webui.md)。
+
+```bash
+cst-agent --web                    # 本机浏览器打开 http://127.0.0.1:8787/
+cst-agent --web --web-port 0       # 端口交给系统，启动日志里给 URL
+cst-agent --web --web-dev ./web    # 开发前端：直接读目录，改完刷新
+cst-agent --web --web-host 0.0.0.0 --web-token 口令   # 手机/局域网访问
+sh scripts/e2e_webui.sh            # 用录制流跑完整轮次，不需要 API key
+```
+
+不带 TUI 的构建也可以开 WebUI（`cmake -DCST_BUILD_WEBUI=ON -DCST_BUILD_TUI=OFF`）；
+`-DCST_BUILD_WEBUI=OFF` 时 `--web` 只打印一条提示。
+
 ### Termux
 
 ```bash
@@ -171,6 +188,7 @@ Gitea Release `vVERSION`（同名资源会被替换）；仓库可设 `RELEASE_T
 | `minimax`（默认） | `https://api.minimax.cn/v1` | `MiniMax-M2.7` | `MINIMAX_API_KEY` |
 | `deepseek` | `https://api.deepseek.com/v1` | `deepseek-flash`（另有 `deepseek-v4-pro`） | `DEEPSEEK_API_KEY` |
 | `openai` | `https://api.openai.com/v1` | `gpt-4.1-mini` | `OPENAI_API_KEY` |
+| `teamorouter` | `https://api.teamorouter.com/v1` | 登录后自动取 `/models` 第一个（`/model` 可换） | `TEAMOROUTER_API_KEY` |
 
 | 用途 | 来源（优先级从高到低） |
 |---|---|
@@ -194,10 +212,10 @@ Gitea Release `vVERSION`（同名资源会被替换）；仓库可设 `RELEASE_T
 | `CST_MAX_STEPS` / `--max-steps` | 每个用户回合最多调用模型几次（30） |
 | `CST_TOOL_OUT_CAP` | 单个工具输出发给模型的字节上限（16384，保留头 60% + 尾 40%） |
 | `CST_CTX_WINDOW` | 发给模型的最近非 system 消息条数（80） |
-| `CST_CTX_TOKENS` / `CST_AUTO_COMPACT=0` | 覆盖模型上下文窗口大小 / 关闭自动压缩（用到 80% 时自动 `/compact`） |
+| `CST_CTX_TOKENS` / `CST_AUTO_COMPACT=0` | 覆盖模型上下文窗口大小 / 关闭自动压缩（用到 75% 时自动 `/compact`） |
 | `CST_NO_PROJECT_NOTES=1` | 不把工作区的 `AGENTS.md` 注入 system prompt |
 | `NO_COLOR` / `CST_ASCII=1` | 关闭颜色 / 强制 ASCII 图形（非 UTF-8 终端自动退化） |
-| `CST_SHELL_TIMEOUT` | `run_shell` 超时秒数（120），超时整组进程被杀，exit=124 |
+| `CST_SHELL_TIMEOUT` | `run_shell` 超时秒数（默认不限），设了才在超时后整组杀进程，exit=124 |
 | `CST_METRICS=0` / `CST_METRICS_PATH` | 关闭 / 指定计时埋点 JSONL（默认 `.agent/metrics/<session>.jsonl`） |
 | `CST_RECORD_SSE=DIR` / `CST_REPLAY_SSE=DIR` | 录制 / 回放原始 SSE 流（`NNNN.sse` + `NNNN.req.json`） |
 | `CST_APPROVAL=ask\|auto\|yolo` / `CST_SANDBOX=off\|landlock\|seccomp` | 审批模式 / 关闭沙箱（回落到只读白名单规则）或只用指定沙箱 |
@@ -276,16 +294,16 @@ TUI 中 `/tools off NAME`、`/tools on NAME` 可临时开关单个工具。
   `ask` / `auto` 的选择会记在 `settings.json`；`yolo` 只在本次运行有效。headless 行为不变（全部自动）。
 - **沙箱**（C 实现，`src/sandbox_exec.c`）：
   - Linux：Landlock（内核 5.13+，直接 syscall，无需 libseccomp）。子进程只能写工作区、临时目录、`/dev/null`、`/dev/tty`；
-    读和执行不受限。Landlock ABI ≥ 4（内核 6.7+）时同时禁止 TCP 连接和监听。
+    读、执行和联网不受限。
   - Linux 没有 Landlock 时（Android / Termux、WSL、老发行版；内核 5.5+，x86_64 / aarch64）：seccomp user-notify
     （界面显示 `auto · seccomp`）。子进程的写类系统调用（带写标志的 open、创建 / 删除 / 改名 / 链接 / chmod 等）先交给
-    agent 里的监督线程，按真实路径判断是否在工作区、临时目录或 `/dev/null` 等之内，不在就返回 `EACCES`；IPv4/IPv6 socket 一律拒绝。
+    agent 里的监督线程，按真实路径判断是否在工作区、临时目录或 `/dev/null` 等之内，不在就返回 `EACCES`。联网不受限。
     读、执行和已打开文件的写入不检查。它防的是误操作而不是恶意程序：检查之后内核会再读一次路径，多线程程序可以趁机换掉。
     探测还会确认能读直接子进程的内存；`ptrace_scope=2` 且无 `CAP_SYS_PTRACE` 时 seccomp 不会启用。
     比 shell 活得久的后台进程：桌面发行版开着 Yama（`ptrace_scope` ≥ 1）时它们的受检写入会被拒；命令结束后一律失败。
-  - macOS：`sandbox_init` profile，同样只放行工作区和临时目录写入，禁网。
+  - macOS：`sandbox_init` profile，同样只放行工作区和临时目录写入，不限制联网。
   - Windows 10 1903+：Low 完整性级别的受限令牌 + Job Object（界面显示 `auto · lowil`）。第一次在工作区运行时
-    给它打上 Low 标签，之后子进程只能写工作区和沙箱临时目录，读不到凭据文件；不限制联网，所以联网命令仍会询问。
+    给它打上 Low 标签，之后子进程只能写工作区和沙箱临时目录，读不到凭据文件；不限制联网。
     `/sandbox` 查看、`/sandbox reset-labels` 撤销标签，详见 [docs/README-windows.md](docs/README-windows.md)。
   - 更老的内核：没有沙箱，自动回落到规则判断（界面显示 `auto · rules`）。
   - `CST_SANDBOX=off` 强制关闭沙箱；`CST_SANDBOX=landlock` / `seccomp` / `lowil` 只用指定的那种。
@@ -301,7 +319,7 @@ TUI 中 `/tools off NAME`、`/tools on NAME` 可临时开关单个工具。
   `sudo`、`rm`、解释器（`python3 -c …`）等危险前缀不会被建议成规则。
 - **撤销**：每轮写文件前自动快照到 `.agent/undo/`，`/undo` 恢复上一轮改动的全部文件（新建的文件会被删除）。
 - **AGENTS.md**：工作区根目录的 `AGENTS.md` 会注入 system prompt；`/init` 让 agent 自己生成一份。
-- **自动压缩**：上一轮 prompt 用到模型上下文 80% 时，下一轮开始前自动总结历史（`CST_AUTO_COMPACT=0` 关闭）。
+- **自动压缩**：上一轮 prompt 用到模型上下文 75% 时，下一轮开始前自动总结历史（`CST_AUTO_COMPACT=0` 关闭）。
 
 ### 扩展：Skills、插件、MCP、子 agent
 
@@ -390,6 +408,7 @@ Thought（推理过程）默认折叠成一行“Thought · 3.2s”，生成中
 | `/diff [path]` * | `git status` + `git diff` |
 | `/compact` | 手动压缩上下文 |
 | `/export [file]` *、`/copy` * | 导出 Markdown 记录；复制上一条回复（OSC 52，需终端支持） |
+| `/web` * | 后台起一个 WebUI 进程（同 workspace、新会话，日志写到 `.agent/webui.log`） |
 | `/init` | 让 agent 写 `AGENTS.md` |
 | `/details` *、`/thinking [on\|off]`、`/keys` * | 展开全部 tool 输出；Thought 默认展开/折叠；快捷键列表 |
 | `/skills [reload\|list]`、`/skill <name> [任务]` | 浏览 skills；带着某个 skill 开始一轮 |

docs/README-windows.md

@@ -111,9 +111,8 @@ windows-x86_64/
   以及 Windows、Program Files、ProgramData 下面的目录打标签：在这些地方启动时，命令不会运行，
   界面会问是否在沙箱外重跑。请在项目目录里启动。
 - `/sandbox` 列出打过标签的目录；`/sandbox reset-labels` 恢复它们原来的标签。
-- 沙箱里可以读、执行用户能访问的文件（凭据文件除外），**不限制联网**。所以像联网的命令
-  （`curl`、`wget`、`ssh`、`git clone/fetch/pull/push`、`npm install`、`pip install`、
-  `winget install`、`Invoke-WebRequest` 等）在 `auto` 模式下仍然会弹窗确认。
+- 沙箱里可以读、执行用户能访问的文件（凭据文件除外），**不限制联网**：`curl`、`git pull`、
+  `npm install` 等联网命令在 `auto` 模式下也直接在沙箱里运行。
 - 命令像是被拦了（`Access is denied`、`拒绝访问`、`Permission denied` 等）时，会问
   “Rerun outside the sandbox?”：`y` 在沙箱外重跑一次，`p` 保存命令前缀规则并重跑，`n` 保留结果。
 - MSYS2 / Cygwin 的程序（包括 Git for Windows 自带的 `usr\bin` 工具）在 Low 级别下无法初始化

docs/compat.md

@@ -42,13 +42,14 @@ the `HAVE_MACOS_RUNNER` variable) or by hand with the checklist below.
 In the default `auto` approval mode, `run_shell` runs inside an OS sandbox
 when one is available. Commands may read and execute anything but may only
 write beneath the workspace, the temp directory, `/dev/null` and `/dev/tty`.
+The network is not restricted.
 
 | Platform | Sandbox | Notes |
 |---|---|---|
-| Linux 5.13+ | Landlock (raw syscalls, no extra library) | ABI ≥ 4 (6.7+) also blocks TCP connect/bind |
-| Linux 5.5+ without Landlock (Android / Termux, WSL, older distros), x86_64 / aarch64 | seccomp user-notify | refuses IPv4/IPv6 sockets; see below |
-| macOS | `sandbox_init` profile | also denies network |
-| Windows 10 1903+ | Low integrity restricted token + Job Object | writes need a Low label (given to the workspace once); network is not blocked, so network commands still ask; see `README-windows.md` |
+| Linux 5.13+ | Landlock (raw syscalls, no extra library) | |
+| Linux 5.5+ without Landlock (Android / Termux, WSL, older distros), x86_64 / aarch64 | seccomp user-notify | see below |
+| macOS | `sandbox_init` profile | |
+| Windows 10 1903+ | Low integrity restricted token + Job Object | writes need a Low label (given to the workspace once); see `README-windows.md` |
 | Older kernels | none | falls back to the read-only rules |
 
 The status bar and sidebar show `auto · landlock`, `auto · seccomp`,
@@ -165,7 +166,7 @@ Chinese VMs as Administrator, a standard user and a Chinese user name):
       keep CRLF and BOM; `run_shell` output in Chinese is readable on a
       936 system
 - [ ] `auto · lowil`: first command reports the label; `echo x > C:\outside`
-      asks to rerun; `curl ...` asks before running; `/sandbox reset-labels`
+      asks to rerun; `curl ...` runs without asking; `/sandbox reset-labels`
       restores the label
 - [ ] Esc during `sleep 30 & sleep 30` returns at once and leaves no
       `busybox.exe` behind

docs/env_openai.md

@@ -13,6 +13,7 @@ CST-Agent 使用 **OpenAI Chat Completions** 协议（`POST {base}/chat/completi
 | `minimax`（默认） | `https://api.minimax.cn/v1` | `MiniMax-M2.7` | `MINIMAX_API_KEY` |
 | `deepseek` | `https://api.deepseek.com/v1` | `deepseek-flash`（另有 `deepseek-v4-pro`） | `DEEPSEEK_API_KEY` |
 | `openai` | `https://api.openai.com/v1` | `gpt-4.1-mini` | `OPENAI_API_KEY` |
+| `teamorouter` | `https://api.teamorouter.com/v1` | 登录后自动取 `/models` 第一个（`/model` 可换） | `TEAMOROUTER_API_KEY` |
 
 显式给出的 `--api-base` / `--model` / 下表中的环境变量优先于预设。
 
@@ -72,7 +73,7 @@ export OPENAI_MODEL='your-model'
 | `CST_MAX_STEPS` | 每个用户回合最多调用模型几次（默认 30） |
 | `CST_TOOL_OUT_CAP` | 单个工具输出发给模型的字节上限（默认 16384） |
 | `CST_CTX_WINDOW` | 发给模型的最近非 system 消息条数（默认 80） |
-| `CST_SHELL_TIMEOUT` | `run_shell` 超时秒数（默认 120） |
+| `CST_SHELL_TIMEOUT` | `run_shell` 超时秒数（默认不限，Ctrl+C / 停止按钮仍可随时中断） |
 | `CST_METRICS=0` / `CST_METRICS_PATH` | 关闭 / 指定计时埋点 JSONL |
 | `CST_RECORD_SSE` / `CST_REPLAY_SSE` | 录制 / 回放原始 SSE 流目录；`CST_REPLAY_CHUNK` 控制回放分块字节数 |
 | `CST_MODELS` | `/model` 可选列表，`:` 或 `,` 分隔 |

docs/webui.md

@@ -0,0 +1,213 @@
+# WebUI（内置 HTTP + SSE 前端）
+
+`cst-agent --web` 让同一个进程同时提供命令行以外的前端：浏览器（或任何 HTTP 客户端）
+连上后能看到流式回答、工具卡片、审批弹窗和任务清单。它是 TUI 之外的第二个前端，
+**引擎没有为它改一行**——两边用的都是 `cst_agent_hooks_t` 这组回调。
+
+这份文档同时是**引擎 API v1 的规范**：以后专门客户端（Tauri / Qt / 移动端）直接照它实现，
+不需要读 C 代码。
+
+## 快速开始
+
+```bash
+# 默认只监听 127.0.0.1:8787
+cst-agent --web
+
+# 指定端口；0 = 让系统分配（启动日志里会打印实际 URL）
+cst-agent --web --web-port 8787
+
+# 让手机/另一台机器访问（必须给 token，否则拒绝启动在非 loopback 上）
+cst-agent --web --web-host 0.0.0.0 --web-token 我自己定的口令
+
+# 开发前端：直接从目录读 web/，改完刷新页面即可，不用重新编译
+cst-agent --web --web-dev ./web
+
+# 启动后自动打开浏览器
+cst-agent --web --web-open
+
+# 启动即跑一轮（不点页面也能用）
+cst-agent --web -p "看看这个仓库有什么问题"
+```
+
+启动日志：
+
+```
+webui: http://127.0.0.1:8787/
+webui: token 3f9a…  (append #token=3f9a… to the URL)
+```
+
+带 token 时把 `#token=…` 贴到浏览器地址栏后面即可（`#` 之后不会发给服务器，
+页面会用 `?token=` 再请求一次）。
+
+环境变量：`CST_WEB_PORT`、`CST_WEB_HOST`、`CST_WEB_TOKEN`、`CST_WEB_ROOT`。
+
+退出：终端里 Ctrl+C，或 `POST /api/quit`。
+
+## 安全模型
+
+| 场景 | 行为 |
+|---|---|
+| 默认 `127.0.0.1` | 不需要 token；`Host` 必须是 loopback（防 DNS rebinding）；带 `Origin` 的请求必须来自本页面自己（`http://<Host>`），否则 401 —— 防止任意网页跨站 POST 驱动 agent |
+| 静态资源 | 页面本身与 `app.js`/`style.css` 不需要 token；`/api/attach/<rel>` 图片仍要（页面会把 token 写进 `SameSite=Strict` cookie） |
+| 请求解析 | 鉴权与大小检查在读请求体**之前**完成；`Content-Length` 必须是纯数字且只有一个值；请求头整体 15 s 内收完 |
+| `--web-host 0.0.0.0` | 没给 `--web-token` 时自动生成随机 token 并打印；所有 `/api/*` 都要 token |
+| token 传递 | `Authorization: Bearer <t>`、`Cookie: cst_token=<t>` 或 `?token=<t>`（`EventSource` 不能设 header，所以查询参数是必需的一条路） |
+| 资源 | 只有白名单路由；路径里的 `..`/编码 NUL 一律 400；静态资源来自二进制内嵌（或 `--web-dev DIR`） |
+| 输出渲染 | 模型与工具输出都当不可信内容：Markdown 由服务端渲染，并经过标签/属性白名单（`javascript:` 链接、站外图片、`<script>` 全部丢弃） |
+| 请求体 | 默认 1 MiB，图片上传 32 MiB；超限 413 |
+
+**不要**把 WebUI 直接暴露到公网：没有 TLS，token 会以明文出现在网络里。需要远程访问时
+放在反向代理（https）后面，并确认 `X-Accel-Buffering: no` 之类的缓冲设置不会掐断 SSE。
+
+## 引擎 API（协议 `cst-webui/1`）
+
+所有响应都是 JSON（`Content-Type: application/json`）。`GET /api/state` 的
+`protocol` 字段给出版本号，客户端应当先看它再决定支持哪些端点。
+
+### 事件流
+
+```
+GET /api/events?since=<seq>      →  text/event-stream (chunked)
+```
+
+* 每条事件都有 `id: <seq>`（单调递增）与 `data: {"type":…,"seq":…, …}`。
+* 断线重连带上 `since=<最后收到的 seq>`（浏览器用 `Last-Event-ID` 也行），
+  服务端保留最近 2000 条，超出后从可用的最老一条开始；比当前 seq 还大（服务端重启过）
+  就当作新连接。
+* 新连接（不带 `since`）只收之后的事件；但若有尚未回答的 `permission`/`ask_user`，
+  会从那条事件开始补发，刷新页面不会丢掉正在等的问题。
+* 心跳是 SSE 注释 `: ping`（每秒一次，客户端忽略）。
+* `state` 事件在状态变化时整份重发，客户端可以直接替换本地状态。
+
+事件类型：
+
+| type | 字段 | 说明 |
+|---|---|---|
+| `state` | 见下表 | 会话/模型/审批/todo/用量快照 |
+| `status` | `message` | 引擎自己的一句话状态（"calling model (step 2)…"） |
+| `assistant_html` | `text` | **已渲染且已消毒的 HTML 片段**，按顺序追加 |
+| `assistant_delta` | `text` | 原始文本增量（逐字节真相，做复制/导出时用） |
+| `think_delta` | `text` | 推理过程增量（Thought） |
+| `tool` | `id`,`name`,`args`,`phase`,`detail` | `phase` = `open`/`ready`/`run`/`done` |
+| `tool_result` | `id`,`name`,`out`,`exit`,`bytes`,`truncated` | 完整输出被截到 32 KiB，`truncated=true` |
+| `todo` | `text` | `todo_write` 替换后的清单（一行一项） |
+| `permission` | `id`,`tool`,`detail`,`preview`,`sandbox`,`timeout` | 需要回答（见下）；`timeout` 秒后按拒绝处理 |
+| `permission_done` | `id`,`answer` | 问题已结束（超时/取消也会发） |
+| `ask_user` | `id`,`question`,`options[]` | 需要回答 |
+| `session` | `id` | 切换/新建了会话，客户端应重新拉 `/api/session` |
+| `turn_end` | `rc`,`error` | 本轮结束（`rc=0` 正常，非 0 见 `error`） |
+
+`state` 字段：`workspace` `session` `provider` `model` `effort` `approval`
+(`ask|auto|yolo`) `plan_mode` `protocol_tools` `status_busy` `todo`
+`context_tokens` `undo_available` `pending_images[]` `usage{requests,prompt_tokens,
+completion_tokens,cached_tokens,cache_miss_tokens,cost,priced,currency}`
+`turn_usage{…}`（上一轮，字段同 `usage`）`api_base` `key_set` `key_from`
+（`saved` / 环境变量名 / `session` / 空，**从不含 key 本身**）
+`model_info{label,context,vision,reasoning,source,price?}` `effort_applies`
+`sees_images`（1 / 0 / -1 未知）`max_steps` `tool_profile` `perm_timeout`。
+`cached_tokens` / `cache_miss_tokens` 来自上游的 prompt cache 统计，前端用它算命中率。
+
+`think_delta` / `assistant_delta` 的 `text` 总是完整的 UTF-8：上游在多字节字符中间
+断开时，残缺的尾巴留到下一块再发。
+
+### 请求
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/api/state` | 上面那份快照 |
+| GET | `/api/session?from=N` | 会话消息（`{messages:[…]}`，形状与 `.agent/sessions/*.jsonl` 一致；assistant 消息额外带 `html`） |
+| GET | `/api/sessions` | `{current, sessions:[{id,title,messages,mtime}]}` |
+| POST | `/api/sessions/new` | `{}` → `{id}` |
+| POST | `/api/sessions/switch` | `{"id":"…"}` |
+| POST | `/api/workspace` | `{"path":"/abs/dir"}` —— 换工作目录（权限规则/埋点/AGENTS.md 跟着换），并**在新目录里开一个新会话**（会话是按目录存的）；返回 `{id}`，坏路径 → 400 |
+| POST | `/api/turn` | `{"text":"…"}` → 202 `{ok:true}`；已有轮次在跑时 **409** |
+| POST | `/api/cancel` | `{}` —— 取消当前轮（不会杀进程）；挂起的权限问题按拒绝、提问按忽略处理 |
+| POST | `/api/permission` | `{"id":N,"answer":0\|1\|2\|3}` → deny / once / always-tool / always-prefix |
+| POST | `/api/ask_user` | `{"id":N,"text":"…"}` 或 `{"id":N,"dismiss":true}` |
+| POST | `/api/config` | `{model?,effort?,approval?,plan_mode?}`；先整体校验再生效，model/effort/approval（`yolo` 除外）写进 `settings.json`；当前模型不吃 effort 时回 `warning`；带 `provider` → 400（改用 `/api/provider`） |
+| GET | `/api/providers` | `{current, providers:[{name,api_base,model,has_key,key_from,key_env,source,current}]}` |
+| GET | `/api/models[?refresh=1]` | 当前提供商的模型：`{provider,current,api_base,key_set,api_count,models:[{id,api,label,context,vision,reasoning,source,price?}]}`；先用缓存，过期/缺失/`refresh=1` 时向 `/v1/models` 拉；key 被拒 → 401（仍带内置模型和 `auth:true`），其它失败放在 `api_error` |
+| POST | `/api/provider` | `{"name":"…","key":"…"?}`：切换提供商。缺 key → 400 `{need_key:true}`；key 被拒 → 401；没这个提供商 → 404；成功 → `{ok,provider,model,warning?}`，key 验证后存进 `credentials`（0600） |
+| POST | `/api/key` | `{"key":"…"}`：换当前提供商的 key，验证与回复同上 |
+| POST | `/api/undo` | 回滚最近一轮的文件改动，回 200 + 报告文本 |
+| POST | `/api/compact` | 手动压缩上下文 |
+| POST | `/api/attach?name=x.png` | 请求体是图片原始字节（≤32 MiB），进入"待发送"列表 |
+| DELETE | `/api/attach` | 清空待发送图片 |
+| GET | `/api/attach/<rel>` | 读回已存进会话的图片（`rel` 由消息的 `attach[].rel` 给出） |
+| POST | `/api/quit` | 关闭进程 |
+
+未命中路由 → `404 {"error":"not found"}`；需要 token 而没给 → `401`。
+轮次运行中（或另一个修改正在进行）时，`sessions/new`、`sessions/switch`、`workspace`、
+`undo`、`compact`、`attach`（上传/清空）、`provider`、`key` 以及改 `model/effort` 的
+`config` 一律 **409**；`approval`/`plan_mode` 可以中途改。
+
+key 只出现在请求体里：回复、事件、日志都不会带它。`/api/provider` 与 `/api/key`
+跟其它 `/api/*` 一样受 loopback 同源检查或 token 保护。
+
+### 客户端接入示例（10 行）
+
+```python
+import json, urllib.request
+base = "http://127.0.0.1:8787"
+def api(path, body=None, token=None):
+    req = urllib.request.Request(base + path, method="POST" if body is not None else "GET")
+    if token: req.add_header("Authorization", "Bearer " + token)
+    data = json.dumps(body).encode() if body is not None else None
+    return urllib.request.urlopen(req, data).read()
+api("/api/turn", {"text": "hello"})           # 之后读 /api/events 收流
+```
+
+### 空 body 的 POST
+
+`POST /api/cancel`、`/api/undo`、`/api/compact`、`/api/quit` 不需要 body。
+没有 `Content-Length` 头的 POST 按 RFC 9112 §6.3 视为**空 body**（`curl -X POST`
+正是这样发的），但该连接不再复用（服务端随后关闭它）：后面是否跟着未声明的
+字节无法判断。
+
+## 前端实现（web/）
+
+没有构建步骤：`web/index.html` + `web/app.js` + `web/style.css` 是纯 ES module，
+编译时被 `scripts/embed_web.sh` 塞进二进制（`.gen/web_assets.inc`，跟内置模型数据同一招），
+所以 Windows 发布包依旧是单个 exe。`--web-dev DIR` 可以绕过内嵌版本直接读目录。
+
+Markdown 在**服务端**渲染（复用 TUI 用的 sashidown 流式 API），客户端只贴 HTML；
+因此不需要引入任何 JS 依赖，也顺带保证了"只发送已确认的 HTML"。
+
+界面本身：左栏可收（顶栏按钮 / `?side=0`），右栏可收（`?panel=0`），主题 `?theme=dark|light`；
+三个开关都会记进 `localStorage`，带查询参数时以参数为准。空状态只留一句提示，第一轮
+对话开始后自动隐去；右栏只给三件事——任务清单、本轮文件改动行数（`+N −M`）、上下文
+占用与 prompt cache 命中率。布局类在页面脚本之前就写进 `<body>`，避免首帧闪一下再收起。
+
+TUI 里打 `/web` 会另起一个 WebUI 进程（`--web --workspace <当前目录> --new`），
+日志在 `<workspace>/.agent/webui.log`：TUI 不能被 `cst_webui_run()` 的阻塞循环占住，
+而且两个进程同时写一个会话文件会把它写坏，所以子进程总是开新会话。
+
+自动压缩的门槛是模型上下文窗口的 **75%**（`CST_CTX_BUDGET` 可覆盖）；到点后下一轮
+开始前先总结历史，而不是等到塞满。
+
+## 测试
+
+```bash
+make check                        # 含 tests/test_webui（HTTP/SSE/鉴权/消毒）
+sh scripts/e2e_webui.sh          # 用录制流跑完整轮次 + 权限往返，不需要 API key
+                                  # （含 e2e_webui_settings.py：假 /v1/models、换提供商/key、中文思考流）
+sh scripts/e2e_webui.sh tests/fixtures/sse/deepseek-ctl ctl
+```
+
+手工验收清单（浏览器）：
+
+1. 打开首页 → 顶部显示 workspace/模型/审批模式，右下状态"就绪"。
+2. 输入一句话 → 助手气泡逐字出现；工具卡片自动展开、结束后带 `exit=` 标记。
+3. 切到 `ask` 审批 → 写文件时弹窗；点"允许一次"后继续，点"拒绝"则该工具返回失败但对话继续。
+4. `会话` 按钮：新建/切换后历史正确重建（刷新页面也一样）。
+5. 拖入一张图片 → 底部出现待发送提示，发送后历史里能看到图。
+6. 关掉标签页再打开 → 事件流自动续传，不丢已完成的消息。
+
+## 限制与已知问题
+
+* 同一会话同时只能有一轮（`POST /api/turn` 返回 409）；TUI 与 WebUI 目前是
+  **二选一**（`--web` 时不启动 TUI），同进程并存留待后续的 hooks 分发层。
+* 一个会话文件只能由一个进程写：不要同时用 TUI 打开 WebUI 正在用的那个 workspace。
+* 没有 WebSocket；服务端→客户端用 SSE，客户端→服务端用 POST。够用且穿透代理更容易。
+* 事件环只有 2000 条：断线太久（超过这个窗口）的客户端会从当前可用的最老事件开始，
+  这时应当重新拉一次 `/api/session`。

include/cst_agent.h

@@ -4,6 +4,7 @@
 #include "ctl.h"
 
 #include <stddef.h>
+#include <time.h>
 
 #ifdef __cplusplus
 extern "C" {
@@ -11,7 +12,6 @@ extern "C" {
 
 #define CST_AGENT_MAX_MSG 256
 #define CST_AGENT_MAX_CONTENT (512 * 1024)
-#define CST_AGENT_CTX_WINDOW 80 /* max non-system msgs sent to LLM */
 #define CST_DEFAULT_MAX_STEPS 30
 #define CST_DEFAULT_TOOL_OUT_CAP (16 * 1024)
 
@@ -47,6 +47,19 @@ int cst_protocol_is_text(cst_protocol_t p);
 /* Eager protocols execute a call during the stream, at confirmation time. */
 int cst_protocol_is_eager(cst_protocol_t p);
 
+/* One image carried by a message (see cst_attach.h). The bytes live beside
+ * the session; this is the metadata plus the name of the stored copy. */
+typedef struct {
+  char id[32];      /* unique inside the session ("img-1a2b3c4d") */
+  char name[256];   /* display name (original file name) */
+  char mime[32];    /* image/png, image/jpeg, image/gif, image/webp, image/bmp */
+  char rel[256];    /* file name inside the session's attachment directory */
+  long long bytes;  /* stored size */
+  int width, height; /* pixels, 0 when the header could not be read */
+  char detail[8];   /* auto | low | high (wire hint, "" = auto) */
+  char origin[32];  /* user | view_image | mcp (for display only) */
+} cst_attachment_t;
+
 typedef struct {
   cst_role_t role;
   char *content;
@@ -55,6 +68,10 @@ typedef struct {
   char tool_name[CTL_MAX_NAME];
   char *tool_calls_json; /* assistant: OpenAI tool_calls array JSON, or NULL */
   char *meta_json;       /* optional JSON object (kind, protocol, ...) */
+  cst_attachment_t *attach; /* images shown with this message, or NULL */
+  int nattach;
+  char *reasoning; /* assistant: reasoning_content as streamed, or NULL */
+  int prefix;      /* wire only: assistant prefix the model continues */
 } cst_message_t;
 
 typedef struct {
@@ -149,6 +166,10 @@ typedef struct {
   char *out;
   size_t out_len;
   int exit_code;
+  /* Images the tool produced for the model (view_image, image-returning MCP
+   * tools). cst_tool_result_free releases them. */
+  cst_attachment_t *attach;
+  int nattach;
 } cst_tool_result_t;
 
 void cst_tool_result_free(cst_tool_result_t *r);
@@ -200,7 +221,9 @@ typedef struct {
   char finish_reason[32];
   long prompt_tokens;
   long completion_tokens;
-  long cached_tokens;
+  long cached_tokens;      /* prompt tokens read from the provider's cache */
+  long cache_miss_tokens;  /* prompt tokens billed at the full input price */
+  long cache_write_tokens; /* prompt tokens written to the cache (Anthropic) */
   double t_first_byte_ms; /* relative to request start; -1 if none */
   double t_end_ms;
   int client_stopped; /* stream ended by stop_flag (not an error) */
@@ -222,8 +245,15 @@ typedef struct {
   void *userdata;
   int enable_tools;     /* send tools[] schema */
   const cst_agent_config_t *tool_cfg; /* active tool set; NULL = all */
+  const char *tools_json; /* tools[] sent verbatim (frozen); NULL = tool_cfg */
   int tool_choice_none; /* "tool_choice":"none" */
+  int send_reasoning;   /* assistant reasoning goes back as reasoning_content */
+  int cache_style;      /* CST_CACHE_* hints to add */
+  const char *cache_key; /* prompt_cache_key (CST_CACHE_OPENAI) */
+  const char *cache_ttl; /* cache_control ttl (CST_CACHE_ANTHROPIC); NULL = 5m */
+  int images_off; /* the model does not take images: send a note instead */
   size_t tool_out_cap;  /* wire cap for role=tool content; 0 = default */
+  const char *session_path; /* where stored images live; NULL = none */
   volatile int *cancel_flag; /* non-zero → abort (error "cancelled") */
   volatile int *stop_flag;   /* non-zero → stop reading, not an error */
   cst_llm_stats_t *stats;    /* optional */
@@ -291,9 +321,34 @@ cst_agent_config_t *cst_agent_config_mut(cst_agent_t *a);
 void cst_agent_request_cancel(cst_agent_t *a);
 int cst_agent_new_session(cst_agent_t *a, char *id_out, size_t id_sz);
 int cst_agent_switch_session(cst_agent_t *a, const char *id);
+/* Re-root the agent at another directory. Per-workspace state (permission
+ * rules, metrics, project notes) follows, the system prompt is rebuilt and the
+ * token budget is re-measured. The session is not touched: the caller decides
+ * whether to keep it or start a new one. */
+int cst_agent_set_workspace(cst_agent_t *a, const char *path, char *err,
+                            size_t err_sz);
 int cst_agent_compact(cst_agent_t *a, char *err, size_t err_sz);
 /* Bare id of the current session (file name without .jsonl). */
 void cst_agent_session_id(const cst_agent_t *a, char *out, size_t out_sz);
+/* Transcript path of the current session (images are stored beside it). */
+const char *cst_agent_session_path(const cst_agent_t *a);
+/* Images picked for the next user message (/attach). They ride along with the
+ * next cst_agent_run_turn*() call and are then part of the session.
+ * cst_agent_attach_file copies the file into the session store; *err gets a
+ * short reason on failure (-1). */
+int cst_agent_attach_file(cst_agent_t *a, const char *path, char *err,
+                          size_t err_sz);
+/* Same for bytes already in memory (clipboard); name is display-only. */
+int cst_agent_attach_bytes(cst_agent_t *a, const char *name, const char *data,
+                           size_t n, char *err, size_t err_sz);
+/* Whether the current model is shown images: 1 yes, -1 unknown (tried; a
+ * 400 turns sending off), 0 no (images go as text notes). */
+int cst_agent_sees_images(const cst_agent_t *a);
+int cst_agent_pending_count(const cst_agent_t *a);
+/* One line "<name> (<mime>, 12 KB)"; -1 when i is out of range. */
+int cst_agent_pending_describe(const cst_agent_t *a, int i, char *out,
+                               size_t out_sz);
+void cst_agent_pending_clear(cst_agent_t *a);
 /* Latest todo_write list of this session, or NULL. */
 const char *cst_agent_todo(const cst_agent_t *a);
 /* AGENTS.md (or CST.md) text injected into the system prompt, or NULL. */
@@ -311,6 +366,19 @@ void cst_agent_undo_key(const cst_agent_t *a, char *sid, size_t sid_sz,
                         char *tag, size_t tag_sz);
 /* Last prompt_tokens reported by the model (0 if unknown). */
 long cst_agent_last_prompt_tokens(const cst_agent_t *a);
+/* Token use since the session was opened, and of the latest turn. */
+typedef struct {
+  int requests;
+  long prompt, cached, miss, write, out;
+  double cost;      /* in currency; valid when priced */
+  int priced;       /* every request had a known price */
+  char currency[8];
+} cst_usage_t;
+void cst_agent_usage(const cst_agent_t *a, cst_usage_t *session,
+                     cst_usage_t *turn);
+/* "[cst] ..." notes the agent appends when Plan mode, approval, branch,
+ * date or AGENTS.md change mid-session (the system prompt stays frozen). */
+int cst_message_is_note(const cst_message_t *m);
 
 const char *cst_agent_system_prompt(void);
 const char *cst_agent_system_prompt_for(cst_protocol_t p);
@@ -384,6 +452,39 @@ const cst_provider_t *cst_provider_at(int i);
 /* Context window of a model in tokens (CST_CTX_TOKENS overrides). */
 long cst_model_context_tokens(const char *model);
 
+/* How a provider caches prompt prefixes.
+ *   auto      : implicit prefix cache, nothing to send (DeepSeek, MiniMax...)
+ *   openai    : implicit, routed by "prompt_cache_key"
+ *   anthropic : explicit "cache_control" breakpoints on content parts */
+typedef enum {
+  CST_CACHE_AUTO = 0,
+  CST_CACHE_OPENAI,
+  CST_CACHE_ANTHROPIC
+} cst_cache_style_t;
+typedef struct {
+  int cache_style;        /* cst_cache_style_t */
+  int reasoning_passback; /* history keeps reasoning_content (DeepSeek) */
+  int prefix_completion;  /* assistant "prefix": true via <base>/beta */
+  int vision;             /* 1 takes images, 0 text only, -1 unknown */
+} cst_model_caps_t;
+/* CST_NO_CACHE_HINTS=1 forces CST_CACHE_AUTO. */
+void cst_model_caps(const char *provider, const char *api_base,
+                    const char *model, cst_model_caps_t *out);
+
+/* Prices per million tokens. CST_PRICE="miss,hit,out[,write[,currency]]"
+ * overrides the built-in table. */
+typedef struct {
+  char currency[8]; /* "¥", "$" */
+  double miss, hit, write, out;
+  int offpeak_half; /* DeepSeek: half price outside Beijing peak hours */
+} cst_price_t;
+/* 0 when a price is known for model, -1 otherwise. */
+int cst_model_price(const char *model, cst_price_t *out);
+/* DeepSeek peak hours: Beijing time Mon-Fri 9:00-12:00 and 14:00-18:00. */
+int cst_price_is_peak(time_t when);
+double cst_price_cost(const cst_price_t *p, long miss, long hit, long write,
+                      long out, time_t when);
+
 /* Reasoning effort: low | medium | high | max. */
 #define CST_DEFAULT_EFFORT "medium"
 int cst_effort_valid(const char *effort);

include/cst_attach.h

@@ -0,0 +1,81 @@
+#ifndef CST_ATTACH_H
+#define CST_ATTACH_H
+
+#include "cst_agent.h"
+
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* --- image attachments ---------------------------------------------------
+ * An attachment is a validated copy of an image file, stored beside the
+ * session so the bytes a model is shown stay the bytes that were picked.
+ * Only the metadata travels in the JSONL; the bytes are encoded into the
+ * request when it is built. */
+
+/* Supported: PNG, JPEG, GIF, WebP, BMP (static images). */
+#define CST_ATTACH_MAX_BYTES (16 * 1024 * 1024) /* one stored image */
+#define CST_ATTACH_MAX_TOTAL (32 * 1024 * 1024) /* per request */
+#define CST_ATTACH_MAX_COUNT 8                  /* per message */
+
+/* Magic-byte test: 0 and a canonical mime when data holds a supported
+ * image, -1 otherwise (an extension alone never decides). */
+int cst_attach_sniff(const void *data, size_t n, char *mime, size_t mime_sz);
+/* Pixel size from the header when it is readable; 0 for unknown. */
+int cst_attach_dimensions(const void *data, size_t n, int *w, int *h);
+
+/* A stored file name as store() makes it ("<id>.<ext>"); rejects anything
+ * that could leave the attachment directory. */
+int cst_attach_rel_ok(const char *rel);
+/* Directory holding this session's stored images (created on demand). */
+int cst_attach_dir(const char *session_path, char *out, size_t out_sz);
+/* Absolute path of a stored image (0 / -1). */
+int cst_attach_full_path(const char *session_path, const cst_attachment_t *a,
+                         char *out, size_t out_sz);
+
+/* Read src_path, verify it is a supported image within limits, and copy it
+ * into the session's attachment directory. Returns a malloc'd entry the
+ * caller owns (cst_attach_free), or NULL with err filled. */
+cst_attachment_t *cst_attach_import_file(const char *session_path,
+                                         const char *src_path, char *err,
+                                         size_t err_sz);
+/* Store already-read bytes (clipboard, downloads); name is display-only. */
+cst_attachment_t *cst_attach_import_bytes(const char *session_path,
+                                          const char *name, const char *data,
+                                          size_t n, char *err, size_t err_sz);
+
+/* Validate and read back a stored image, or NULL when it is gone. */
+char *cst_attach_read(const char *session_path, const cst_attachment_t *a,
+                      size_t *out_len, char *err, size_t err_sz);
+/* "data:image/png;base64,...." for the wire; NULL when the file is gone. */
+char *cst_attach_data_url(const char *session_path, const cst_attachment_t *a);
+/* "1920x1080 PNG 412 KB" style one-liner for prompts and the UI. */
+void cst_attach_describe(const cst_attachment_t *a, char *out, size_t out_sz);
+
+void cst_attach_free(cst_attachment_t *a);
+/* Free a list of n entries allocated as separate blocks. */
+void cst_attachments_free(cst_attachment_t *list, int n);
+/* Deep copy (NULL on OOM or when n <= 0). */
+cst_attachment_t *cst_attachments_dup(const cst_attachment_t *list, int n);
+/* Append src to *list (grows with realloc). 0 / -1. */
+int cst_attachments_push(cst_attachment_t **list, int *n, int *cap,
+                         const cst_attachment_t *src);
+
+/* JSON array of n attachments for the session JSONL (malloc'd), or NULL. */
+char *cst_attachments_to_json(const cst_attachment_t *list, int n);
+/* Parse a JSON array; caller frees with cst_attachments_free. */
+cst_attachment_t *cst_attachments_from_json(const void *array_json, int *n_out);
+
+/* Base64 of n bytes (malloc'd, no line breaks). */
+char *cst_base64_encode(const void *data, size_t n);
+/* Standard or URL-safe base64 (whitespace ignored) to bytes; malloc'd,
+ * NULL on a bad character. */
+char *cst_base64_decode(const char *s, size_t n, size_t *out_len);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

include/cst_clipboard.h

@@ -0,0 +1,35 @@
+#ifndef CST_CLIPBOARD_H
+#define CST_CLIPBOARD_H
+
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Image bytes on the system clipboard (PNG, or BMP from a Windows DIB).
+ * Wayland: wl-paste; X11: xclip; macOS: pngpaste or osascript; Windows: the
+ * clipboard API. Returns 0 with *data malloc'd, or -1 with err filled in
+ * ("no image on the clipboard", "install wl-clipboard", ...). */
+int cst_clipboard_image(char **data, size_t *n, char *err, size_t err_sz);
+
+/* Windows CF_DIB bytes (BITMAPINFOHEADER + pixels) as an image file: a PNG
+ * for uncompressed 24/32-bit bitmaps, else a BMP. NULL when malformed. */
+char *cst_dib_to_image(const void *dib, size_t sz, size_t *n);
+
+#define CST_PASTE_MAX_PATHS 8
+#define CST_PASTE_PATH_MAX 1024
+
+/* Split pasted text into file paths the way terminals paste dropped files:
+ * whitespace- or newline-separated, '...' / "..." quoting, file:// URIs
+ * (percent-decoded) and, outside Windows, backslash escapes. Returns the
+ * count, or -1 when the text is empty or holds more than max paths. Whether
+ * the paths exist is up to the caller. */
+int cst_paste_paths(const char *text, size_t len,
+                    char out[][CST_PASTE_PATH_MAX], int max);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

include/cst_http.h

@@ -0,0 +1,108 @@
+#ifndef CST_HTTP_H
+#define CST_HTTP_H
+
+/* A small HTTP/1.1 server for the built-in WebUI (src/http_srv.c).
+ *
+ * Only what a local single-page app needs: exact-match routes, keep-alive,
+ * fixed-length bodies and chunked streaming responses (SSE). No TLS, no
+ * HTTP/2, no chunked *request* bodies, no CGI. Every connection is served
+ * by its own thread; a handler may keep the connection as long as it wants
+ * (that is how the event stream works). */
+
+#include "cst_net.h"
+
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct cst_http_conn cst_http_conn_t;
+
+typedef struct {
+  char method[8];  /* GET / POST / DELETE ... */
+  char path[1024]; /* percent-decoded, without the query string */
+  char query[1024]; /* raw, without '?' */
+  const char *body; /* NUL-terminated; may hold binary bytes */
+  size_t body_len;
+  /* Headers of interest, NULL when absent (pointers into the request). */
+  const char *authorization;
+  const char *cookie;
+  const char *origin;
+  const char *host;
+  const char *content_type;
+  const char *user_agent;
+  const char *last_event_id; /* an EventSource reconnecting */
+  int keep_alive;
+} cst_http_req_t;
+
+/* 0 = handled (a response was sent), -1 = not found (the server replies). */
+typedef int (*cst_http_fn)(cst_http_conn_t *c, void *ud);
+
+typedef struct {
+  const char *method; /* "*" matches any */
+  const char *path;   /* exact; "*" = fallback (try last) */
+  cst_http_fn fn;
+  void *ud;
+  int auth;         /* ask the auth hook before the handler */
+  size_t max_body;  /* request body cap; 0 = server default */
+} cst_http_route_t;
+
+typedef struct {
+  const char *host; /* NULL/"" = 127.0.0.1 */
+  int port;         /* 0 = pick a free port */
+  size_t max_body;  /* default 1 MiB */
+  int max_conn;     /* default 32 */
+  int read_timeout_ms; /* waiting for the request headers (default 15000) */
+  int idle_timeout_ms; /* keep-alive pause between requests (default 60000) */
+  const cst_http_route_t *routes;
+  int nroutes;
+  /* 0 = allow, -1 = the server answers 401 before the handler runs. */
+  int (*auth)(const cst_http_req_t *req, void *ud);
+  void *auth_ud;
+  /* One line per request, e.g. "GET /api/state -> 200". */
+  void (*on_log)(const char *line, void *ud);
+  void *log_ud;
+} cst_http_opts_t;
+
+typedef struct cst_http_server cst_http_server_t;
+
+/* Start listening. NULL on failure with a reason in err. */
+cst_http_server_t *cst_http_start(const cst_http_opts_t *o, char *err,
+                                  size_t err_sz);
+int cst_http_port(const cst_http_server_t *s);
+/* Non-zero once stop() was called: long-lived handlers must return. */
+int cst_http_stopping(const cst_http_server_t *s);
+/* Close the listener and every connection, then wait (30 s at most) for the
+ * handler threads. Returns how many still run: their ud must stay alive. */
+int cst_http_stop(cst_http_server_t *s);
+/* Does nothing while handlers still run on s. */
+void cst_http_free(cst_http_server_t *s);
+
+/* --- inside a handler --- */
+const cst_http_req_t *cst_http_request(cst_http_conn_t *c);
+int cst_http_send(cst_http_conn_t *c, int status, const char *ctype,
+                  const void *body, size_t n);
+int cst_http_send_str(cst_http_conn_t *c, int status, const char *ctype,
+                      const char *s);
+/* json may be NULL (then "null" is sent); it is copied, not owned. */
+int cst_http_send_json(cst_http_conn_t *c, int status, const char *json);
+/* {"error":"..."} */
+int cst_http_send_err(cst_http_conn_t *c, int status, const char *msg);
+/* True once a response (or stream) began for this request. */
+int cst_http_sent(const cst_http_conn_t *c);
+
+/* Chunked response: begin(), any number of write()s, end(). */
+int cst_http_stream_begin(cst_http_conn_t *c, const char *ctype);
+int cst_http_stream_write(cst_http_conn_t *c, const void *data, size_t n);
+int cst_http_stream_end(cst_http_conn_t *c);
+
+/* Query parameter, percent-decoded ('+' = space). 0 when found. */
+int cst_http_query(const cst_http_req_t *req, const char *key, char *out,
+                   size_t out_sz);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* CST_HTTP_H */

include/cst_keymap.h

@@ -64,6 +64,7 @@ typedef enum {
   CST_KA_COMPACT,
   CST_KA_COPY,
   CST_KA_EXPORT,
+  CST_KA_PASTE_IMAGE,
   /* model */
   CST_KA_MODEL,
   CST_KA_PROVIDER,

include/cst_models.h

@@ -0,0 +1,92 @@
+#ifndef CST_MODELS_H
+#define CST_MODELS_H
+
+/* Model registry: what cst-agent knows about providers and models.
+ *
+ * Three layers, highest first, merged field by field:
+ *   1. <config>/models.json        user overrides and extra providers
+ *   2. <config>/models-cache/<provider>.json   GET /models metadata, exact id
+ *   3. built-in data (src/models_builtin.json, embedded at build time)
+ * then defaults (128000 tokens, vision unknown). Model rules match the name
+ * without its "vendor/" prefix, case-insensitively: a plain "match" is a
+ * prefix, one with '*' is a glob, one with '/' is tested against the full
+ * id. Within a layer the most specific rule (most literal characters) that
+ * sets a field wins, so table order does not matter.
+ *
+ * CST_CTX_TOKENS, CST_PRICE, CST_MODELS and CST_NO_CACHE_HINTS still
+ * override everything. */
+
+#include "cst_agent.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct {
+  long context;    /* tokens */
+  int vision;      /* 1 takes images, 0 text only, -1 unknown */
+  int cache_style; /* cst_cache_style_t */
+  int reasoning;   /* takes OpenAI-style reasoning_effort */
+  int has_price;
+  cst_price_t price;
+  /* Layers that supplied anything, highest first: "user+api+built-in",
+   * "default", "env+built-in"... */
+  char source[48];
+} cst_model_info_t;
+
+/* provider may be NULL: then every provider's fetched cache is searched. */
+void cst_model_info(const char *provider, const char *model,
+                    cst_model_info_t *out);
+/* Short picker label: "1M · vision", "200K · text only", "128K". */
+void cst_model_info_label(const cst_model_info_t *mi, char *out, size_t n);
+
+/* One entry of GET /models, with the optional OpenRouter-style metadata. */
+typedef struct {
+  char id[128];
+  long context;  /* 0 = not given */
+  int vision;    /* -1 = not given */
+  int has_price; /* prices in USD per 1M tokens */
+  double miss, hit, write, out;
+} cst_model_meta_t;
+
+/* Like cst_llm_list_models, keeping context_length,
+ * architecture.input_modalities (or modalities) and pricing when present. */
+int cst_llm_list_models_meta(const char *api_base, const char *api_key,
+                             cst_model_meta_t *out, int max_out, char *err,
+                             size_t err_sz);
+
+#define CST_MODELS_CACHE_TTL (24L * 3600)
+
+/* Store a fetched list as <config>/models-cache/<provider>.json and use it
+ * from now on. 0 / -1. */
+int cst_models_cache_save(const char *provider, const char *api_base,
+                          const cst_model_meta_t *list, int n);
+/* The cached list for provider: count (up to max), or -1 when there is
+ * none. *age_s gets the seconds since it was fetched. */
+int cst_models_cache_load(const char *provider, cst_model_meta_t *out, int max,
+                          long *age_s);
+
+/* The "models" a provider entry lists (built-in or user file). */
+int cst_provider_models(const cst_provider_t *p, char out[][128], int max);
+/* Where a provider entry came from: "built-in" or "user". */
+const char *cst_provider_source(const cst_provider_t *p);
+/* The user file's path (it may not exist). */
+int cst_models_user_path(char *out, size_t out_sz);
+
+/* Drop everything and read the built-in data, the user file and the caches
+ * again. Provider pointers stay valid but may name another provider. */
+void cst_models_reload(void);
+/* Tests: load these documents instead of the built-in data and the user
+ * file (NULL = none). Caches still come from <config>. 0, or -1 with err. */
+int cst_models_load_json(const char *builtin_json, const char *user_json,
+                         char *err, size_t err_sz);
+/* The embedded built-in document. */
+const char *cst_models_builtin_json(void);
+/* Problems found while loading (bad user file...), or "". */
+const char *cst_models_load_error(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

include/cst_net.h

@@ -0,0 +1,68 @@
+#ifndef CST_NET_H
+#define CST_NET_H
+
+/* Minimal TCP sockets for the embedded HTTP server (src/net.c).
+ *
+ * The point of this layer is that src/http_srv.c and src/webui.c never
+ * include a socket header: Unix file descriptors and Windows SOCKETs differ
+ * in type, close() and error reporting, and Windows needs WSAStartup before
+ * anything works. */
+
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifdef _WIN32
+typedef intptr_t os_socket_t;
+#define OS_SOCKET_BAD ((os_socket_t)-1)
+#else
+typedef int os_socket_t;
+#define OS_SOCKET_BAD (-1)
+#endif
+
+/* Longest "address:port" os_net_peer writes (IPv6 hosts are bracketed so a
+ * URL built from it stays unambiguous). */
+#define OS_NET_ADDR_MAX 64
+
+/* Winsock startup (no-op on Unix, which also ignores SIGPIPE so a client
+ * that hangs up cannot kill the process). 0 / -1. */
+int os_net_init(void);
+void os_net_cleanup(void);
+
+/* Bind and listen on host:port. host may be NULL/"" (then "127.0.0.1"),
+ * "0.0.0.0"/"::" (every interface) or any literal address / name; port 0
+ * picks a free one. Returns the listening socket, or OS_SOCKET_BAD with a
+ * short reason in err. */
+os_socket_t os_net_listen(const char *host, int port, char *err, size_t err_sz);
+/* The port actually bound (0 when unknown). */
+int os_net_port(os_socket_t s);
+/* A one-line "host:port" for messages. */
+void os_net_peer(os_socket_t s, char *out, size_t out_sz);
+
+/* Connect to host:port, waiting up to timeout_ms: the socket, or
+ * OS_SOCKET_BAD. Used by the tests and by anything that drives the WebUI
+ * API from inside the process. */
+os_socket_t os_net_connect(const char *host, int port, int timeout_ms);
+
+/* Accept one connection, waiting up to timeout_ms (<0 = forever).
+ * Returns the socket, OS_SOCKET_BAD on error, or OS_SOCKET_BAD with
+ * *timed_out set when the wait ran out. */
+os_socket_t os_net_accept(os_socket_t s, int timeout_ms, int *timed_out);
+
+/* Read at most n bytes, waiting up to timeout_ms: bytes read, 0 at EOF,
+ * -1 on error, -2 when nothing arrived in time. */
+long os_net_recv(os_socket_t s, void *buf, size_t n, int timeout_ms);
+/* Write everything (timeout_ms per call): 0 / -1. */
+int os_net_send_all(os_socket_t s, const void *buf, size_t n, int timeout_ms);
+/* Wake up a thread blocked in recv/send on this socket (shutdown, no close). */
+void os_net_shutdown(os_socket_t s);
+void os_net_close(os_socket_t s);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* CST_NET_H */

include/cst_provider_switch.h

@@ -0,0 +1,79 @@
+#ifndef CST_PROVIDER_SWITCH_H
+#define CST_PROVIDER_SWITCH_H
+
+/* Model lists, API keys and provider switches, shared by the TUI and the
+ * WebUI so both front ends validate and persist the same way.
+ *
+ * A key is checked with GET /models: a 401/403 (CST_MODELS_AUTH) rejects
+ * it, any other failure (offline, no /models route) lets it through
+ * unverified. A key that passes is saved to <config>/credentials. Keys are
+ * never copied into err. */
+
+#include "cst_agent.h"
+#include "cst_models.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define CST_PS_MAX_MODELS 512
+#define CST_PS_UNKNOWN (-1)   /* no such provider */
+#define CST_PS_NEED_KEY (-10) /* no key given, none saved or in the env */
+/* Non-negative results are flags: */
+#define CST_PS_UNVERIFIED 1 /* /models failed for another reason; err says */
+#define CST_PS_UNSAVED 2    /* the credentials file could not be written */
+
+typedef struct {
+  char id[128];
+  int api; /* listed by the provider's /models (else built-in only) */
+  cst_model_info_t info;
+} cst_ps_model_t;
+
+/* GET /models; a good answer refreshes models-cache/<provider>.json. The
+ * count, CST_MODELS_AUTH, or another negative value with err set. */
+int cst_ps_fetch(const char *provider, const char *api_base, const char *key,
+                 char ids[][128], int max, char *err, size_t err_sz);
+/* The cached list: count, or -1; *fresh when younger than the TTL. */
+int cst_ps_cached(const char *provider, char ids[][128], int max, int *fresh);
+
+/* Base URL for provider: cfg's own when it is the current provider (it may
+ * be overridden), else the preset's; "" when unknown. */
+const char *cst_ps_base(const cst_agent_config_t *cfg, const char *provider);
+
+/* The model picker list for cfg's provider: the API's ids (the cache while
+ * it is fresh, else a fetch; refresh always fetches) followed by the
+ * built-in names it did not list. *api_rc gets the fetch result (count,
+ * CST_MODELS_AUTH, -1 with err) or the cached count. Returns the count. */
+int cst_ps_models(const cst_agent_config_t *cfg, int refresh,
+                  cst_ps_model_t *out, int max, int *api_rc, char *err,
+                  size_t err_sz);
+
+/* Checks key against /models and saves it: CST_MODELS_AUTH (err set), or
+ * the CST_PS_* flags. When ids is given it gets the fetched list and *nids
+ * the raw fetch result. */
+int cst_ps_verify_save(const char *provider, const char *api_base,
+                       const char *key, char ids[][128], int max, int *nids,
+                       char *err, size_t err_sz);
+
+/* Point cfg at provider p with key: base URL, the remembered model (else
+ * the preset's), settings saved. */
+void cst_ps_apply_provider(cst_agent_config_t *cfg, const cst_provider_t *p,
+                           const char *key);
+
+/* The whole switch without a prompt: key NULL/"" uses the saved or env
+ * key (else CST_PS_NEED_KEY); a given key is verified and saved first. A
+ * preset with no model takes the first one the API lists. The CST_PS_*
+ * flags, or CST_PS_UNKNOWN / CST_PS_NEED_KEY / CST_MODELS_AUTH. */
+int cst_ps_switch_provider(cst_agent_config_t *cfg, const char *name,
+                           const char *key, char *err, size_t err_sz);
+
+/* Replace the current provider's key: verified, saved, put in cfg. Same
+ * results as cst_ps_verify_save. */
+int cst_ps_set_key(cst_agent_config_t *cfg, const char *key, char *err,
+                   size_t err_sz);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

include/cst_sandbox.h

@@ -2,20 +2,19 @@
 #define CST_SANDBOX_H
 
 /*
- * OS sandbox for run_shell: reads and exec stay allowed everywhere, writes
- * are limited to the workspace, the temp dir, /dev/null and /dev/tty, and
- * the network is cut where the OS can do it.
- *   Linux   Landlock (network needs ABI 4, kernel 6.7+)
+ * OS sandbox for run_shell: reads, exec and the network stay allowed;
+ * writes are limited to the workspace, the temp dir, /dev/null and /dev/tty.
+ *   Linux   Landlock
  *   Linux   seccomp user-notify when Landlock is missing (Android/Termux,
  *           older kernels): a supervisor thread checks the path of every
- *           write-type syscall and IPv4/IPv6 sockets are refused. Guards
+ *           write-type syscall. Guards
  *           against mistakes, not hostile code (the path is checked before
  *           the kernel reads it again).
  *   macOS   sandbox_init (Seatbelt profile)
  *   Windows Low integrity level: a restricted token (no admin privileges,
  *           Low IL) can only write objects labeled Low, so the workspace and
  *           a temp dir get that label; the credentials file is labeled
- *           no-read-up. The network stays open (callers ask first).
+ *           no-read-up.
  *   other   none: callers fall back to rule-based approval
  */
 
@@ -42,7 +41,7 @@ int cst_sandbox_probe(void);
 int cst_sandbox_reprobe(void);
 /* "landlock" | "seatbelt" | "seccomp" | "lowil" | "none" */
 const char *cst_sandbox_name(int kind);
-/* Landlock ABI version (0 when unavailable); ≥4 also blocks TCP. */
+/* Landlock ABI version (0 when unavailable). */
 int cst_sandbox_landlock_abi(void);
 
 typedef struct {
@@ -69,7 +68,7 @@ int cst_sandbox_run_shell(const char *workspace, const char *cmd,
                           size_t max_out, os_run_result_t *r);
 
 /* Output of a failed sandboxed run that looks like the sandbox got in the
- * way (EACCES / EPERM / EROFS / blocked network). */
+ * way (EACCES / EPERM / EROFS). */
 int cst_sandbox_blocked(const char *out, size_t n, int exit_code);
 
 /* lowil: directories this user's cst-agent labeled Low (recorded in the

include/cst_util.h

@@ -27,6 +27,17 @@ size_t cst_utf8_floor(const char *s, size_t n);
 char *cst_utf8_sanitize(const char *s, size_t n, size_t *out_len);
 int cst_utf8_valid(const char *s, size_t n);
 
+/* Re-chunks a byte stream so no piece ends inside a UTF-8 sequence: the
+ * incomplete tail (at most 3 bytes) waits in the hold for the next feed. */
+typedef struct {
+  char b[4];
+  size_t n;
+} cst_utf8_hold_t;
+/* Returns the complete prefix of hold+s[0..n) (malloc'd, NUL-terminated,
+ * *out_len may be 0), or NULL on OOM. */
+char *cst_utf8_hold_feed(cst_utf8_hold_t *h, const char *s, size_t n,
+                         size_t *out_len);
+
 /* Text files may start with a UTF-8 BOM (Windows editors): its length (0/3),
  * and an in-place strip of the NUL-terminated s (*len updated when given). */
 size_t cst_bom_len(const char *s, size_t n);

include/cst_version.h

@@ -2,8 +2,8 @@
 #define CST_VERSION_H
 
 #define CST_VERSION_MAJOR 0
-#define CST_VERSION_MINOR 6
-#define CST_VERSION_PATCH 1
+#define CST_VERSION_MINOR 8
+#define CST_VERSION_PATCH 3
 
 #define CST_VERSION_STR_(x) #x
 #define CST_VERSION_STR(x) CST_VERSION_STR_(x)

include/cst_web_md.h

@@ -0,0 +1,48 @@
+#ifndef CST_WEB_MD_H
+#define CST_WEB_MD_H
+
+/* Markdown for the WebUI: the same sashidown renderer the TUI uses, but
+ * HTML output with a strict allowlist.
+ *
+ * sashidown renders straight to HTML and escapes text, quotes and '&', so
+ * no raw markup can reach the browser. Two holes remain, and both matter
+ * because every byte rendered here comes from a model or a tool: a link's
+ * href keeps any scheme ("javascript:") and an image's src may point
+ * anywhere (a tracking pixel, or worse). cst_web_md_* therefore rewrites
+ * tags instead of passing them through: unknown tags are dropped, hrefs
+ * are limited to http/https/mailto/relative, and images to the session's
+ * own attachment endpoint.
+ *
+ * The streaming form renders confirmed HTML as the model talks, which is
+ * the CST property the project is built on: nothing is emitted before it
+ * is safe to emit. A tag split across two deltas is held back until its
+ * '>' arrives. */
+
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Called with chunks of sanitized HTML; return non-zero to stop. */
+typedef int (*cst_web_md_emit_fn)(const char *html, size_t len, void *ud);
+
+typedef struct cst_web_md cst_web_md_t;
+
+cst_web_md_t *cst_web_md_new(cst_web_md_emit_fn emit, void *ud);
+/* Feed model output. Returns 0, or -1 on OOM. */
+int cst_web_md_feed(cst_web_md_t *s, const char *data, size_t len);
+/* Flush the pending input and close the renderer. */
+int cst_web_md_finish(cst_web_md_t *s);
+void cst_web_md_free(cst_web_md_t *s);
+
+/* One-shot: markdown -> sanitized HTML (malloc'd, never NULL on success). */
+char *cst_web_md_html(const char *md, size_t len);
+/* The sanitizer alone (tests, and any HTML that did not come from here). */
+char *cst_web_md_sanitize(const char *html, size_t len);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* CST_WEB_MD_H */

include/cst_webui.h

@@ -0,0 +1,44 @@
+#ifndef CST_WEBUI_H
+#define CST_WEBUI_H
+
+/* The built-in WebUI: an HTTP + SSE front end for one agent process.
+ *
+ * It is a second implementation of the same interface the TUI uses
+ * (cst_agent_hooks_t), which is why the engine needs no changes: the turn
+ * runs on a worker thread and every live event goes out as a Server-Sent
+ * Event. The protocol is documented in docs/webui.md and is meant to be
+ * the contract a dedicated client speaks later.  */
+
+#include "cst_agent.h"
+
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* What --web listens on when --web-port/CST_WEB_PORT says nothing (the
+ * README and --help quote this number, so keep them in sync). */
+#define CST_WEBUI_DEFAULT_PORT 8787
+
+typedef struct {
+  const char *host;  /* NULL = 127.0.0.1; "0.0.0.0" = every interface */
+  int port;          /* 0 = pick a free port */
+  const char *token; /* NULL = generate one when needed */
+  const char *root;  /* serve the UI from this directory instead of the
+                        copy embedded in the binary (development) */
+  int open_browser;  /* best-effort xdg-open / open / start */
+  /* Prompt to run once at startup (--web -p ...); NULL = wait for the UI. */
+  const char *prompt;
+  int perm_timeout_s; /* how long a permission question waits (0 = 600) */
+} cst_webui_opts_t;
+
+/* Serve until interrupted (Ctrl+C) or the event stream asks to quit.
+ * Returns the process exit code. */
+int cst_webui_run(cst_agent_t *agent, const cst_webui_opts_t *opts);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* CST_WEBUI_H */

include/os_compat.h

@@ -114,9 +114,10 @@ int os_win_get_label(const char *path, char *out, size_t n);
 int os_clipboard_set(const char *utf8, size_t n);
 #endif
 
-/* Child processes get stdin=/dev/null, their own process group, and are
- * killed after the timeout (CST_SHELL_TIMEOUT seconds, default 120) or when
- * *flag becomes non-zero. Exit code 124 = timeout, 130 = cancelled. */
+/* Child processes get stdin=/dev/null and their own process group. They run
+ * with no time limit unless one is asked for (CST_SHELL_TIMEOUT seconds, or
+ * os_set_run_timeout()); either way a non-zero *flag cancels them.
+ * Exit code 124 = killed by that timeout, 130 = cancelled. */
 void os_set_cancel_flag(volatile int *flag);
 volatile int *os_get_cancel_flag(void);
 void os_set_run_timeout(int seconds); /* this thread; 0 = default */

scripts/e2e_webui.sh

@@ -0,0 +1,290 @@
+#!/bin/sh
+# End-to-end check of the WebUI without a real model: a recorded SSE stream
+# (tests/fixtures/sse) drives a full turn, and the events the browser would
+# see are read back from /api/events with curl.
+#
+#   scripts/e2e_webui.sh [replay-dir] [protocol]
+#
+# Needs: curl. python3 only for the JSON field checks (they are skipped
+# without it). Exit code 0 = every assertion passed.
+set -eu
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+REPLAY="${1:-$ROOT/tests/fixtures/sse/deepseek-native-eos}"
+PROTO="${2:-native-eos}"
+BIN="${CST_AGENT:-$ROOT/cst-agent}"
+[ -x "$BIN" ] || { echo "build cst-agent first ($BIN)"; exit 1; }
+
+WORK="$(mktemp -d "${TMPDIR:-/tmp}/cst-webui-XXXXXX")" 2>/dev/null || {
+  WORK="$ROOT/.build-tmp/e2e-webui"; rm -rf "$WORK"; mkdir -p "$WORK"; }
+EVENTS="$WORK/events.txt"
+LOG="$WORK/server.log"
+cleanup() {
+  [ -n "${SRV_PID:-}" ] && kill "$SRV_PID" 2>/dev/null || true
+  rm -rf "$WORK"
+}
+trap cleanup EXIT INT TERM
+
+echo "== start cst-agent --web (replay $REPLAY)"
+# --yolo: the recorded stream calls write tools, and a permission question
+# would wait for a browser nobody is driving here.
+CST_REPLAY_SSE="$REPLAY" \
+CST_REPLAY_CHUNK=512 \
+"$BIN" --web --web-port 0 --workspace "$WORK" --new --api-key sk-e2e \
+  --protocol "$PROTO" --tools default --yolo > "$LOG" 2>&1 &
+SRV_PID=$!
+
+# The port is picked by the OS; the server prints the URL it bound.
+i=0
+PORT=""
+while [ $i -lt 50 ]; do
+  PORT="$(sed -n 's#^webui: http://127.0.0.1:\([0-9]*\)/.*#\1#p' "$LOG" | head -1)"
+  [ -n "$PORT" ] && break
+  i=$((i + 1))
+  sleep 0.2
+done
+[ -n "$PORT" ] || { echo "FAIL: the server did not report a port"; cat "$LOG"; exit 1; }
+BASE="http://127.0.0.1:$PORT"
+echo "   port $PORT"
+
+fail() { echo "FAIL: $1"; echo "--- events"; cat "$EVENTS" 2>/dev/null | head -40; exit 1; }
+# SIGTERM must shut the server down cleanly, even mid-turn (128+ = a crash)
+stop_server() {
+  kill "$1" 2>/dev/null || return 0
+  n=0
+  while kill -0 "$1" 2>/dev/null && [ $n -lt 200 ]; do n=$((n + 1)); sleep 0.2; done
+  if kill -0 "$1" 2>/dev/null; then
+    kill -9 "$1" 2>/dev/null || true
+    fail "$2 hung on SIGTERM"
+  fi
+  st=0
+  wait "$1" 2>/dev/null || st=$?
+  [ "$st" -lt 128 ] || fail "$2 died with status $st on SIGTERM"
+}
+
+# 1. the shell page and the state endpoint
+curl -fsS --max-time 5 "$BASE/" | grep -q "<title>CST-Agent" || fail "GET / is not the shell page"
+curl -fsS --max-time 5 "$BASE/api/state" > "$WORK/state.json" || fail "GET /api/state"
+grep -q '"protocol":"cst-webui/1"' "$WORK/state.json" || fail "state has no protocol tag"
+grep -q '"session":' "$WORK/state.json" || fail "state has no session id"
+
+# 2. an unknown route is a 404, an oversized body a 413
+code="$(curl -s -o /dev/null -w '%{http_code}' --max-time 5 "$BASE/api/does-not-exist")"
+[ "$code" = "404" ] || fail "unknown route returned $code"
+code="$(head -c 2000000 /dev/zero | tr '\0' 'a' |
+        curl -s -o /dev/null -w '%{http_code}' --max-time 20 \
+             -X POST --data-binary @- "$BASE/api/turn")"
+[ "$code" = "413" ] || fail "2 MB body returned $code (want 413)"
+
+# 3. stream the events while a recorded turn runs
+curl -sN --max-time 120 "$BASE/api/events" > "$EVENTS" &
+CURL_PID=$!
+sleep 0.5
+code="$(curl -s -o "$WORK/turn.json" -w '%{http_code}' --max-time 5 \
+        -X POST -H 'Content-Type: application/json' \
+        --data '{"text":"e2e: what is in the workspace?"}' "$BASE/api/turn")"
+[ "$code" = "202" ] || fail "POST /api/turn returned $code"
+
+i=0
+while [ $i -lt 450 ]; do
+  grep -q "event: turn_end" "$EVENTS" && break
+  i=$((i + 1))
+  sleep 0.2
+done
+kill "$CURL_PID" 2>/dev/null || true
+grep -q "event: turn_end" "$EVENTS" || fail "the turn never finished"
+grep -q "event: assistant_html" "$EVENTS" || fail "no assistant markdown was streamed"
+grep -q "event: tool" "$EVENTS" || fail "no tool event was streamed"
+grep -q '"rc":0' "$EVENTS" || fail "the turn did not end with rc=0"
+
+# 4. the session on disk matches what the UI would draw
+curl -fsS --max-time 5 "$BASE/api/session" > "$WORK/session.json" || fail "GET /api/session"
+grep -q '"role":"assistant"' "$WORK/session.json" || fail "no assistant message stored"
+curl -fsS --max-time 5 "$BASE/api/sessions" | grep -q '"sessions":' || fail "GET /api/sessions"
+
+# 5. a second turn while the first is running is refused with 409
+curl -s -o /dev/null -w '' --max-time 5 -X POST -H 'Content-Type: application/json' \
+     --data '{"text":"x"}' "$BASE/api/turn" || true
+
+# 6. asking to stop is accepted
+curl -fsS --max-time 5 -X POST -H 'Content-Type: application/json' \
+     --data '{}' "$BASE/api/cancel" > /dev/null || fail "POST /api/cancel"
+
+# 6b. the write endpoints: config, undo, compact and image upload
+curl -fsS --max-time 5 -X POST -H 'Content-Type: application/json' \
+     --data '{"approval":"ask","plan_mode":false}' "$BASE/api/config" |
+  grep -q '"ok":true' || fail "POST /api/config"
+curl -fsS --max-time 5 "$BASE/api/state" | grep -q '"approval":"ask"' ||
+  fail "the config change is not in the state"
+code="$(curl -s -o "$WORK/undo.txt" -w '%{http_code}' --max-time 5 \
+        -X POST "$BASE/api/undo")"
+case "$code" in
+  200) grep -q . "$WORK/undo.txt" || fail "an undo without a report" ;;
+  409) ;;   # nothing to undo in this run
+  *) fail "POST /api/undo returned $code" ;;
+esac
+code="$(curl -s -o /dev/null -w '%{http_code}' --max-time 30 \
+        -X POST "$BASE/api/compact")"
+# The recorded stream is spent by now, so a model failure is a valid answer.
+case "$code" in 200 | 500) ;; *) fail "POST /api/compact returned $code" ;; esac
+
+if command -v base64 > /dev/null; then
+  # a real 1x1 PNG: the server sniffs the content, not the extension
+  # (kept with a .bin suffix so the find below only sees the stored copy)
+  echo 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFAAH/q842iQAAAABJRU5ErkJggg==' |
+    base64 -d > "$WORK/tiny.bin" 2> /dev/null || : > "$WORK/tiny.bin"
+  code="$(curl -s -o /dev/null -w '%{http_code}' --max-time 10 -X POST \
+          --data-binary @"$WORK/tiny.bin" "$BASE/api/attach?name=e2e.png")"
+  [ "$code" = "200" ] || fail "POST /api/attach returned $code"
+  curl -fsS --max-time 5 "$BASE/api/state" |
+    grep -q '"pending_images":\["' || fail "the upload is not pending"
+  # the stored name is the content hash, so ask the disk for it
+  STORED="$(find "$WORK" -name '*.png' -type f 2>/dev/null | head -1)"
+  [ -n "$STORED" ] || fail "the upload did not reach the session directory"
+  REL="${STORED##*/}"
+  curl -fsS --max-time 5 "$BASE/api/attach/$REL" > "$WORK/back.png" ||
+    fail "GET /api/attach/$REL"
+  cmp -s "$WORK/tiny.bin" "$WORK/back.png" ||
+    fail "the image did not round trip byte for byte"
+  code="$(curl -s -o /dev/null -w '%{http_code}' --max-time 5 \
+          "$BASE/api/attach/..%2f..%2fetc%2fpasswd")"
+  case "$code" in 400 | 404) ;; *) fail "a traversal in attach returned $code" ;; esac
+  curl -fsS --max-time 5 -X DELETE "$BASE/api/attach" | grep -q '"ok":true' ||
+    fail "DELETE /api/attach"
+  curl -fsS --max-time 5 "$BASE/api/state" |
+    grep -q '"pending_images":\[\]' || fail "the pending image was not cleared"
+else
+  echo "   (no base64 tool: the image upload check is skipped)"
+fi
+
+# 6c. a request with a foreign Host header is refused while no token is set:
+# that is the DNS-rebinding guard.
+code="$(curl -s -o /dev/null -w '%{http_code}' --max-time 5 \
+        -H 'Host: evil.example' "$BASE/api/state")"
+[ "$code" = "401" ] || fail "a foreign Host header returned $code (want 401)"
+
+if command -v python3 > /dev/null; then
+  python3 - "$WORK/session.json" <<'PY' || fail "the session JSON is not valid JSON / is empty"
+import json, sys
+d = json.load(open(sys.argv[1]))
+assert isinstance(d.get("messages"), list) and d["messages"], d
+PY
+fi
+
+# 7. the interactive approval path: a fresh server in ask mode must raise a
+# permission event, and answering it must let the turn continue.
+echo "== permission round trip (-A ask)"
+stop_server "$SRV_PID" "the first server"   # its replay is spent
+rm -rf "$WORK/pw"; mkdir -p "$WORK/pw"
+P_EVENTS="$WORK/permission-events.txt"
+P_LOG="$WORK/permission-server.log"   # its own log: the port parse must not
+                                      # pick up the first server's URL
+CST_REPLAY_SSE="$REPLAY" CST_REPLAY_CHUNK=512 \
+"$BIN" --web --web-port 0 --workspace "$WORK/pw" --new --api-key sk-e2e \
+  --protocol "$PROTO" --tools default --approval ask --confirm all \
+  > "$P_LOG" 2>&1 &
+P_PID=$!
+i=0
+P_PORT=""
+while [ $i -lt 50 ]; do
+  P_PORT="$(sed -n 's#^webui: http://127.0.0.1:\([0-9]*\)/.*#\1#p' "$P_LOG" | tail -1)"
+  [ -n "$P_PORT" ] && break
+  i=$((i + 1)); sleep 0.2
+done
+[ -n "$P_PORT" ] || fail "the ask-mode server did not start (see $P_LOG)"
+P_BASE="http://127.0.0.1:$P_PORT"
+curl -sN --max-time 60 "$P_BASE/api/events" > "$P_EVENTS" &
+P_CURL=$!
+sleep 0.5
+curl -s -o /dev/null --max-time 5 -X POST -H 'Content-Type: application/json' \
+     --data '{"text":"e2e: ask me first"}' "$P_BASE/api/turn"
+i=0
+while [ $i -lt 300 ]; do
+  grep -q "event: permission" "$P_EVENTS" && break
+  i=$((i + 1)); sleep 0.2
+done
+if [ $i -ge 300 ]; then
+  kill "$P_PID" 2>/dev/null || true
+  kill "$P_CURL" 2>/dev/null || true
+  echo "   (no permission question within 60 s - skipped; $(grep -c '^event: ' "$P_EVENTS") events seen)"
+else
+  PID_REQ="$(sed -n 's/.*"id":\([0-9]*\),"tool".*/\1/p' "$P_EVENTS" | head -1)"
+  [ -n "$PID_REQ" ] || fail "a permission event without an id"
+  # Answer while the server is still waiting for it.
+  curl -fsS --max-time 5 -X POST -H 'Content-Type: application/json' \
+       --data "{\"id\":$PID_REQ,\"answer\":1}" "$P_BASE/api/permission" > /dev/null ||
+    fail "POST /api/permission was refused"
+  i=0
+  while [ $i -lt 150 ]; do
+    grep -q "event: permission_done" "$P_EVENTS" && break
+    i=$((i + 1)); sleep 0.2
+  done
+  grep -q "event: permission_done" "$P_EVENTS" || fail "the answer was not acknowledged"
+  stop_server "$P_PID" "the ask-mode server"
+  kill "$P_CURL" 2>/dev/null || true
+  echo "   answered request $PID_REQ with 'allow once'"
+fi
+
+# 8. token auth, --web-dev, and a clean shutdown
+echo "== token auth and --web-dev"
+T_LOG="$WORK/token-server.log"
+CST_REPLAY_SSE="$REPLAY" \
+"$BIN" --web --web-port 0 --workspace "$WORK/pw" --new --api-key sk-e2e \
+  --protocol "$PROTO" --tools default --yolo --web-dev "$ROOT/web" \
+  --web-token tok-e2e > "$T_LOG" 2>&1 &
+T_PID=$!
+i=0
+T_PORT=""
+while [ $i -lt 50 ]; do
+  T_PORT="$(sed -n 's#^webui: http://127.0.0.1:\([0-9]*\)/.*#\1#p' "$T_LOG" | tail -1)"
+  [ -n "$T_PORT" ] && break
+  i=$((i + 1)); sleep 0.2
+done
+[ -n "$T_PORT" ] || fail "the token server did not start (see $T_LOG)"
+T_BASE="http://127.0.0.1:$T_PORT"
+
+code="$(curl -s -o /dev/null -w '%{http_code}' --max-time 5 "$T_BASE/api/state")"
+[ "$code" = "401" ] || fail "a token-protected server answered $code without one"
+code="$(curl -s -o /dev/null -w '%{http_code}' --max-time 5 \
+        -H 'Authorization: Bearer tok-e2e' "$T_BASE/api/state")"
+[ "$code" = "200" ] || fail "the Bearer token was rejected ($code)"
+code="$(curl -s -o /dev/null -w '%{http_code}' --max-time 5 \
+        "$T_BASE/api/state?token=tok-e2e")"
+[ "$code" = "200" ] || fail "the query token was rejected ($code)"
+code="$(curl -s -o /dev/null -w '%{http_code}' --max-time 5 \
+        -H 'Cookie: a=b; cst_token=tok-e2e; z=y' "$T_BASE/api/state")"
+[ "$code" = "200" ] || fail "the cookie token was rejected ($code)"
+code="$(curl -s -o /dev/null -w '%{http_code}' --max-time 5 \
+        -H 'Authorization: Bearer tok-e2' "$T_BASE/api/state")"
+[ "$code" = "401" ] || fail "a wrong token was accepted ($code)"
+
+# --web-dev serves straight from the directory, so the bytes must match it
+curl -fsS --max-time 5 -H 'Authorization: Bearer tok-e2e' "$T_BASE/app.js" \
+  > "$WORK/app.js" || fail "GET /app.js from --web-dev"
+cmp -s "$WORK/app.js" "$ROOT/web/app.js" ||
+  fail "--web-dev did not serve web/app.js from disk"
+
+# POST /api/quit must return and then take the server down on its own
+curl -fsS --max-time 5 -X POST -H 'Authorization: Bearer tok-e2e' \
+     "$T_BASE/api/quit" | grep -q '"ok":true' || fail "POST /api/quit"
+i=0
+while [ $i -lt 50 ] && kill -0 "$T_PID" 2> /dev/null; do
+  i=$((i + 1)); sleep 0.2
+done
+kill -0 "$T_PID" 2> /dev/null && fail "the server ignored /api/quit"
+wait "$T_PID" 2>/dev/null || true
+
+# 9. ask_user waits for the answer, and the HTTP hardening checks (both
+# need a scripted model: python3)
+if command -v python3 > /dev/null; then
+  echo "== ask_user round trip"
+  CST_AGENT="$BIN" python3 "$ROOT/scripts/e2e_webui_ask.py" > "$WORK/ask.txt" 2>&1 ||
+    { cat "$WORK/ask.txt"; fail "the ask_user round trip"; }
+  echo "== HTTP hardening"
+  CST_AGENT="$BIN" python3 "$ROOT/scripts/e2e_webui_http.py" > "$WORK/http.txt" 2>&1 ||
+    { cat "$WORK/http.txt"; fail "the HTTP hardening checks"; }
+  echo "== settings and streaming"
+  CST_AGENT="$BIN" python3 "$ROOT/scripts/e2e_webui_settings.py" > "$WORK/settings.txt" 2>&1 ||
+    { cat "$WORK/settings.txt"; fail "the settings checks"; }
+fi
+
+echo "== OK: (events: $(grep -c '^event: ' "$EVENTS"))"

scripts/e2e_webui_ask.py

@@ -0,0 +1,164 @@
+"""WebUI ask_user round trip against a fake OpenAI-compatible API.
+
+  python3 scripts/e2e_webui_ask.py      (CST_AGENT= picks the binary)
+
+Checks: the turn really waits for the answer, a page opened while the
+question is open still receives it, and Last-Event-ID resumes the stream.
+"""
+import json, os, shutil, subprocess, sys, tempfile, threading, time, urllib.request
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+BIN = os.environ.get("CST_AGENT", os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "cst-agent"))
+REQS = []
+
+
+class H(BaseHTTPRequestHandler):
+    def log_message(self, *a):
+        pass
+
+    def do_GET(self):
+        body = json.dumps({"data": [{"id": "deepseek-flash"}]}).encode()
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_POST(self):
+        n = int(self.headers.get("Content-Length", 0))
+        REQS.append(json.loads(self.rfile.read(n)))
+        self.send_response(200)
+        self.send_header("Content-Type", "text/event-stream")
+        self.end_headers()
+        base = {"id": "x", "object": "chat.completion.chunk", "model": "deepseek-flash"}
+
+        def ev(o):
+            self.wfile.write(b"data: " + json.dumps({**base, **o}).encode() + b"\n\n")
+            self.wfile.flush()
+        if len(REQS) == 1:
+            args = json.dumps({"question": "Pick a colour?", "options": "red\nblue"})
+            ev({"choices": [{"index": 0, "delta": {"role": "assistant", "tool_calls": [
+                {"index": 0, "id": "call_1", "type": "function",
+                 "function": {"name": "ask_user", "arguments": args}}]}}]})
+            ev({"choices": [{"index": 0, "delta": {}, "finish_reason": "tool_calls"}]})
+        else:
+            ev({"choices": [{"index": 0, "delta": {"role": "assistant", "content": "done"}}]})
+            ev({"choices": [{"index": 0, "delta": {}, "finish_reason": "stop"}]})
+        self.wfile.write(b"data: [DONE]\n\n")
+        self.wfile.flush()
+
+
+fails = 0
+
+
+def check(ok, msg):
+    global fails
+    print(("PASS " if ok else "FAIL ") + msg)
+    fails += 0 if ok else 1
+
+
+class Sse:
+    def __init__(self, base, last_id=None):
+        self.lines = []
+        req = urllib.request.Request(base + "/api/events")
+        if last_id is not None:
+            req.add_header("Last-Event-ID", str(last_id))
+        self.r = urllib.request.urlopen(req, timeout=60)
+        threading.Thread(target=self.pump, daemon=True).start()
+
+    def pump(self):
+        try:
+            for raw in self.r:
+                self.lines.append(raw.decode())
+        except Exception:
+            pass
+
+    def events(self, name):
+        out = []
+        for i, l in enumerate(self.lines):
+            if l.strip() == "event: " + name and i + 1 < len(self.lines):
+                out.append(json.loads(self.lines[i + 1][6:]))
+        return out
+
+    def ids(self):
+        return [int(l[4:]) for l in self.lines if l.startswith("id: ")]
+
+    def close(self):
+        try:
+            self.r.close()
+        except Exception:
+            pass
+
+
+def wait(fn, t=15):
+    end = time.time() + t
+    while time.time() < end:
+        v = fn()
+        if v:
+            return v
+        time.sleep(0.1)
+    return None
+
+
+def post(base, path, obj):
+    req = urllib.request.Request(base + path, data=json.dumps(obj).encode(),
+                                 headers={"Content-Type": "application/json"})
+    try:
+        with urllib.request.urlopen(req, timeout=5) as r:
+            return r.status
+    except urllib.error.HTTPError as e:
+        return e.code
+
+
+api = ThreadingHTTPServer(("127.0.0.1", 0), H)
+threading.Thread(target=api.serve_forever, daemon=True).start()
+ws = tempfile.mkdtemp(prefix="cst-ask-")
+log = open(ws + "/server.log", "w+")
+p = subprocess.Popen([BIN, "--web", "--web-port", "0", "--workspace", ws, "--new",
+                      "--api-key", "sk-x", "--provider", "deepseek", "--model", "deepseek-flash",
+                      "--api-base", "http://127.0.0.1:%d/v1" % api.server_address[1],
+                      "--protocol", "native-eos", "--approval", "auto"],
+                     stdout=log, stderr=subprocess.STDOUT)
+try:
+    def port():
+        log.seek(0)
+        for l in log.read().splitlines():
+            if l.startswith("webui: http://127.0.0.1:"):
+                return l.split(":")[3].split("/")[0]
+    pt = wait(port)
+    base = "http://127.0.0.1:%s" % pt
+    a = Sse(base)
+    time.sleep(0.3)
+    check(post(base, "/api/turn", {"text": "ask me"}) == 202, "turn accepted")
+    ask = wait(lambda: a.events("ask_user"))
+    check(bool(ask), "ask_user event raised")
+    time.sleep(1.5)
+    check(len(REQS) == 1, "the turn waits for the answer (requests so far: %d)" % len(REQS))
+    # a page opened now must still see the open question
+    b = Sse(base)
+    check(bool(wait(lambda: b.events("ask_user"), 5)), "a late page gets the open question")
+    # reconnect with Last-Event-ID: nothing before that id is resent
+    last = a.ids()[-1]
+    c = Sse(base, last_id=last - 1)
+    got = wait(lambda: c.ids(), 5)
+    check(bool(got) and got[0] == last, "Last-Event-ID resumes after that id (%s, want %d)" % (got[:1] if got else got, last))
+    if ask:
+        check(post(base, "/api/ask_user", {"id": ask[0]["id"], "text": "blue"}) == 200, "answer accepted")
+    end = wait(lambda: a.events("turn_end"), 20)
+    check(bool(end) and end[0].get("rc") == 0, "turn ended rc=0")
+    tool_msgs = [m for m in (REQS[1]["messages"] if len(REQS) > 1 else []) if m.get("role") == "tool"]
+    check(bool(tool_msgs) and "blue" in json.dumps(tool_msgs), "the answer reached the model: %s" % json.dumps(tool_msgs)[:200])
+    for s in (a, b, c):
+        s.close()
+finally:
+    p.terminate()
+    try:
+        p.wait(20)
+    except subprocess.TimeoutExpired:
+        p.kill()
+        check(False, "server hung on SIGTERM")
+    check(p.returncode is not None and p.returncode < 128 and p.returncode >= 0, "clean exit (%s)" % p.returncode)
+    log.close()
+    shutil.rmtree(ws, ignore_errors=True)
+print("FAILED:", fails)
+sys.exit(1 if fails else 0)

scripts/e2e_webui_http.py

@@ -0,0 +1,234 @@
+"""WebUI HTTP hardening checks over raw sockets, against a scripted model.
+
+  python3 scripts/e2e_webui_http.py      (CST_AGENT= picks the binary)
+
+Cross-site requests, request parsing (Content-Length, NUL, long lines,
+keep-alive), auth before the body, changes refused while a turn runs,
+cancel waking a pending question, token mode and shutdown.
+"""
+import json, os, re, shutil, socket, subprocess, sys, tempfile, threading, time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+BIN = os.environ.get("CST_AGENT", os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "cst-agent"))
+REQS = []
+
+
+class Api(BaseHTTPRequestHandler):
+    """First call: ask_user. Later calls: a plain answer."""
+
+    def log_message(self, *a):
+        pass
+
+    def do_GET(self):
+        body = json.dumps({"data": [{"id": "deepseek-flash"}]}).encode()
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_POST(self):
+        n = int(self.headers.get("Content-Length", 0))
+        REQS.append(json.loads(self.rfile.read(n)))
+        self.send_response(200)
+        self.send_header("Content-Type", "text/event-stream")
+        self.end_headers()
+        base = {"id": "x", "object": "chat.completion.chunk", "model": "deepseek-flash"}
+
+        def ev(o):
+            self.wfile.write(b"data: " + json.dumps({**base, **o}).encode() + b"\n\n")
+            self.wfile.flush()
+        if len(REQS) == 1:
+            args = json.dumps({"question": "Pick?", "options": "a\nb"})
+            ev({"choices": [{"index": 0, "delta": {"role": "assistant", "tool_calls": [
+                {"index": 0, "id": "call_1", "type": "function",
+                 "function": {"name": "ask_user", "arguments": args}}]}}]})
+            ev({"choices": [{"index": 0, "delta": {}, "finish_reason": "tool_calls"}]})
+        else:
+            ev({"choices": [{"index": 0, "delta": {"role": "assistant", "content": "ok"}}]})
+            ev({"choices": [{"index": 0, "delta": {}, "finish_reason": "stop"}]})
+        self.wfile.write(b"data: [DONE]\n\n")
+        self.wfile.flush()
+
+
+fails = 0
+
+
+def check(ok, msg):
+    global fails
+    print(("PASS " if ok else "FAIL ") + msg)
+    fails += 0 if ok else 1
+
+
+def raw(port, data, timeout=5, read_all=True):
+    """Send bytes, return everything read until EOF/timeout."""
+    s = socket.create_connection(("127.0.0.1", port), timeout=timeout)
+    s.sendall(data)
+    out = b""
+    try:
+        while True:
+            b = s.recv(65536)
+            if not b:
+                break
+            out += b
+            if not read_all:
+                break
+    except socket.timeout:
+        pass
+    s.close()
+    return out.decode("latin1")
+
+
+def status(resp):
+    # a pipelined response starts right after the previous body, not on a new line
+    return [int(m) for m in re.findall(r"HTTP/1\.1 (\d{3}) ", resp)]
+
+
+def req(method, path, headers=None, body=b"", host=None):
+    h = {"Host": host or "127.0.0.1:%d" % PORT, "Connection": "close"}
+    h.update(headers or {})
+    if body or method == "POST":
+        h["Content-Length"] = str(len(body))
+    head = "%s %s HTTP/1.1\r\n" % (method, path) + "".join("%s: %s\r\n" % kv for kv in h.items()) + "\r\n"
+    return head.encode() + body
+
+
+def start(ws, *extra):
+    log = open(os.path.join(ws, "server.log"), "w+")
+    p = subprocess.Popen([BIN, "--web", "--web-port", "0", "--workspace", ws, "--new",
+                          "--api-key", "sk-x", "--provider", "deepseek", "--model", "deepseek-flash",
+                          "--api-base", "http://127.0.0.1:%d/v1" % api.server_address[1],
+                          "--protocol", "native-eos", "--approval", "auto", *extra],
+                         stdout=log, stderr=subprocess.STDOUT)
+    end = time.time() + 10
+    while time.time() < end:
+        log.seek(0)
+        for l in log.read().splitlines():
+            if l.startswith("webui: http://127.0.0.1:"):
+                return p, int(l.split(":")[3].split("/")[0]), log
+        time.sleep(0.1)
+    raise SystemExit("server did not start")
+
+
+def stop(p, name):
+    p.terminate()
+    try:
+        p.wait(20)
+    except subprocess.TimeoutExpired:
+        p.kill()
+        check(False, name + " hung on SIGTERM")
+        return
+    check(0 <= p.returncode < 128, "%s exits cleanly (%s)" % (name, p.returncode))
+
+
+api = ThreadingHTTPServer(("127.0.0.1", 0), Api)
+threading.Thread(target=api.serve_forever, daemon=True).start()
+root = tempfile.mkdtemp(prefix="cst-http-")
+try:
+    ws = os.path.join(root, "a")
+    os.makedirs(ws)
+    p, PORT, log = start(ws)
+    me = "http://127.0.0.1:%d" % PORT
+    cfg = b'{"approval":"ask"}'
+    # 1. cross-site requests
+    r = raw(PORT, req("POST", "/api/config", {"Origin": "http://evil.example", "Content-Type": "text/plain"}, cfg))
+    check(status(r)[:1] == [401], "a cross-site POST is refused (%s)" % status(r))
+    r = raw(PORT, req("POST", "/api/config", {"Origin": "null"}, cfg))
+    check(status(r)[:1] == [401], "Origin: null is refused")
+    r = raw(PORT, req("POST", "/api/config", {"Origin": me, "Content-Type": "application/json"}, b'{"approval":"auto"}'))
+    check(status(r)[:1] == [200], "our own page may POST (%s)" % status(r))
+    r = raw(PORT, req("POST", "/api/config", {}, b'{"approval":"auto"}'))
+    check(status(r)[:1] == [200], "a client without Origin (curl) may POST")
+    r = raw(PORT, req("GET", "/api/attach/img-0000.png", host="evil.example"))
+    check(status(r)[:1] == [401], "session images need the Host check too (%s)" % status(r))
+    r = raw(PORT, req("GET", "/app.js"))
+    check(status(r)[:1] == [200], "assets are served")
+    # 2. request parsing
+    r = raw(PORT, req("GET", "/api/state%00x"))
+    check(status(r)[:1] == [400], "an encoded NUL in the path is a 400 (%s)" % status(r))
+    smuggle = b"GET /api/sessions HTTP/1.1\r\nHost: 127.0.0.1\r\n\r\n"
+    r = raw(PORT, ("POST /api/cancel HTTP/1.1\r\nHost: 127.0.0.1:%d\r\nContent-Length: abc\r\n\r\n" % PORT).encode() + smuggle)
+    check(status(r) == [400], "Content-Length: abc is a 400, nothing smuggled (%s)" % status(r))
+    r = raw(PORT, ("POST /api/cancel HTTP/1.1\r\nHost: 127.0.0.1:%d\r\nContent-Length: 0\r\nContent-Length: %d\r\n\r\n"
+                   % (PORT, len(smuggle))).encode() + smuggle)
+    check(status(r) == [400], "two different Content-Lengths are a 400 (%s)" % status(r))
+    r = raw(PORT, ("GET /%s HTTP/1.1\r\nHost: x\r\n\r\n" % ("a" * 9000)).encode())
+    check(status(r)[:1] == [400], "an over-long request line is a 400 (%s)" % status(r))
+    r = raw(PORT, req("GET", "/api/state?x=http://a/b"))
+    check(status(r)[:1] == [200], "'://' in the query leaves the path alone (%s)" % status(r))
+    r = raw(PORT, req("GET", "/api/state", {"Connection": "Close"}), timeout=3)
+    check("Connection: close" in r, "Connection: Close (any case) closes")
+    ka = ("GET /api/state HTTP/1.1\r\nHost: 127.0.0.1:%d\r\n\r\n" % PORT).encode()
+    big = ("POST /api/turn HTTP/1.1\r\nHost: 127.0.0.1:%d\r\nContent-Length: 5000000\r\n\r\n" % PORT).encode()
+    r = raw(PORT, ka + big)
+    check(status(r) == [200, 413], "a 413 after a keep-alive request still arrives (%s)" % status(r))
+    # 3. a pending question: changes are refused, approval may change, cancel wakes it
+    events = []
+
+    def sse():
+        s = socket.create_connection(("127.0.0.1", PORT))
+        s.sendall(("GET /api/events HTTP/1.1\r\nHost: 127.0.0.1:%d\r\n\r\n" % PORT).encode())
+        buf = b""
+        s.settimeout(60)
+        try:
+            while True:
+                b = s.recv(65536)
+                if not b:
+                    break
+                buf += b
+                events[:] = [l[7:] for l in buf.decode("latin1").split("\n") if l.startswith("event: ")]
+        except Exception:
+            pass
+    threading.Thread(target=sse, daemon=True).start()
+    time.sleep(0.4)
+    r = raw(PORT, req("POST", "/api/turn", {"Content-Type": "application/json"}, b'{"text":"go"}'))
+    check(status(r)[:1] == [202], "turn accepted")
+    end = time.time() + 15
+    while time.time() < end and "ask_user" not in events:
+        time.sleep(0.1)
+    check("ask_user" in events, "the question is open")
+    for path, body in (("/api/sessions/new", b""), ("/api/workspace", json.dumps({"path": root}).encode()),
+                       ("/api/compact", b""), ("/api/undo", b""), ("/api/config", b'{"model":"x"}')):
+        r = raw(PORT, req("POST", path, {"Content-Type": "application/json"}, body))
+        check(status(r)[:1] == [409], "%s is refused mid-turn (%s)" % (path, status(r)))
+    r = raw(PORT, req("POST", "/api/config", {"Content-Type": "application/json"}, b'{"approval":"yolo"}'))
+    check(status(r)[:1] == [200], "approval may change mid-turn")
+    r = raw(PORT, req("POST", "/api/cancel", {"Content-Type": "application/json"}, b"{}"))
+    end = time.time() + 10
+    while time.time() < end and "turn_end" not in events:
+        time.sleep(0.1)
+    check("turn_end" in events, "cancel ends a turn parked on a question")
+    r = raw(PORT, req("POST", "/api/sessions/new", {"Content-Type": "application/json"}))
+    check(status(r)[:1] == [200], "after the turn, a new session is fine (%s)" % status(r))
+    stop(p, "the server")
+
+    # 4. token mode: the page loads, the API and images do not without it
+    ws2 = os.path.join(root, "b")
+    os.makedirs(ws2)
+    p, PORT, log = start(ws2, "--web-token", "tok-x")
+    r = raw(PORT, req("GET", "/app.js"))
+    check(status(r)[:1] == [200], "token mode: app.js loads without the token (%s)" % status(r))
+    r = raw(PORT, req("GET", "/api/state"))
+    check(status(r)[:1] == [401], "token mode: the API needs it")
+    r = raw(PORT, req("GET", "/api/attach/img-0000.png"))
+    check(status(r)[:1] == [401], "token mode: images need it")
+    r = raw(PORT, req("GET", "/api/state", {"Cookie": "cst_token=tok-x"}))
+    check(status(r)[:1] == [200], "token mode: the cookie works")
+    t0 = time.time()
+    r = raw(PORT, ("POST /api/attach HTTP/1.1\r\nHost: 127.0.0.1:%d\r\nContent-Length: 33554431\r\n"
+                   "Expect: 100-continue\r\n\r\n" % PORT).encode(), timeout=5)
+    check(status(r) == [401] and time.time() - t0 < 3,
+          "no token, no body read: 401 at once (%s, %.1fs)" % (status(r), time.time() - t0))
+    stop(p, "the token server")
+
+    # 5. option checks
+    rc = subprocess.run([BIN, "--web", "--web-port", "70000", "--workspace", ws2],
+                        capture_output=True, timeout=10).returncode
+    check(rc != 0, "--web-port 70000 is refused")
+    rc = subprocess.run([BIN, "--web", "--web-token", "x" * 80, "--web-port", "0", "--workspace", ws2,
+                         "--api-key", "k"], capture_output=True, timeout=10).returncode
+    check(rc != 0, "an over-long --web-token is refused")
+finally:
+    shutil.rmtree(root, ignore_errors=True)
+print("FAILED:", fails)
+sys.exit(1 if fails else 0)

scripts/e2e_webui_settings.py

@@ -0,0 +1,313 @@
+"""WebUI settings and streaming against fake OpenAI-compatible APIs.
+
+  python3 scripts/e2e_webui_settings.py      (CST_AGENT= picks the binary)
+
+Checks: Chinese reasoning streams as whole characters in few events; the
+provider list, the model list with capabilities, config validation and
+persistence; a wrong key is rejected, a good one switches the provider
+(requests then go to the new base URL) and is saved; and all of it
+survives a restart. HOME and XDG_CONFIG_HOME point at a temp dir, so no
+real credentials or settings are read or written.
+"""
+import json, os, shutil, stat, subprocess, sys, tempfile, threading, time, urllib.request
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+BIN = os.environ.get("CST_AGENT", os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "cst-agent"))
+THINK = ["好的，我先看看工作区里", "有哪些文件，然后用中文", "回答这个问题。😀 结束"]
+ANSWER = "这是中文回答。"
+GOOD_KEYS = {"sk-good", "sk-good2"}
+B_REQS = []
+
+
+def sse_reply(h, model, think, answer):
+    h.send_response(200)
+    h.send_header("Content-Type", "text/event-stream")
+    h.end_headers()
+    base = {"id": "x", "object": "chat.completion.chunk", "model": model}
+
+    def ev(o):
+        h.wfile.write(b"data: " + json.dumps({**base, **o}, ensure_ascii=False).encode() + b"\n\n")
+        h.wfile.flush()
+    for part in think:
+        ev({"choices": [{"index": 0, "delta": {"role": "assistant", "reasoning_content": part}}]})
+    ev({"choices": [{"index": 0, "delta": {"content": answer}}]})
+    ev({"choices": [{"index": 0, "delta": {}, "finish_reason": "stop"}]})
+    h.wfile.write(b"data: [DONE]\n\n")
+    h.wfile.flush()
+
+
+def send_json(h, code, obj):
+    body = json.dumps(obj).encode()
+    h.send_response(code)
+    h.send_header("Content-Type", "application/json")
+    h.send_header("Content-Length", str(len(body)))
+    h.end_headers()
+    h.wfile.write(body)
+
+
+class A(BaseHTTPRequestHandler):
+    """The starting provider: any key, one model, Chinese reasoning."""
+    def log_message(self, *a):
+        pass
+
+    def do_GET(self):
+        send_json(self, 200, {"data": [{"id": "deepseek-flash"}]})
+
+    def do_POST(self):
+        self.rfile.read(int(self.headers.get("Content-Length", 0)))
+        sse_reply(self, "deepseek-flash", THINK, ANSWER)
+
+
+class B(BaseHTTPRequestHandler):
+    """The provider switched to: /models checks the key."""
+    def log_message(self, *a):
+        pass
+
+    def key_ok(self):
+        auth = self.headers.get("Authorization", "")
+        return auth.startswith("Bearer ") and auth[7:] in GOOD_KEYS
+
+    def do_GET(self):
+        if not self.key_ok():
+            return send_json(self, 401, {"error": {"message": "invalid api key"}})
+        send_json(self, 200, {"data": [{"id": "fake-vis"}, {"id": "fake-text"}]})
+
+    def do_POST(self):
+        body = json.loads(self.rfile.read(int(self.headers.get("Content-Length", 0))) or b"{}")
+        B_REQS.append({"auth": self.headers.get("Authorization", ""), "model": body.get("model")})
+        if not self.key_ok():
+            return send_json(self, 401, {"error": {"message": "invalid api key"}})
+        sse_reply(self, body.get("model") or "fake-vis", [], "B 的回答")
+
+
+fails = 0
+
+
+def check(ok, msg):
+    global fails
+    print(("PASS " if ok else "FAIL ") + msg)
+    fails += 0 if ok else 1
+
+
+class Sse:
+    def __init__(self, base):
+        self.lines = []
+        self.r = urllib.request.urlopen(base + "/api/events", timeout=60)
+        threading.Thread(target=self.pump, daemon=True).start()
+
+    def pump(self):
+        try:
+            for raw in self.r:
+                self.lines.append(raw)
+        except Exception:
+            pass
+
+    def events(self, name):
+        out = []
+        for i, l in enumerate(self.lines):
+            if l.strip() == b"event: " + name.encode() and i + 1 < len(self.lines):
+                out.append(self.lines[i + 1][6:])
+        return out
+
+    def close(self):
+        try:
+            self.r.close()
+        except Exception:
+            pass
+
+
+def wait(fn, t=15):
+    end = time.time() + t
+    while time.time() < end:
+        v = fn()
+        if v:
+            return v
+        time.sleep(0.1)
+    return None
+
+
+def call(base, path, obj=None, method=None):
+    data = None if obj is None else json.dumps(obj).encode()
+    req = urllib.request.Request(base + path, data=data, method=method or ("POST" if data else "GET"),
+                                 headers={"Content-Type": "application/json"})
+    try:
+        with urllib.request.urlopen(req, timeout=20) as r:
+            raw = r.read()
+            return r.status, json.loads(raw or b"{}"), raw
+    except urllib.error.HTTPError as e:
+        raw = e.read()
+        try:
+            return e.code, json.loads(raw or b"{}"), raw
+        except ValueError:
+            return e.code, {}, raw
+
+
+def serve(handler):
+    s = ThreadingHTTPServer(("127.0.0.1", 0), handler)
+    threading.Thread(target=s.serve_forever, daemon=True).start()
+    return s
+
+
+api_a, api_b = serve(A), serve(B)
+ws = tempfile.mkdtemp(prefix="cst-set-")
+home = tempfile.mkdtemp(prefix="cst-home-")
+cfgdir = home + "/.config/cst-agent"
+os.makedirs(cfgdir)
+with open(cfgdir + "/models.json", "w") as f:
+    json.dump({"providers": {"fakeb": {"api_base": "http://127.0.0.1:%d/v1" % api_b.server_address[1],
+                                       "key_env": "FAKEB_API_KEY", "default_model": ""}},
+               "models": [{"match": "fake-vis", "vision": True, "context": 200000},
+                          {"match": "fake-text", "vision": False}]}, f)
+env = dict(os.environ, HOME=home, XDG_CONFIG_HOME=home + "/.config",
+           XDG_DATA_HOME=home + "/.local/share", XDG_CACHE_HOME=home + "/.cache")
+for k in ("DEEPSEEK_API_KEY", "FAKEB_API_KEY", "OPENAI_API_KEY", "CST_API_KEY"):
+    env.pop(k, None)
+procs = []
+
+
+def start(args, tag):
+    log = open("%s/%s.log" % (ws, tag), "w+")
+    p = subprocess.Popen([BIN, "--web", "--web-port", "0", "--workspace", ws] + args,
+                         stdout=log, stderr=subprocess.STDOUT, env=env)
+    procs.append((p, log))
+
+    def port():
+        log.seek(0)
+        for l in log.read().splitlines():
+            if l.startswith("webui: http://127.0.0.1:"):
+                return l.split(":")[3].split("/")[0]
+    pt = wait(port)
+    return p, "http://127.0.0.1:%s" % pt
+
+
+def stop(p):
+    p.terminate()
+    try:
+        p.wait(20)
+    except subprocess.TimeoutExpired:
+        p.kill()
+        check(False, "server hung on SIGTERM")
+    check(p.returncode is not None and 0 <= p.returncode < 128, "clean exit (%s)" % p.returncode)
+
+
+def leaked(raw):
+    return any(k.encode() in raw for k in GOOD_KEYS | {"sk-bad", "sk-x"})
+
+
+try:
+    p, base = start(["--new", "--api-key", "sk-x", "--provider", "deepseek", "--model", "deepseek-flash",
+                     "--api-base", "http://127.0.0.1:%d/v1" % api_a.server_address[1],
+                     "--protocol", "native-eos", "--approval", "auto"], "first")
+    a = Sse(base)
+    time.sleep(0.3)
+
+    # 1. Chinese reasoning: whole characters, a handful of events
+    code, _, _ = call(base, "/api/turn", {"text": "用中文想一想"})
+    check(code == 202, "turn accepted")
+    end = wait(lambda: a.events("turn_end"), 20)
+    check(bool(end) and json.loads(end[0]).get("rc") == 0, "turn ended rc=0")
+    raw = a.events("think_delta")
+    ok = True
+    for r in raw:
+        try:
+            r.decode("utf-8")
+        except UnicodeDecodeError:
+            ok = False
+    check(ok, "every think_delta frame is valid UTF-8")
+    text = "".join(json.loads(r.decode("utf-8", "replace"))["text"] for r in raw)
+    want = "".join(THINK)
+    check(text == want and "\ufffd" not in text, "the thinking text round trips: %r" % text[:60])
+    check(0 < len(raw) <= 2 * len(THINK) + 2,
+          "think_delta events: %d for %d bytes" % (len(raw), len(want.encode())))
+    ans = "".join(json.loads(r)["text"] for r in a.events("assistant_delta"))
+    check(ans == ANSWER, "the answer round trips: %r" % ans)
+
+    # 2. providers and models
+    code, d, rawp = call(base, "/api/providers")
+    names = {x["name"]: x for x in d.get("providers", [])}
+    check(code == 200 and "deepseek" in names and "fakeb" in names, "provider list: %s" % sorted(names))
+    check(names.get("deepseek", {}).get("current") and names["deepseek"].get("has_key")
+          and names["deepseek"].get("key_from") == "session", "deepseek: current, key for this run")
+    check(names.get("fakeb", {}).get("has_key") is False and names["fakeb"].get("source") == "user",
+          "fakeb: no key yet, from models.json")
+    check(not leaked(rawp), "no key in /api/providers")
+    code, d, _ = call(base, "/api/models")
+    ids = [m["id"] for m in d.get("models", [])]
+    first = (d.get("models") or [{}])[0]
+    check(code == 200 and "deepseek-flash" in ids and first.get("api") is True
+          and "context" in first and "label" in first, "model list: %s" % ids[:5])
+
+    # 3. config: validation and persistence
+    check(call(base, "/api/config", {"effort": "bogus"})[0] == 400, "a bad effort is a 400")
+    check(call(base, "/api/config", {"provider": "fakeb"})[0] == 400, "provider via /api/config is a 400")
+    check(call(base, "/api/config", {"model": ""})[0] == 400, "an empty model is a 400")
+    code, d, _ = call(base, "/api/config", {"model": "deepseek-v4-pro", "effort": "high"})
+    check(code == 200 and d.get("ok"), "model + effort accepted")
+    code, s, _ = call(base, "/api/state")
+    check(s.get("model") == "deepseek-v4-pro" and s.get("effort") == "high", "the state has them")
+    check(s.get("effort_applies") is True and s.get("key_set") is True and "model_info" in s
+          and s.get("perm_timeout", 0) > 0 and "turn_usage" in s, "the state has the new fields")
+    st = open(cfgdir + "/settings.json").read() if os.path.exists(cfgdir + "/settings.json") else ""
+    check("deepseek-v4-pro" in st and "high" in st, "settings.json remembers model and effort")
+
+    # 4. switching provider: no key, a wrong key, a good key
+    code, d, _ = call(base, "/api/provider", {"name": "fakeb"})
+    check(code == 400 and d.get("need_key"), "fakeb without a key: need_key (%s)" % code)
+    code, d, rawp = call(base, "/api/provider", {"name": "fakeb", "key": "sk-bad"})
+    check(code == 401 and "拒绝" in d.get("error", ""), "a wrong key is rejected (%s %s)" % (code, d.get("error")))
+    check(not leaked(rawp), "no key in the rejection")
+    check(call(base, "/api/state")[1].get("provider") == "deepseek", "still on deepseek")
+    check(call(base, "/api/provider", {"name": "nope"})[0] == 404, "an unknown provider is a 404")
+    code, d, rawp = call(base, "/api/provider", {"name": "fakeb", "key": "sk-good"})
+    check(code == 200 and d.get("provider") == "fakeb" and d.get("model") == "fake-vis",
+          "switched to fakeb, first listed model picked (%s %s)" % (code, d))
+    check(not leaked(rawp), "no key in the switch reply")
+    creds = cfgdir + "/credentials"
+    cr = open(creds).read() if os.path.exists(creds) else ""
+    check("fakeb.api_key=sk-good" in cr, "the key was saved to credentials")
+    if os.name == "posix" and os.path.exists(creds):
+        check(stat.S_IMODE(os.stat(creds).st_mode) == 0o600, "credentials is 0600")
+    code, d, _ = call(base, "/api/models")
+    ms = {m["id"]: m for m in d.get("models", [])}
+    check("fake-vis" in ms and ms["fake-vis"].get("vision") is True and ms["fake-vis"].get("context") == 200000
+          and ms.get("fake-text", {}).get("vision") is False, "fakeb models with capabilities")
+    code, d, _ = call(base, "/api/config", {"effort": "low"})
+    check(code == 200 and d.get("warning"), "effort on a model without it: saved with a warning")
+
+    # 5. a turn now goes to the new base URL with the new key
+    n0 = len(B_REQS)
+    code, _, _ = call(base, "/api/turn", {"text": "hi B"})
+    check(code == 202, "turn on fakeb accepted")
+    wait(lambda: len(a.events("turn_end")) >= 2, 20)
+    check(len(B_REQS) > n0 and B_REQS[-1]["auth"] == "Bearer sk-good" and B_REQS[-1]["model"] == "fake-vis",
+          "the request reached fakeb: %s" % (B_REQS[-1:] or "none"))
+
+    # 6. replacing the key
+    code, d, _ = call(base, "/api/key", {"key": "sk-bad"})
+    check(code == 401, "a wrong replacement key is rejected (%s)" % code)
+    code, d, _ = call(base, "/api/key", {"key": "sk-good2"})
+    check(code == 200 and d.get("ok"), "the replacement key is accepted")
+    check("fakeb.api_key=sk-good2" in open(creds).read(), "the replacement key was saved")
+    check(call(base, "/api/key", {})[0] == 400, "an empty key body is a 400")
+    a.close()
+    stop(p)
+
+    # 7. the next start remembers provider, model and key
+    p, base = start(["--new"], "second")
+    code, s, raws = call(base, "/api/state")
+    check(s.get("provider") == "fakeb" and s.get("model") == "fake-vis" and s.get("key_set") is True
+          and s.get("key_from") == "saved", "restart: %s/%s key %s" % (s.get("provider"), s.get("model"), s.get("key_from")))
+    check(not leaked(raws), "no key in /api/state")
+    stop(p)
+
+    logs = b"".join(open(lg.name, "rb").read() for _, lg in procs)
+    check(not leaked(logs.replace(b"sk-x", b"")) , "no key in the server logs")
+finally:
+    for p, log in procs:
+        if p.poll() is None:
+            p.kill()
+        log.close()
+    shutil.rmtree(ws, ignore_errors=True)
+    shutil.rmtree(home, ignore_errors=True)
+print("FAILED:", fails)
+sys.exit(1 if fails else 0)

scripts/embed_web.sh

@@ -0,0 +1,40 @@
+#!/bin/sh
+# Embed web/ into .gen/web_assets.inc as C byte arrays (the same trick the
+# Makefile uses for src/models_builtin.json). POSIX sh on purpose: the musl
+# and busybox build environments have no bash.  Usage:
+#   sh scripts/embed_web.sh [out.inc] [web-dir]
+set -eu
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+OUT="${1:-$ROOT/.gen/web_assets.inc}"
+DIR="${2:-$ROOT/web}"
+
+FILES="index.html app.js style.css favicon.svg"
+
+mkdir -p "$(dirname "$OUT")"
+{
+  echo "/* Generated by scripts/embed_web.sh from web/ - do not edit. */"
+  for f in $FILES; do
+    [ -f "$DIR/$f" ] || continue
+    var="wui_asset_$(echo "$f" | tr -c 'a-zA-Z0-9' '_')"
+    echo "static const unsigned char ${var}[] = {"
+    od -An -v -tx1 "$DIR/$f" | sed 's/\([0-9a-f][0-9a-f]\)/0x\1,/g'
+    echo "0x00};"
+  done
+  echo "static const wui_asset_t wui_assets[] = {"
+  for f in $FILES; do
+    [ -f "$DIR/$f" ] || continue
+    var="wui_asset_$(echo "$f" | tr -c 'a-zA-Z0-9' '_')"
+    case "$f" in
+      *.html) ctype="text/html; charset=utf-8" ;;
+      *.js)   ctype="text/javascript; charset=utf-8" ;;
+      *.css)  ctype="text/css; charset=utf-8" ;;
+      *.svg)  ctype="image/svg+xml" ;;
+      *)      ctype="application/octet-stream" ;;
+    esac
+    echo "  {\"$f\", \"$ctype\", ${var}, sizeof(${var}) - 1},"
+  done
+  echo "};"
+  echo "static const int wui_asset_count = (int)(sizeof(wui_assets) / sizeof(wui_assets[0]));"
+} > "$OUT.tmp"
+mv "$OUT.tmp" "$OUT"
+echo "embedded $(wc -c < "$OUT") bytes of C into $OUT"

scripts/tui_keys/esc.py

@@ -0,0 +1,44 @@
+import os
+import sys, time
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from harness import Term
+import fakeapi
+from keys import input_text, styled, check, FAILS, base
+
+for term in ("xterm-256color", "screen-256color"):
+    t = Term(args=("-b", base, "-k", "sk-test"), term=term)
+    t.send("some text")
+    t.send("\x1b", 0.4)
+    check(term + " lone esc clears input", input_text(t) == [], t)
+    t.send("alpha beta")
+    t.send("\x1bb")  # alt+b word left
+    t.send("X")
+    check(term + " alt+b word left", "alpha Xbeta" in input_text(t), t)
+    t.send("\x1b\r")  # alt+enter newline
+    t.send("Y")
+    check(term + " alt+enter newline", input_text(t)[-2:] == ["alpha X", "Ybeta"], t)
+    t.send("\x03", 0.2)
+    # picker with CSI form
+    t.send("/model\r", 0.8)
+    s0 = styled(t)
+    t.arrow("down", "csi")
+    s1 = styled(t)
+    t.arrow("up", "csi")
+    s2 = styled(t)
+    check(term + " picker csi down", s0 != s1, t)
+    check(term + " picker csi up", s0 == s2, t)
+    t.send("\x1b", 0.4)
+    # home/end variants
+    t.send("middle")
+    for seq in ("\x1b[H", "\x1bOH", "\x1b[1~", "\x1b[7~"):
+        t.send("\x1b[F" + seq)
+        t.send("<")
+        t.send("\x08" if False else "")
+    check(term + " home variants", input_text(t)[-1:] == ["<<<<middle"], t)
+    for seq in ("\x1b[F", "\x1bOF", "\x1b[4~", "\x1b[8~"):
+        t.send("\x1b[H" + seq)
+        t.send(">")
+    check(term + " end variants", input_text(t)[-1:] == ["<<<<middle>>>>"], t)
+    t.close()
+print("FAILED:", len(FAILS))
+sys.exit(min(len(FAILS), 100))

scripts/tui_keys/fakeapi.py

@@ -0,0 +1,43 @@
+import json, sys, threading, time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+LOG = []
+
+
+class H(BaseHTTPRequestHandler):
+    def log_message(self, *a):
+        pass
+
+    def do_GET(self):
+        body = json.dumps({"data": [{"id": "deepseek-flash"}, {"id": "deepseek-v4-pro"}]}).encode()
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_POST(self):
+        n = int(self.headers.get("Content-Length", 0))
+        raw = self.rfile.read(n)
+        try:
+            LOG.append(json.loads(raw))
+        except Exception:
+            LOG.append({"_raw": raw[:200].decode("latin1")})
+        self.send_response(200)
+        self.send_header("Content-Type", "text/event-stream")
+        self.end_headers()
+        def ev(o):
+            self.wfile.write(b"data: " + json.dumps(o).encode() + b"\n\n")
+            self.wfile.flush()
+        base = {"id": "x", "object": "chat.completion.chunk", "model": "deepseek-flash"}
+        ev({**base, "choices": [{"index": 0, "delta": {"role": "assistant", "content": "reply-%d" % len(LOG)}}]})
+        ev({**base, "choices": [{"index": 0, "delta": {}, "finish_reason": "stop"}],
+            "usage": {"prompt_tokens": 10, "completion_tokens": 2, "total_tokens": 12}})
+        self.wfile.write(b"data: [DONE]\n\n")
+        self.wfile.flush()
+
+
+def start():
+    s = ThreadingHTTPServer(("127.0.0.1", 0), H)
+    threading.Thread(target=s.serve_forever, daemon=True).start()
+    return s, "http://127.0.0.1:%d/v1" % s.server_address[1]

scripts/tui_keys/harness.py

@@ -0,0 +1,99 @@
+"""Drive the cst-agent TUI in a pty and read the screen back (pyte).
+
+Run from the repo root after `make`:
+  nix-shell -p python3Packages.pyte --run "python3 scripts/tui_keys/keys.py"
+  nix-shell -p python3Packages.pyte --run "python3 scripts/tui_keys/esc.py"
+(or `pip install pyte`). A local fake OpenAI-compatible server answers the
+model calls, so no API key is needed. Exit status is the failure count.
+"""
+import os, pty, sys, time, select, fcntl, termios, struct, signal, shutil, tempfile
+import pyte
+
+BIN = os.environ.get("CST_BIN") or os.path.join(
+    os.path.dirname(os.path.abspath(__file__)), "..", "..", "cst-agent")
+
+
+class Term:
+    def __init__(self, cols=120, rows=36, kitty=False, env=None, args=(), home=None,
+                 ws=None, term="xterm-256color"):
+        self.cols, self.rows, self.kitty = cols, rows, kitty
+        self.screen = pyte.Screen(cols, rows)
+        self.stream = pyte.ByteStream(self.screen)
+        self.home = home or tempfile.mkdtemp(prefix="cstk_home_")
+        self.ws = ws or tempfile.mkdtemp(prefix="cstk_ws_")
+        e = dict(os.environ)
+        e.update({"TERM": term, "HOME": self.home,
+                  "XDG_CONFIG_HOME": os.path.join(self.home, ".config"),
+                  "LANG": "C.UTF-8", "LC_ALL": "C.UTF-8",
+                  "CST_PROVIDER": "deepseek", "DEEPSEEK_API_KEY": "sk-dummy-test",
+                  "CST_METRICS": "0"})
+        e.pop("NO_COLOR", None)
+        if env:
+            e.update(env)
+        self.raw = b""
+        pid, fd = pty.fork()
+        if pid == 0:
+            os.chdir(self.ws)
+            os.execve(BIN, [BIN, "-N", *args], e)
+        self.pid, self.fd = pid, fd
+        fcntl.ioctl(fd, termios.TIOCSWINSZ, struct.pack("HHHH", rows, cols, 0, 0))
+        self.pump(1.5)
+
+    def pump(self, t=0.25):
+        end = time.time() + t
+        while True:
+            left = end - time.time()
+            if left <= 0:
+                break
+            r, _, _ = select.select([self.fd], [], [], left)
+            if not r:
+                continue
+            try:
+                d = os.read(self.fd, 65536)
+            except OSError:
+                break
+            if not d:
+                break
+            self.raw += d
+            if self.kitty and b"\x1b[?u" in d:
+                os.write(self.fd, b"\x1b[?0u")
+            self.stream.feed(d)
+
+    def send(self, b, t=0.15):
+        if isinstance(b, str):
+            b = b.encode()
+        os.write(self.fd, b)
+        self.pump(t)
+
+    def appcursor(self):
+        return (1 << 5) in self.screen.mode  # pyte DECCKM
+
+    def arrow(self, d, form=None, mod=None, t=0.15):
+        c = {"up": "A", "down": "B", "right": "C", "left": "D"}[d]
+        if mod:
+            seq = "\x1b[1;%d%s" % (mod, c)
+        else:
+            f = form or ("ss3" if self.appcursor() else "csi")
+            seq = ("\x1bO" if f == "ss3" else "\x1b[") + c
+        self.send(seq, t)
+
+    def lines(self):
+        return [l.rstrip() for l in self.screen.display]
+
+    def find(self, s):
+        return [(i, l) for i, l in enumerate(self.lines()) if s in l]
+
+    def cursor(self):
+        return self.screen.cursor.y, self.screen.cursor.x
+
+    def dump(self, title=""):
+        print("=" * 20, title, "cursor", self.cursor())
+        for i, l in enumerate(self.lines()):
+            print("%2d|%s" % (i, l))
+
+    def close(self):
+        try:
+            os.kill(self.pid, signal.SIGTERM)
+            os.waitpid(self.pid, 0)
+        except Exception:
+            pass

scripts/tui_keys/keys.py

@@ -0,0 +1,273 @@
+import os
+import sys, time
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from harness import Term
+import fakeapi
+
+srv, base = fakeapi.start()
+FAILS = []
+VERBOSE = "-v" in sys.argv
+
+
+def check(name, cond, t=None):
+    print(("PASS " if cond else "FAIL ") + name)
+    if not cond:
+        FAILS.append(name)
+        if t:
+            t.dump(name)
+
+
+def input_text(t):
+    """Input box rows: the bar rows right above the mode line."""
+    L = t.lines()
+    mode = [i for i, l in enumerate(L) if l.lstrip().startswith("┃ ") and
+            ("Build ·" in l or "Plan ·" in l)]
+    if not mode:
+        return []
+    rows = []
+    i = mode[-1] - 1
+    while i >= 0:
+        s = L[i].lstrip()
+        if not s.startswith("┃"):
+            break
+        body = s[2:].split("     ")[0].rstrip() if s.startswith("┃ ") else ""
+        if body == "" and rows:
+            break
+        if body:
+            rows.append(body)
+        i -= 1
+    rows.reverse()
+    if rows and (rows[0].startswith("Ask anything") or rows[0].startswith("Enter queues")):
+        return []
+    return rows
+
+
+def styled(t):
+    """Screen text plus the reverse/bg attributes, to see highlight moves."""
+    out = []
+    for y in range(t.rows):
+        row = t.screen.buffer[y]
+        out.append("".join("%s%s%s" % (row[x].data, int(row[x].reverse), row[x].bg[:3])
+                           for x in range(t.cols)))
+    return out
+
+
+def clear(t):
+    if [r for r in input_text(t) if r]:
+        t.send("\x03", 0.2)  # ctrl+c clears a non-empty input (twice on empty quits)
+
+
+def new(kitty=False, **kw):
+    t = Term(kitty=kitty, args=("-b", base, "-k", "sk-test", "-m", "deepseek-flash"), **kw)
+    return t
+
+
+def basic(t, form, tag):
+    clear(t)
+    t.send("hello world")
+    for _ in range(5):
+        t.arrow("left", form)
+    t.send("X")
+    check(f"{tag} left x5 insert", "hello Xworld" in input_text(t), t)
+    t.arrow("right", form); t.arrow("right", form)
+    t.send("Y")
+    check(f"{tag} right x2 insert", "hello XwoYrld" in input_text(t), t)
+    # boundaries
+    for _ in range(30):
+        t.arrow("left", form, t=0.02)
+    t.pump(0.2)
+    t.send("<")
+    check(f"{tag} left past start", "<hello XwoYrld" in input_text(t), t)
+    for _ in range(30):
+        t.arrow("right", form, t=0.02)
+    t.pump(0.2)
+    t.send(">")
+    check(f"{tag} right past end", "<hello XwoYrld>" in input_text(t), t)
+    clear(t)
+
+
+def cjk(t):
+    clear(t)
+    t.send("你好世界")
+    y, x_end = t.cursor()
+    t.arrow("left"); t.arrow("left")
+    y2, x2 = t.cursor()
+    check("cjk cursor moves 2 cells per char", x_end - x2 == 4, t)
+    t.send("A")
+    check("cjk insert between wide chars", "你好A世界" in input_text(t), t)
+    t.arrow("right")
+    t.send("B")
+    check("cjk right over wide char", "你好A世B界" in input_text(t), t)
+    clear(t)
+    t.send("a😀b")
+    t.arrow("left"); t.arrow("left")
+    t.send("Z")
+    check("emoji left", "aZ😀b" in input_text(t), t)
+    clear(t)
+
+
+def multiline(t):
+    clear(t)
+    t.send("line one is long")
+    t.send("\x0e")  # ctrl+n newline
+    t.send("l2")
+    t.send("\x0e")
+    t.send("third line here")
+    rows = input_text(t)
+    check("multiline 3 rows", rows[-3:] == ["line one is long", "l2", "third line here"], t)
+    for _ in range(4):
+        t.arrow("left")  # cursor before "here"
+    t.arrow("up")       # col 11 -> clamp to end of "l2"
+    t.send("U")
+    rows = input_text(t)
+    check("up clamps column to short line", rows[-2] == "l2U", t)
+    t.arrow("up")       # col 3 on line one
+    t.send("V")
+    rows = input_text(t)
+    check("up keeps column", rows[-3] == "linVe one is long", t)
+    t.arrow("down"); t.arrow("down")
+    t.send("W")
+    rows = input_text(t)
+    check("down twice to last line", "W" in rows[-1], t)
+    clear(t)
+
+
+def history(t):
+    clear(t)
+    t.send("first prompt\r", 1.5)
+    t.send("second prompt\r", 1.5)
+    t.arrow("up")
+    check("hist up -> newest", input_text(t)[-1:] == ["second prompt"], t)
+    t.arrow("up")
+    check("hist up -> older", input_text(t)[-1:] == ["first prompt"], t)
+    t.arrow("up")
+    check("hist up at oldest stays", input_text(t)[-1:] == ["first prompt"], t)
+    t.arrow("down")
+    check("hist down -> newer", input_text(t)[-1:] == ["second prompt"], t)
+    t.arrow("down")
+    check("hist down past newest -> empty", input_text(t) in ([], [""]), t)
+    # draft survives a trip through history
+    t.send("my draft")
+    t.arrow("up")
+    t.arrow("down")
+    check("draft restored after up/down", input_text(t)[-1:] == ["my draft"], t)
+    clear(t)
+
+
+def wrapped(t):
+    clear(t)
+    long = " ".join("w%02d" % i for i in range(40))  # ~160 chars, wraps
+    t.send(long, 0.4)
+    nrows = len(input_text(t))
+    t.arrow("up")
+    txt = "".join(input_text(t))
+    check("up on wrapped line keeps the text", "w39" in txt and "w00" in txt, t)
+    t.send("Q")
+    rows = input_text(t)
+    check("up on wrapped line moves one visual row", nrows >= 2 and "Q" in "".join(rows[:-1]), t)
+    clear(t)
+
+
+def completion(t):
+    clear(t)
+    t.send("/", 0.3)
+    before = styled(t)
+    t.arrow("down"); t.arrow("down")
+    mid = styled(t)
+    t.arrow("up")
+    after = styled(t)
+    check("completion popup reacts to down", before != mid, t)
+    check("completion up differs from down-down", mid != after, t)
+    check("completion arrows do not touch input", input_text(t)[-1:] == ["/"], t)
+    t.send("\x1b", 0.3)
+    clear(t)
+
+
+def modifiers(t):
+    clear(t)
+    t.send("alpha beta gamma")
+    t.arrow("left", mod=5)   # ctrl+left -> word left
+    t.send("X")
+    check("ctrl+left word", "alpha beta Xgamma" in input_text(t), t)
+    t.arrow("left", mod=3)   # alt+left
+    t.arrow("left", mod=3)
+    t.send("Y")
+    check("alt+left word", "alpha Ybeta Xgamma" in input_text(t), t)
+    t.arrow("right", mod=5)
+    t.send("Z")
+    check("ctrl+right word", "alpha YbetaZ Xgamma" in input_text(t), t)
+    t.arrow("left", mod=2)  # shift+left: should at least not insert junk
+    t.send("S")
+    txt = "".join(input_text(t))
+    check("shift+left no junk", "[" not in txt and ";" not in txt and "1;2" not in txt, t)
+    clear(t)
+
+
+def split_and_burst(t, form):
+    clear(t)
+    t.send("abcdef")
+    ss = "\x1bO" if form == "ss3" else "\x1b["
+    # escape sequence split across writes (slow link)
+    import os
+    os.write(t.fd, ss[:1].encode()); time.sleep(0.008)
+    os.write(t.fd, (ss[1:] + "D").encode()); t.pump(0.2)
+    t.send("1")
+    check(f"split {form} seq", "abcde1f" in input_text(t), t)
+    # key-repeat burst in one write
+    t.send((ss + "D") * 4, 0.3)
+    t.send("2")
+    check(f"burst {form} x4", "ab2cde1f" in input_text(t), t)
+    clear(t)
+
+
+def picker(t):
+    clear(t)
+    t.send("/model\r", 0.8)
+    s0 = styled(t)
+    t.arrow("down")
+    s1 = styled(t)
+    t.arrow("up")
+    s2 = styled(t)
+    check("picker down changes selection", s0 != s1, t)
+    check("picker up returns", s0 == s2, t)
+    t.send("\x1b", 0.4)
+    clear(t)
+
+
+def run(kitty, tag):
+    print("#####", tag)
+    t = new(kitty=kitty)
+    try:
+        basic(t, None, tag + " native")
+        basic(t, "csi" if t.appcursor() else "ss3", tag + " other-form")
+        cjk(t)
+        multiline(t)
+        modifiers(t)
+        split_and_burst(t, "ss3")
+        split_and_burst(t, "csi")
+        completion(t)
+        wrapped(t)
+        history(t)
+        picker(t)
+    finally:
+        t.close()
+
+
+if __name__ == "__main__":
+    run(False, "xterm")
+    run(True, "kitty")
+    for term in ("screen-256color", "tmux-256color", "linux", "vt220", "xterm"):
+        print("#####", term)
+        t = Term(args=("-b", base, "-k", "sk-test"), term=term)
+        try:
+            basic(t, "ss3", term + " ss3")
+            basic(t, "csi", term + " csi")
+            modifiers(t)
+            multiline(t)
+            cjk(t)
+        finally:
+            t.close()
+    print("FAILED:", len(FAILS))
+    for f in FAILS:
+        print("  -", f)
+    sys.exit(min(len(FAILS), 100))

scripts/tui_keys/provider.py

@@ -0,0 +1,65 @@
+"""TUI /provider and /key against a fake API whose /models checks the key.
+
+  nix-shell -p python3Packages.pyte --run "python3 scripts/tui_keys/provider.py"
+
+A wrong key is asked for again, a good one is saved and switches the
+provider; /key replaces it. Same code path as the WebUI (provider_switch.c).
+"""
+import json, os, sys, threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from harness import Term
+from keys import check, base
+
+GOOD = {"sk-good", "sk-good2"}
+
+
+class B(BaseHTTPRequestHandler):
+    def log_message(self, *a):
+        pass
+
+    def do_GET(self):
+        auth = self.headers.get("Authorization", "")
+        ok = auth.startswith("Bearer ") and auth[7:] in GOOD
+        body = json.dumps({"data": [{"id": "fake-one"}]} if ok else {"error": {"message": "bad key"}}).encode()
+        self.send_response(200 if ok else 401)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+
+srv = ThreadingHTTPServer(("127.0.0.1", 0), B)
+threading.Thread(target=srv.serve_forever, daemon=True).start()
+
+t = Term(args=("-b", base, "-k", "sk-test"))
+cfg = os.path.join(t.home, ".config", "cst-agent")
+os.makedirs(cfg, exist_ok=True)
+t.close()
+with open(os.path.join(cfg, "models.json"), "w") as f:
+    json.dump({"providers": {"fakeb": {"api_base": "http://127.0.0.1:%d/v1" % srv.server_address[1],
+                                       "key_env": "FAKEB_API_KEY", "default_model": ""}}}, f)
+t = Term(args=("-b", base, "-k", "sk-test"), home=t.home, env={"FAKEB_API_KEY": ""})
+creds = os.path.join(cfg, "credentials")
+
+
+def screen():
+    return "\n".join(t.lines())
+
+
+t.send("/provider fakeb\r", 0.8)
+check("a key prompt for fakeb", "API key for fakeb" in screen(), t)
+t.send("sk-bad\r", 1.5)
+check("a wrong key is asked for again", "rejected that key" in screen(), t)
+check("the wrong key is not saved", not os.path.exists(creds) or "sk-bad" not in open(creds).read(), t)
+t.send("sk-good\r", 2.0)
+check("switched to fakeb", "provider → fakeb" in screen(), t)
+check("the good key is saved", os.path.exists(creds) and "fakeb.api_key=sk-good" in open(creds).read(), t)
+check("no key on screen", "sk-good" not in screen() and "sk-bad" not in screen(), t)
+t.send("/key\r", 0.8)
+t.send("sk-good2\r", 2.0)
+check("/key replaces it", "fakeb.api_key=sk-good2" in open(creds).read(), t)
+t.close()
+from keys import FAILS
+print("FAILED:", len(FAILS))
+sys.exit(min(len(FAILS), 100))

src/agent_store.c

@@ -288,7 +288,10 @@ int cst_agent_store_info(const char *workspace, const char *id,
     cJSON *o = cJSON_Parse(line);
     const cJSON *r = cJSON_GetObjectItemCaseSensitive(o, "role");
     const cJSON *c = cJSON_GetObjectItemCaseSensitive(o, "content");
-    if (cJSON_IsString(r) && strcmp(r->valuestring, "user") == 0 &&
+    const cJSON *k = cJSON_GetObjectItemCaseSensitive(
+        cJSON_GetObjectItemCaseSensitive(o, "meta"), "kind");
+    int note = cJSON_IsString(k) && strcmp(k->valuestring, "note") == 0;
+    if (cJSON_IsString(r) && strcmp(r->valuestring, "user") == 0 && !note &&
         cJSON_IsString(c) && c->valuestring[0]) {
       clip_line(info->first_user, sizeof(info->first_user), c->valuestring);
       have_first = 1;

src/attach.c

@@ -0,0 +1,646 @@
+#ifndef _DEFAULT_SOURCE
+#define _DEFAULT_SOURCE
+#endif
+
+#include "cJSON.h"
+#include "cst_attach.h"
+#include "cst_util.h"
+#include "os_compat.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+/* --- base64 -------------------------------------------------------------- */
+
+static const char B64[] =
+    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+char *cst_base64_encode(const void *data, size_t n) {
+  const unsigned char *p = data;
+  size_t olen = ((n + 2) / 3) * 4;
+  char *out = malloc(olen + 1);
+  if (!out)
+    return NULL;
+  size_t o = 0;
+  for (size_t i = 0; i < n; i += 3) {
+    unsigned v = (unsigned)p[i] << 16;
+    if (i + 1 < n)
+      v |= (unsigned)p[i + 1] << 8;
+    if (i + 2 < n)
+      v |= (unsigned)p[i + 2];
+    out[o++] = B64[(v >> 18) & 63];
+    out[o++] = B64[(v >> 12) & 63];
+    out[o++] = i + 1 < n ? B64[(v >> 6) & 63] : '=';
+    out[o++] = i + 2 < n ? B64[v & 63] : '=';
+  }
+  out[o] = 0;
+  return out;
+}
+
+static int b64_val(unsigned char c) {
+  if (c >= 'A' && c <= 'Z')
+    return c - 'A';
+  if (c >= 'a' && c <= 'z')
+    return c - 'a' + 26;
+  if (c >= '0' && c <= '9')
+    return c - '0' + 52;
+  if (c == '+' || c == '-')
+    return 62;
+  if (c == '/' || c == '_')
+    return 63;
+  return -1;
+}
+
+char *cst_base64_decode(const char *s, size_t n, size_t *out_len) {
+  if (out_len)
+    *out_len = 0;
+  if (!s)
+    return NULL;
+  char *out = malloc(n / 4 * 3 + 4);
+  if (!out)
+    return NULL;
+  size_t o = 0;
+  unsigned acc = 0;
+  int bits = 0;
+  for (size_t i = 0; i < n; i++) {
+    unsigned char c = (unsigned char)s[i];
+    if (c == '=')
+      break;
+    if (c == ' ' || c == '\t' || c == '\r' || c == '\n')
+      continue;
+    int v = b64_val(c);
+    if (v < 0) {
+      free(out);
+      return NULL;
+    }
+    acc = (acc << 6) | (unsigned)v;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      out[o++] = (char)((acc >> bits) & 0xFF);
+    }
+  }
+  if (out_len)
+    *out_len = o;
+  return out;
+}
+
+/* --- format sniffing ----------------------------------------------------- */
+
+static int be32(const unsigned char *p) {
+  return (p[0] << 24) | (p[1] << 16) | (p[2] << 8) | p[3];
+}
+
+static int le32(const unsigned char *p) {
+  return (int)((unsigned)p[0] | ((unsigned)p[1] << 8) |
+               ((unsigned)p[2] << 16) | ((unsigned)p[3] << 24));
+}
+
+static int le16(const unsigned char *p) {
+  return (int)((unsigned)p[0] | ((unsigned)p[1] << 8));
+}
+
+static const char *mime_of_ext(const char *mime) {
+  if (strcmp(mime, "image/png") == 0)
+    return "png";
+  if (strcmp(mime, "image/jpeg") == 0)
+    return "jpg";
+  if (strcmp(mime, "image/gif") == 0)
+    return "gif";
+  if (strcmp(mime, "image/webp") == 0)
+    return "webp";
+  if (strcmp(mime, "image/bmp") == 0)
+    return "bmp";
+  return "bin";
+}
+
+/* A JPEG SOF marker carries the frame size; skip it when scanning. */
+static int jpeg_sof(int marker) {
+  switch (marker) {
+  case 0xC0:
+  case 0xC1:
+  case 0xC2:
+  case 0xC3:
+  case 0xC5:
+  case 0xC6:
+  case 0xC7:
+  case 0xC9:
+  case 0xCA:
+  case 0xCB:
+  case 0xCD:
+  case 0xCE:
+  case 0xCF:
+    return 1;
+  default:
+    return 0;
+  }
+}
+
+int cst_attach_sniff(const void *data, size_t n, char *mime, size_t mime_sz) {
+  const unsigned char *p = data;
+  const char *m = NULL;
+  if (n >= 8 && memcmp(p, "\x89PNG\r\n\x1a\n", 8) == 0)
+    m = "image/png";
+  else if (n >= 3 && p[0] == 0xFF && p[1] == 0xD8 && p[2] == 0xFF)
+    m = "image/jpeg";
+  else if (n >= 6 && memcmp(p, "GIF87a", 6) == 0)
+    m = "image/gif";
+  else if (n >= 6 && memcmp(p, "GIF89a", 6) == 0)
+    m = "image/gif";
+  else if (n >= 12 && memcmp(p, "RIFF", 4) == 0 && memcmp(p + 8, "WEBP", 4) == 0)
+    m = "image/webp";
+  else if (n >= 2 && p[0] == 'B' && p[1] == 'M')
+    m = "image/bmp";
+  if (!m)
+    return -1;
+  snprintf(mime, mime_sz, "%s", m);
+  return 0;
+}
+
+/* PNG / GIF / BMP are direct; JPEG needs a marker walk; WebP has three
+ * container flavours. */
+int cst_attach_dimensions(const void *data, size_t n, int *w, int *h) {
+  const unsigned char *p = data;
+  *w = *h = 0;
+  char mime[32];
+  if (cst_attach_sniff(data, n, mime, sizeof(mime)) != 0)
+    return -1;
+
+  if (strcmp(mime, "image/png") == 0) {
+    /* 8 signature + 4 length + "IHDR" + w + h */
+    if (n < 24 || memcmp(p + 12, "IHDR", 4) != 0)
+      return -1;
+    *w = be32(p + 16);
+    *h = be32(p + 20);
+    return 0;
+  }
+  if (strcmp(mime, "image/gif") == 0) {
+    if (n < 10)
+      return -1;
+    *w = le16(p + 6);
+    *h = le16(p + 8);
+    return 0;
+  }
+  if (strcmp(mime, "image/bmp") == 0) {
+    if (n < 26)
+      return -1;
+    int wi = le32(p + 18);
+    int hi = le32(p + 22);
+    if (wi < 0)
+      wi = -wi; /* bottom-up rows are stored with a negative height */
+    if (hi < 0)
+      hi = -hi;
+    *w = wi;
+    *h = hi;
+    return 0;
+  }
+  if (strcmp(mime, "image/webp") == 0) {
+    if (n < 30)
+      return -1;
+    const unsigned char *c = p + 12;
+    if (memcmp(c, "VP8 ", 4) == 0) {
+      /* 4 tag + 3 start code, then 16-bit width / height (14 bits each) */
+      if (n < 30 || !(c[7] == 0x9D && c[8] == 0x01 && c[9] == 0x2A))
+        return -1;
+      *w = le16(c + 10) & 0x3FFF;
+      *h = le16(c + 12) & 0x3FFF;
+      return 0;
+    }
+    if (memcmp(c, "VP8L", 4) == 0) {
+      if (n < 25 || c[8] != 0x2F)
+        return -1;
+      unsigned b = (unsigned)c[9] | ((unsigned)c[10] << 8) |
+                   ((unsigned)c[11] << 16) | ((unsigned)c[12] << 24);
+      *w = (int)(b & 0x3FFF) + 1;
+      *h = (int)((b >> 14) & 0x3FFF) + 1;
+      return 0;
+    }
+    if (memcmp(c, "VP8X", 4) == 0) {
+      if (n < 30)
+        return -1;
+      *w = (int)((unsigned)c[12] | ((unsigned)c[13] << 8) |
+                 ((unsigned)c[14] << 16)) + 1;
+      *h = (int)((unsigned)c[15] | ((unsigned)c[16] << 8) |
+                 ((unsigned)c[17] << 16)) + 1;
+      return 0;
+    }
+    return -1;
+  }
+  if (strcmp(mime, "image/jpeg") == 0) {
+    size_t i = 2;
+    while (i + 3 < n) {
+      if (p[i] != 0xFF)
+        return -1; /* lost sync */
+      unsigned marker = p[i + 1];
+      i += 2;
+      if (marker == 0xD8 || (marker >= 0xD0 && marker <= 0xD7))
+        continue; /* standalone markers: no payload */
+      if (marker == 0xD9 || marker == 0x01)
+        continue;
+      if (i + 1 >= n)
+        return -1;
+      size_t seg = (size_t)((p[i] << 8) | p[i + 1]);
+      if (seg < 2 || i + seg > n)
+        return -1;
+      if (jpeg_sof((int)marker) && seg >= 7) {
+        *h = (p[i + 3] << 8) | p[i + 4];
+        *w = (p[i + 5] << 8) | p[i + 6];
+        return 0;
+      }
+      i += seg;
+    }
+  }
+  return -1;
+}
+
+/* --- storage ------------------------------------------------------------- */
+
+/* <session dir>/attachments/<session stem> — beside the JSONL so moving the
+ * workspace keeps the two together. */
+int cst_attach_dir(const char *session_path, char *out, size_t out_sz) {
+  if (!session_path || !session_path[0])
+    return -1;
+  char dir[OS_PATH_MAX];
+  snprintf(dir, sizeof(dir), "%s", session_path);
+  char *slash = strrchr(dir, '/');
+#ifdef _WIN32
+  char *bslash = strrchr(dir, '\\');
+  if (bslash && (!slash || bslash > slash))
+    slash = bslash;
+#endif
+  char leaf[256];
+  const char *base = slash ? slash + 1 : dir;
+  size_t bl = strlen(base);
+  if (bl >= sizeof(leaf))
+    bl = sizeof(leaf) - 1;
+  memcpy(leaf, base, bl);
+  leaf[bl] = 0;
+  if (slash)
+    *(slash + 1) = 0;
+  else {
+    dir[0] = '.';
+    dir[1] = 0;
+  }
+  char *dot = strstr(leaf, ".jsonl");
+  if (dot)
+    *dot = 0;
+  char rel[320];
+  snprintf(rel, sizeof(rel), "attachments/%s", leaf[0] ? leaf : "session");
+  char full[OS_PATH_MAX];
+  if (os_path_join(full, sizeof(full), dir, rel) != 0)
+    return -1;
+  if (os_mkdir_p(full, 0700) != 0)
+    return -1;
+  snprintf(out, out_sz, "%s", full);
+  return 0;
+}
+
+/* Stored names are "<id>.<ext>" made by store(); anything else in a JSONL
+ * (hand-edited or crafted) could point outside the attachment directory. */
+int cst_attach_rel_ok(const char *rel) {
+  if (!rel || !rel[0] || rel[0] == '.')
+    return 0;
+  for (const char *p = rel; *p; p++) {
+    char c = *p;
+    if (!((c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') ||
+          (c >= '0' && c <= '9') || c == '-' || c == '_' || c == '.'))
+      return 0;
+  }
+  return strstr(rel, "..") == NULL;
+}
+
+int cst_attach_full_path(const char *session_path, const cst_attachment_t *a,
+                         char *out, size_t out_sz) {
+  if (!a || !cst_attach_rel_ok(a->rel))
+    return -1;
+  char dir[OS_PATH_MAX];
+  if (cst_attach_dir(session_path, dir, sizeof(dir)) != 0)
+    return -1;
+  return os_path_join(out, out_sz, dir, a->rel);
+}
+
+static char *read_whole(const char *path, size_t *out_len, size_t max) {
+  FILE *f = fopen(path, "rb");
+  if (!f)
+    return NULL;
+  cst_buf_t b = {0};
+  char chunk[16384];
+  size_t n;
+  while ((n = fread(chunk, 1, sizeof(chunk), f)) > 0) {
+    if (b.len + n > max || cst_buf_append(&b, chunk, n) != 0) {
+      cst_buf_free(&b);
+      fclose(f);
+      return NULL;
+    }
+  }
+  fclose(f);
+  *out_len = b.len;
+  return cst_buf_steal(&b);
+}
+
+/* FNV over the bytes, the name and the clock: short, stable, unique enough
+ * inside one session. */
+static void make_id(const char *name, const char *data, size_t n, char *out,
+                    size_t out_sz) {
+  uint64_t h = cst_fnv1a64(CST_FNV_INIT, data, n > 4096 ? 4096 : n);
+  h = cst_fnv1a64(h, name, strlen(name));
+  h = cst_fnv1a64(h, &n, sizeof(n));
+  double now = os_now_ms();
+  h = cst_fnv1a64(h, &now, sizeof(now));
+  h = cst_fnv1a64(h, &(int){os_getpid()}, sizeof(int));
+  snprintf(out, out_sz, "img-%08x", (unsigned)(h & 0xFFFFFFFFu));
+}
+
+static cst_attachment_t *store(const char *session_path, const char *name,
+                               const char *data, size_t n, const char *origin,
+                               char *err, size_t err_sz) {
+  if (!name || !name[0])
+    name = "image";
+  char mime[32];
+  if (cst_attach_sniff(data, n, mime, sizeof(mime)) != 0) {
+    snprintf(err, err_sz,
+             "not a supported image (PNG, JPEG, GIF, WebP or BMP; "
+             "checked by content, not by extension)");
+    return NULL;
+  }
+  if (n > CST_ATTACH_MAX_BYTES) {
+    snprintf(err, err_sz, "image is %.1f MB; the limit is %d MB",
+             (double)n / (1024 * 1024), (int)(CST_ATTACH_MAX_BYTES >> 20));
+    return NULL;
+  }
+  char dir[OS_PATH_MAX];
+  if (cst_attach_dir(session_path, dir, sizeof(dir)) != 0) {
+    snprintf(err, err_sz, "cannot create the attachment directory");
+    return NULL;
+  }
+  cst_attachment_t *a = calloc(1, sizeof(*a));
+  if (!a) {
+    snprintf(err, err_sz, "out of memory");
+    return NULL;
+  }
+  make_id(name, data, n, a->id, sizeof(a->id));
+  snprintf(a->rel, sizeof(a->rel), "%s.%s", a->id, mime_of_ext(mime));
+  snprintf(a->name, sizeof(a->name), "%s", name && name[0] ? name : "image");
+  snprintf(a->mime, sizeof(a->mime), "%s", mime);
+  snprintf(a->origin, sizeof(a->origin), "%s", origin ? origin : "user");
+  snprintf(a->detail, sizeof(a->detail), "auto");
+  a->bytes = (long long)n;
+  cst_attach_dimensions(data, n, &a->width, &a->height);
+
+  char full[OS_PATH_MAX];
+  if (cst_attach_full_path(session_path, a, full, sizeof(full)) != 0) {
+    snprintf(err, err_sz, "attachment path is too long");
+    free(a);
+    return NULL;
+  }
+  FILE *f = fopen(full, "wb");
+  if (!f) {
+    snprintf(err, err_sz, "cannot write %.200s", full);
+    free(a);
+    return NULL;
+  }
+  size_t w = fwrite(data, 1, n, f);
+  if (fclose(f) != 0 || w != n) {
+    snprintf(err, err_sz, "cannot write %.200s", full);
+    free(a);
+    return NULL;
+  }
+  return a;
+}
+
+cst_attachment_t *cst_attach_import_bytes(const char *session_path,
+                                          const char *name, const char *data,
+                                          size_t n, char *err, size_t err_sz) {
+  char dummy[8];
+  if (!err || !err_sz) {
+    err = dummy;
+    err_sz = sizeof(dummy);
+  }
+  err[0] = 0;
+  if (!session_path || !session_path[0]) {
+    snprintf(err, err_sz, "no session to store the image in");
+    return NULL;
+  }
+  if (!data || !n) {
+    snprintf(err, err_sz, "image is empty");
+    return NULL;
+  }
+  return store(session_path, name, data, n, "user", err, err_sz);
+}
+
+cst_attachment_t *cst_attach_import_file(const char *session_path,
+                                         const char *src_path, char *err,
+                                         size_t err_sz) {
+  char dummy[8];
+  if (!err || !err_sz) {
+    err = dummy;
+    err_sz = sizeof(dummy);
+  }
+  err[0] = 0;
+  size_t n = 0;
+  char *data = read_whole(src_path, &n, CST_ATTACH_MAX_BYTES);
+  if (!data) {
+    snprintf(err, err_sz, "cannot read %.300s (or it is larger than %d MB)",
+             src_path, (int)(CST_ATTACH_MAX_BYTES >> 20));
+    return NULL;
+  }
+  const char *leaf = src_path;
+  for (const char *p = src_path; *p; p++)
+    if (*p == '/' || *p == '\\')
+      leaf = p + 1;
+  cst_attachment_t *a = store(session_path, leaf, data, n, "user", err, err_sz);
+  free(data);
+  return a;
+}
+
+char *cst_attach_read(const char *session_path, const cst_attachment_t *a,
+                      size_t *out_len, char *err, size_t err_sz) {
+  char dummy[8];
+  if (!err || !err_sz) {
+    err = dummy;
+    err_sz = sizeof(dummy);
+  }
+  err[0] = 0;
+  char full[OS_PATH_MAX];
+  if (cst_attach_full_path(session_path, a, full, sizeof(full)) != 0) {
+    snprintf(err, err_sz, "attachment has no stored file");
+    return NULL;
+  }
+  char *data = read_whole(full, out_len, CST_ATTACH_MAX_BYTES);
+  if (!data) {
+    snprintf(err, err_sz,
+             "%.200s is missing; the image was deleted from the session "
+             "store",
+             a->name);
+    return NULL;
+  }
+  char mime[32];
+  if (cst_attach_sniff(data, *out_len, mime, sizeof(mime)) != 0) {
+    snprintf(err, err_sz, "%.200s in the session store is no longer an image",
+             a->name);
+    free(data);
+    return NULL;
+  }
+  return data;
+}
+
+char *cst_attach_data_url(const char *session_path, const cst_attachment_t *a) {
+  char err[256];
+  size_t n = 0;
+  char *data = cst_attach_read(session_path, a, &n, err, sizeof(err));
+  if (!data)
+    return NULL;
+  char mime[32];
+  cst_attach_sniff(data, n, mime, sizeof(mime)); /* the bytes decide */
+  char *b64 = cst_base64_encode(data, n);
+  free(data);
+  if (!b64)
+    return NULL;
+  cst_buf_t b = {0};
+  cst_buf_printf(&b, "data:%s;base64,", mime);
+  cst_buf_puts(&b, b64);
+  free(b64);
+  return cst_buf_steal(&b);
+}
+
+void cst_attach_describe(const cst_attachment_t *a, char *out, size_t out_sz) {
+  if (!a) {
+    snprintf(out, out_sz, "(none)");
+    return;
+  }
+  const char *kind = strncmp(a->mime, "image/", 6) == 0 ? a->mime + 6 : a->mime;
+  char dim[32] = "";
+  if (a->width > 0 && a->height > 0)
+    snprintf(dim, sizeof(dim), "%dx%d ", a->width, a->height);
+  out[0] = 0;
+  if (a->bytes >= 1024 * 1024)
+    snprintf(out, out_sz, "%s%s %.1f MB", dim, kind,
+             (double)a->bytes / (1024 * 1024));
+  else
+    snprintf(out, out_sz, "%s%s %.0f KB", dim, kind,
+             (double)a->bytes / 1024);
+}
+
+/* --- lifetime ------------------------------------------------------------ */
+
+void cst_attach_free(cst_attachment_t *a) { free(a); }
+
+/* Entries always live in one array (a 1-element array for a single import),
+ * so freeing the block releases them all. */
+void cst_attachments_free(cst_attachment_t *list, int n) {
+  (void)n;
+  free(list);
+}
+
+cst_attachment_t *cst_attachments_dup(const cst_attachment_t *list, int n) {
+  if (!list || n <= 0)
+    return NULL;
+  cst_attachment_t *out = calloc((size_t)n, sizeof(*out));
+  if (!out)
+    return NULL;
+  for (int i = 0; i < n; i++)
+    out[i] = list[i];
+  return out;
+}
+
+int cst_attachments_push(cst_attachment_t **list, int *n, int *cap,
+                         const cst_attachment_t *src) {
+  if (!list || !n || !cap || !src)
+    return -1;
+  if (*n == *cap) {
+    int nc = *cap ? *cap * 2 : 4;
+    cst_attachment_t *nv = realloc(*list, (size_t)nc * sizeof(**list));
+    if (!nv)
+      return -1;
+    *list = nv;
+    *cap = nc;
+  }
+  (*list)[(*n)++] = *src;
+  return 0;
+}
+
+/* --- JSONL --------------------------------------------------------------- */
+
+char *cst_attachments_to_json(const cst_attachment_t *list, int n) {
+  if (!list || n <= 0)
+    return NULL;
+  cJSON *arr = cJSON_CreateArray();
+  if (!arr)
+    return NULL;
+  for (int i = 0; i < n; i++) {
+    const cst_attachment_t *a = &list[i];
+    cJSON *o = cJSON_CreateObject();
+    cJSON_AddStringToObject(o, "id", a->id);
+    cJSON_AddStringToObject(o, "name", a->name);
+    cJSON_AddStringToObject(o, "mime", a->mime);
+    cJSON_AddStringToObject(o, "rel", a->rel);
+    cJSON_AddNumberToObject(o, "bytes", (double)a->bytes);
+    if (a->width > 0 && a->height > 0) {
+      cJSON_AddNumberToObject(o, "width", a->width);
+      cJSON_AddNumberToObject(o, "height", a->height);
+    }
+    if (a->detail[0] && strcmp(a->detail, "auto") != 0)
+      cJSON_AddStringToObject(o, "detail", a->detail);
+    if (a->origin[0])
+      cJSON_AddStringToObject(o, "origin", a->origin);
+    cJSON_AddItemToArray(arr, o);
+  }
+  char *s = cJSON_PrintUnformatted(arr);
+  cJSON_Delete(arr);
+  return s;
+}
+
+cst_attachment_t *cst_attachments_from_json(const void *array_json, int *n_out) {
+  if (n_out)
+    *n_out = 0;
+  const cJSON *arr = array_json;
+  if (!cJSON_IsArray(arr))
+    return NULL;
+  int n = cJSON_GetArraySize(arr);
+  if (n <= 0)
+    return NULL;
+  cst_attachment_t *list = calloc((size_t)n, sizeof(*list));
+  if (!list)
+    return NULL;
+  int k = 0;
+  const cJSON *it = NULL;
+  cJSON_ArrayForEach(it, arr) {
+    if (!cJSON_IsObject(it))
+      continue;
+    const cJSON *jid = cJSON_GetObjectItemCaseSensitive(it, "id");
+    const cJSON *jrel = cJSON_GetObjectItemCaseSensitive(it, "rel");
+    if (!cJSON_IsString(jid) || !cJSON_IsString(jrel) ||
+        !cst_attach_rel_ok(jrel->valuestring))
+      continue;
+    cst_attachment_t *a = &list[k];
+    snprintf(a->id, sizeof(a->id), "%s", jid->valuestring);
+    snprintf(a->rel, sizeof(a->rel), "%s", jrel->valuestring);
+    const cJSON *v = cJSON_GetObjectItemCaseSensitive(it, "name");
+    snprintf(a->name, sizeof(a->name), "%s",
+             cJSON_IsString(v) ? v->valuestring : a->id);
+    v = cJSON_GetObjectItemCaseSensitive(it, "mime");
+    snprintf(a->mime, sizeof(a->mime), "%s",
+             cJSON_IsString(v) ? v->valuestring : "image/*");
+    v = cJSON_GetObjectItemCaseSensitive(it, "bytes");
+    a->bytes = cJSON_IsNumber(v) ? (long long)v->valuedouble : 0;
+    v = cJSON_GetObjectItemCaseSensitive(it, "width");
+    a->width = cJSON_IsNumber(v) ? v->valueint : 0;
+    v = cJSON_GetObjectItemCaseSensitive(it, "height");
+    a->height = cJSON_IsNumber(v) ? v->valueint : 0;
+    v = cJSON_GetObjectItemCaseSensitive(it, "detail");
+    snprintf(a->detail, sizeof(a->detail), "%s",
+             cJSON_IsString(v) ? v->valuestring : "auto");
+    v = cJSON_GetObjectItemCaseSensitive(it, "origin");
+    snprintf(a->origin, sizeof(a->origin), "%s",
+             cJSON_IsString(v) ? v->valuestring : "");
+    k++;
+  }
+  if (k == 0) {
+    free(list);
+    return NULL;
+  }
+  if (n_out)
+    *n_out = k;
+  return list;
+}

src/clipboard.c

@@ -0,0 +1,482 @@
+#include "cst_clipboard.h"
+#include "cst_attach.h"
+#include "os_compat.h"
+
+#include <ctype.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#ifdef _WIN32
+#include <windows.h>
+#else
+#include <unistd.h>
+#endif
+
+static void set_err(char *err, size_t err_sz, const char *msg) {
+  if (err && err_sz)
+    snprintf(err, err_sz, "%s", msg);
+}
+
+static void put_le32(unsigned char *p, unsigned long v) {
+  p[0] = (unsigned char)(v & 0xff);
+  p[1] = (unsigned char)((v >> 8) & 0xff);
+  p[2] = (unsigned char)((v >> 16) & 0xff);
+  p[3] = (unsigned char)((v >> 24) & 0xff);
+}
+
+static void put_be32(unsigned char *p, unsigned long v) {
+  p[0] = (unsigned char)((v >> 24) & 0xff);
+  p[1] = (unsigned char)((v >> 16) & 0xff);
+  p[2] = (unsigned char)((v >> 8) & 0xff);
+  p[3] = (unsigned char)(v & 0xff);
+}
+
+static unsigned long get_le32(const unsigned char *p) {
+  return (unsigned long)p[0] | (unsigned long)p[1] << 8 |
+         (unsigned long)p[2] << 16 | (unsigned long)p[3] << 24;
+}
+
+static unsigned long crc32_update(unsigned long crc, const unsigned char *p,
+                                  size_t n) {
+  static unsigned long table[256];
+  static int ready;
+  if (!ready) {
+    for (unsigned long i = 0; i < 256; i++) {
+      unsigned long c = i;
+      for (int k = 0; k < 8; k++)
+        c = c & 1 ? 0xedb88320UL ^ (c >> 1) : c >> 1;
+      table[i] = c;
+    }
+    ready = 1;
+  }
+  crc ^= 0xffffffffUL;
+  for (size_t i = 0; i < n; i++)
+    crc = table[(crc ^ p[i]) & 0xff] ^ (crc >> 8);
+  return crc ^ 0xffffffffUL;
+}
+
+static unsigned char *png_chunk(unsigned char *o, const char *type,
+                                const unsigned char *data, size_t n) {
+  put_be32(o, (unsigned long)n);
+  memcpy(o + 4, type, 4);
+  if (n)
+    memcpy(o + 8, data, n);
+  put_be32(o + 8 + n, crc32_update(0, o + 4, n + 4));
+  return o + 12 + n;
+}
+
+/* RGB rows (filter byte 0 each) in stored deflate blocks: no compressor in
+ * the tree, and clipboard screenshots stay well under the attach cap. */
+static char *png_from_raw(const unsigned char *raw, size_t raw_n, long w,
+                          long h, size_t *n) {
+  size_t blocks = raw_n / 65535 + 1;
+  size_t z_n = 2 + raw_n + blocks * 5 + 4;
+  size_t total = 8 + (12 + 13) + (12 + z_n) + 12;
+  unsigned char *out = malloc(total);
+  unsigned char *z = malloc(z_n);
+  if (!out || !z) {
+    free(out);
+    free(z);
+    return NULL;
+  }
+  unsigned char *q = z;
+  *q++ = 0x78;
+  *q++ = 0x01;
+  unsigned long a = 1, b = 0;
+  size_t left = raw_n, pos = 0;
+  do {
+    size_t len = left > 65535 ? 65535 : left;
+    *q++ = left == len ? 1 : 0;
+    q[0] = (unsigned char)(len & 0xff);
+    q[1] = (unsigned char)(len >> 8);
+    q[2] = (unsigned char)(~len & 0xff);
+    q[3] = (unsigned char)((~len >> 8) & 0xff);
+    q += 4;
+    memcpy(q, raw + pos, len);
+    for (size_t i = 0; i < len; i++) {
+      a = (a + raw[pos + i]) % 65521;
+      b = (b + a) % 65521;
+    }
+    q += len;
+    pos += len;
+    left -= len;
+  } while (left);
+  put_be32(q, b << 16 | a);
+  q += 4;
+
+  unsigned char ihdr[13];
+  put_be32(ihdr, (unsigned long)w);
+  put_be32(ihdr + 4, (unsigned long)h);
+  ihdr[8] = 8; /* bit depth */
+  ihdr[9] = 2; /* RGB */
+  ihdr[10] = ihdr[11] = ihdr[12] = 0;
+  unsigned char *o = out;
+  memcpy(o, "\x89PNG\r\n\x1a\n", 8);
+  o = png_chunk(o + 8, "IHDR", ihdr, sizeof(ihdr));
+  o = png_chunk(o, "IDAT", z, (size_t)(q - z));
+  o = png_chunk(o, "IEND", NULL, 0);
+  free(z);
+  *n = (size_t)(o - out);
+  return (char *)out;
+}
+
+/* CF_DIB is a BMP without its 14-byte file header; the pixel offset depends
+ * on the header size, BI_BITFIELDS masks and the color table. */
+char *cst_dib_to_image(const void *dib_v, size_t sz, size_t *n) {
+  const unsigned char *dib = dib_v;
+  if (!dib || sz < 40)
+    return NULL;
+  unsigned long hsize = get_le32(dib);
+  long w = (long)(int)get_le32(dib + 4);
+  long hh = (long)(int)get_le32(dib + 8);
+  unsigned bits = (unsigned)(dib[14] | dib[15] << 8);
+  unsigned long comp = get_le32(dib + 16);
+  unsigned long used = get_le32(dib + 32);
+  if (hsize < 40 || hsize > sz)
+    return NULL;
+  size_t off = hsize;
+  if (hsize == 40 && comp == 3 /* BI_BITFIELDS */)
+    off += 12;
+  size_t colors = used;
+  if (!colors && bits <= 8)
+    colors = (size_t)1 << bits;
+  if (colors > 256)
+    return NULL;
+  off += colors * 4;
+  if (off > sz)
+    return NULL;
+
+  long h = hh < 0 ? -hh : hh;
+  if ((bits == 24 || bits == 32) && (comp == 0 || comp == 3) && w > 0 &&
+      h > 0 && w <= 32768 && h <= 32768) {
+    size_t stride = ((size_t)w * bits / 8 + 3) & ~(size_t)3;
+    size_t raw_n = (size_t)h * (1 + (size_t)w * 3);
+    if (stride * (size_t)h <= sz - off && raw_n < CST_ATTACH_MAX_BYTES) {
+      unsigned char *raw = malloc(raw_n);
+      if (!raw)
+        return NULL;
+      size_t bpp = bits / 8;
+      for (long y = 0; y < h; y++) {
+        long src_y = hh > 0 ? h - 1 - y : y; /* positive height = bottom-up */
+        const unsigned char *s = dib + off + (size_t)src_y * stride;
+        unsigned char *d = raw + (size_t)y * (1 + (size_t)w * 3);
+        *d++ = 0;
+        for (long x = 0; x < w; x++, s += bpp) {
+          *d++ = s[2];
+          *d++ = s[1];
+          *d++ = s[0];
+        }
+      }
+      char *png = png_from_raw(raw, raw_n, w, h, n);
+      free(raw);
+      return png;
+    }
+  }
+
+  char *out = malloc(14 + sz);
+  if (!out)
+    return NULL;
+  unsigned char *hd = (unsigned char *)out;
+  hd[0] = 'B';
+  hd[1] = 'M';
+  put_le32(hd + 2, (unsigned long)(14 + sz));
+  put_le32(hd + 6, 0);
+  put_le32(hd + 10, (unsigned long)(14 + off));
+  memcpy(out + 14, dib, sz);
+  *n = 14 + sz;
+  return out;
+}
+
+#ifdef _WIN32
+
+int cst_clipboard_image(char **data, size_t *n, char *err, size_t err_sz) {
+  *data = NULL;
+  *n = 0;
+  UINT png = RegisterClipboardFormatA("PNG");
+  if (!OpenClipboard(NULL)) {
+    set_err(err, err_sz, "could not open the clipboard");
+    return -1;
+  }
+  HANDLE h = NULL;
+  int is_png = 0;
+  if (png && IsClipboardFormatAvailable(png)) {
+    h = GetClipboardData(png);
+    is_png = 1;
+  } else if (IsClipboardFormatAvailable(CF_DIB)) {
+    h = GetClipboardData(CF_DIB);
+  }
+  const unsigned char *p = h ? GlobalLock(h) : NULL;
+  if (!p) {
+    CloseClipboard();
+    set_err(err, err_sz, "no image on the clipboard");
+    return -1;
+  }
+  size_t sz = (size_t)GlobalSize(h);
+  char *out = NULL;
+  if (sz > CST_ATTACH_MAX_BYTES) {
+    set_err(err, err_sz, "clipboard image is too large");
+  } else if (is_png) {
+    out = malloc(sz ? sz : 1);
+    if (out) {
+      memcpy(out, p, sz);
+      *n = sz;
+    }
+  } else {
+    out = cst_dib_to_image(p, sz, n);
+    if (!out)
+      set_err(err, err_sz, "clipboard bitmap is malformed");
+  }
+  GlobalUnlock(h);
+  CloseClipboard();
+  if (!out)
+    return -1;
+  *data = out;
+  return 0;
+}
+
+#else
+
+/* Runs cmd (stderr already redirected by the caller); 127 = not installed. */
+static int run_bytes(const char *cmd, char **data, size_t *n) {
+  os_run_result_t r;
+  memset(&r, 0, sizeof(r));
+  if (os_run_shell_c(NULL, cmd, CST_ATTACH_MAX_BYTES + 1, &r) != 0) {
+    os_run_result_free(&r);
+    return -1;
+  }
+  if (r.exit_code != 0 || r.out_len == 0) {
+    int code = r.exit_code == 127 ? 127 : -1;
+    os_run_result_free(&r);
+    return code;
+  }
+  *data = r.out;
+  *n = r.out_len;
+  return 0;
+}
+
+static int type_ok(const char *s, size_t n) {
+  if (n < 7 || n > 63 || strncmp(s, "image/", 6) != 0)
+    return 0;
+  for (size_t i = 0; i < n; i++)
+    if (!isalnum((unsigned char)s[i]) && !strchr("/.+-", s[i]))
+      return 0;
+  return 1;
+}
+
+/* Best image MIME type from a newline-separated list: PNG first. */
+static int pick_type(const char *list, size_t len, char *out, size_t out_sz) {
+  out[0] = 0;
+  size_t i = 0;
+  while (i < len) {
+    size_t j = i;
+    while (j < len && list[j] != '\n' && list[j] != '\r')
+      j++;
+    if (type_ok(list + i, j - i)) {
+      int is_png = j - i == 9 && strncmp(list + i, "image/png", 9) == 0;
+      if (is_png || !out[0])
+        snprintf(out, out_sz, "%.*s", (int)(j - i), list + i);
+      if (is_png)
+        break;
+    }
+    i = j + 1;
+  }
+  return out[0] ? 0 : -1;
+}
+
+static int via_lister(const char *list_cmd, const char *get_fmt,
+                      const char *tool, char **data, size_t *n, char *err,
+                      size_t err_sz) {
+  char *types = NULL;
+  size_t tn = 0;
+  int rc = run_bytes(list_cmd, &types, &tn);
+  if (rc == 127) {
+    char msg[96];
+    snprintf(msg, sizeof(msg), "reading the clipboard needs %s", tool);
+    set_err(err, err_sz, msg);
+    return -1;
+  }
+  char type[64];
+  int ok = rc == 0 && pick_type(types, tn, type, sizeof(type)) == 0;
+  free(types);
+  if (!ok) {
+    set_err(err, err_sz, "no image on the clipboard");
+    return -1;
+  }
+  char cmd[256];
+  snprintf(cmd, sizeof(cmd), get_fmt, type);
+  if (run_bytes(cmd, data, n) != 0) {
+    set_err(err, err_sz, "could not read the clipboard image");
+    return -1;
+  }
+  return 0;
+}
+
+#ifdef __APPLE__
+static int mac_image(char **data, size_t *n, char *err, size_t err_sz) {
+  int rc = run_bytes("pngpaste - 2>/dev/null", data, n);
+  if (rc == 0)
+    return 0;
+  char path[1024];
+  int fd = os_mkstemp(path, sizeof(path), "cst-clip");
+  if (fd < 0) {
+    set_err(err, err_sz, "could not create a temp file");
+    return -1;
+  }
+  close(fd);
+  char cmd[1600];
+  snprintf(cmd, sizeof(cmd),
+           "osascript -e 'set f to open for access (POSIX file \"%s\") with "
+           "write permission' -e 'set eof f to 0' -e 'write (the clipboard as "
+           "\xc2\xabclass PNGf\xc2\xbb) to f' -e 'close access f' "
+           ">/dev/null 2>&1",
+           path);
+  os_run_result_t r;
+  memset(&r, 0, sizeof(r));
+  int ran = os_run_shell_c(NULL, cmd, 4096, &r);
+  int code = r.exit_code;
+  os_run_result_free(&r);
+  char *buf = NULL;
+  size_t len = 0;
+  if (ran == 0 && code == 0) {
+    FILE *f = fopen(path, "rb");
+    if (f) {
+      char chunk[65536];
+      size_t got;
+      while ((got = fread(chunk, 1, sizeof(chunk), f)) > 0 &&
+             len <= CST_ATTACH_MAX_BYTES) {
+        char *nb = realloc(buf, len + got);
+        if (!nb)
+          break;
+        buf = nb;
+        memcpy(buf + len, chunk, got);
+        len += got;
+      }
+      fclose(f);
+    }
+  }
+  remove(path);
+  if (!buf || !len) {
+    free(buf);
+    set_err(err, err_sz, "no image on the clipboard");
+    return -1;
+  }
+  *data = buf;
+  *n = len;
+  return 0;
+}
+#endif
+
+int cst_clipboard_image(char **data, size_t *n, char *err, size_t err_sz) {
+  *data = NULL;
+  *n = 0;
+#ifdef __APPLE__
+  return mac_image(data, n, err, err_sz);
+#else
+  const char *wl = getenv("WAYLAND_DISPLAY");
+  if (wl && *wl)
+    return via_lister("wl-paste --list-types 2>/dev/null",
+                      "wl-paste --no-newline --type '%s' 2>/dev/null",
+                      "wl-clipboard (wl-paste)", data, n, err, err_sz);
+  const char *x = getenv("DISPLAY");
+  if (x && *x)
+    return via_lister("xclip -selection clipboard -t TARGETS -o 2>/dev/null",
+                      "xclip -selection clipboard -t '%s' -o 2>/dev/null",
+                      "xclip", data, n, err, err_sz);
+  set_err(err, err_sz, "no clipboard here (no Wayland or X11 display)");
+  return -1;
+#endif
+}
+
+#endif
+
+static int hexval(int c) {
+  if (c >= '0' && c <= '9')
+    return c - '0';
+  if (c >= 'a' && c <= 'f')
+    return c - 'a' + 10;
+  if (c >= 'A' && c <= 'F')
+    return c - 'A' + 10;
+  return -1;
+}
+
+/* file://[host]/path -> /path, percent-decoded; 0 on success. */
+static int from_file_uri(char *s) {
+  const char *p = s + 7;
+  const char *slash = strchr(p, '/');
+  if (!slash)
+    return -1;
+  if (slash != p && !(slash - p == 9 && strncmp(p, "localhost", 9) == 0))
+    return -1;
+  char *o = s;
+  for (const char *q = slash; *q; q++) {
+    if (*q == '%' && hexval(q[1]) >= 0 && hexval(q[2]) >= 0) {
+      *o++ = (char)(hexval(q[1]) * 16 + hexval(q[2]));
+      q += 2;
+    } else {
+      *o++ = *q;
+    }
+  }
+  *o = 0;
+#ifdef _WIN32
+  if (s[0] == '/' && isalpha((unsigned char)s[1]) && s[2] == ':')
+    memmove(s, s + 1, strlen(s));
+#endif
+  return s[0] ? 0 : -1;
+}
+
+static int is_space(char c) {
+  return c == ' ' || c == '\t' || c == '\r' || c == '\n';
+}
+
+int cst_paste_paths(const char *text, size_t len,
+                    char out[][CST_PASTE_PATH_MAX], int max) {
+  int n = 0;
+  size_t i = 0;
+  while (i < len) {
+    while (i < len && is_space(text[i]))
+      i++;
+    if (i >= len)
+      break;
+    if (n >= max)
+      return -1;
+    char *tok = out[n];
+    size_t k = 0;
+    char q = 0;
+    while (i < len) {
+      char c = text[i];
+      if (!c)
+        return -1;
+      if (q) {
+        if (c == q) {
+          q = 0;
+          i++;
+          continue;
+        }
+      } else {
+        if (c == '\'' || c == '"') {
+          q = c;
+          i++;
+          continue;
+        }
+        if (is_space(c))
+          break;
+#ifndef _WIN32
+        if (c == '\\' && i + 1 < len)
+          c = text[++i];
+#endif
+      }
+      if (k + 1 >= CST_PASTE_PATH_MAX)
+        return -1;
+      tok[k++] = c;
+      i++;
+    }
+    if (q || !k)
+      return -1;
+    tok[k] = 0;
+    if (strncmp(tok, "file://", 7) == 0 && from_file_uri(tok) != 0)
+      return -1;
+    n++;
+  }
+  return n > 0 ? n : -1;
+}

src/http_srv.c

@@ -0,0 +1,770 @@
+#ifndef _DEFAULT_SOURCE
+#define _DEFAULT_SOURCE
+#endif
+
+#include "cst_http.h"
+#include "cst_util.h"
+#include "os_compat.h"
+
+#include <errno.h>
+#include <pthread.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#define HTTP_HDR_MAX 32768  /* one header block */
+#define HTTP_LINE_MAX 8192  /* one header line */
+#define HTTP_DEFAULT_BODY (1024 * 1024)
+#define HTTP_DEFAULT_CONN 32
+#define HTTP_IDLE_TIMEOUT 60000
+#define HTTP_READ_TIMEOUT 15000
+
+struct cst_http_server {
+  os_socket_t listener;
+  int port;
+  pthread_t accept_th;
+  int accept_started;
+  pthread_mutex_t mu;
+  pthread_cond_t cv;
+  int stopping;
+  int nconn;
+  cst_http_conn_t *conns_first;
+  cst_http_opts_t o;
+  cst_http_route_t *routes;
+  int nroutes;
+};
+
+struct cst_http_conn {
+  cst_http_server_t *srv;
+  os_socket_t sock;
+  cst_http_req_t req;
+  char rbuf[8192];
+  size_t rlen, rpos;
+  char *body;             /* owned while the request is served */
+  char hdrs[HTTP_HDR_MAX]; /* header values are copied here */
+  size_t hdrs_used;
+  int sent;
+  int streaming;
+  int failed;
+  int nreq;            /* requests served on this connection */
+  int expect_continue; /* the client waits for "100 Continue" */
+  int keep_alive_req;  /* what the client asked for */
+  cst_http_conn_t *prev, *next;
+};
+
+static const char *status_text(int code) {
+  switch (code) {
+  case 200: return "OK";
+  case 201: return "Created";
+  case 202: return "Accepted";
+  case 204: return "No Content";
+  case 302: return "Found";
+  case 400: return "Bad Request";
+  case 401: return "Unauthorized";
+  case 403: return "Forbidden";
+  case 404: return "Not Found";
+  case 405: return "Method Not Allowed";
+  case 409: return "Conflict";
+  case 411: return "Length Required";
+  case 413: return "Payload Too Large";
+  case 415: return "Unsupported Media Type";
+  case 429: return "Too Many Requests";
+  case 500: return "Internal Server Error";
+  case 503: return "Service Unavailable";
+  default: return "Error";
+  }
+}
+
+/* --- reading -------------------------------------------------------------- */
+
+/* deadline: os_now_ms() value; the whole read must be done by then, so a
+ * client trickling one byte at a time cannot hold the thread forever. */
+static int fill(cst_http_conn_t *c, double deadline) {
+  if (c->rpos < c->rlen)
+    return 1;
+  double left = deadline - os_now_ms();
+  if (left <= 0)
+    return -2;
+  long r = os_net_recv(c->sock, c->rbuf, sizeof(c->rbuf), (int)left + 1);
+  if (r <= 0)
+    return (int)r; /* 0 eof, -1 error, -2 timeout */
+  c->rpos = 0;
+  c->rlen = (size_t)r;
+  return 1;
+}
+
+#define RD_TOO_LONG (-3)
+
+static int rd_line(cst_http_conn_t *c, char *out, size_t cap, double deadline) {
+  size_t n = 0;
+  for (;;) {
+    int rc = fill(c, deadline);
+    if (rc <= 0)
+      return rc;
+    while (c->rpos < c->rlen) {
+      char ch = c->rbuf[c->rpos++];
+      if (ch == '\n') {
+        if (n && out[n - 1] == '\r')
+          n--;
+        out[n] = 0;
+        return 1;
+      }
+      if (n + 2 >= cap)
+        return RD_TOO_LONG;
+      out[n++] = ch;
+    }
+  }
+}
+
+/* Exactly n bytes, using what the read buffer already holds. malloc'd. */
+static char *rd_body(cst_http_conn_t *c, size_t n, int timeout_ms) {
+  char *buf = malloc(n + 1);
+  if (!buf)
+    return NULL;
+  size_t got = 0;
+  while (got < n) {
+    if (c->rpos < c->rlen) {
+      size_t take = c->rlen - c->rpos;
+      if (take > n - got)
+        take = n - got;
+      memcpy(buf + got, c->rbuf + c->rpos, take);
+      c->rpos += take;
+      got += take;
+      continue;
+    }
+    long r = os_net_recv(c->sock, c->rbuf, sizeof(c->rbuf), timeout_ms);
+    if (r <= 0) {
+      free(buf);
+      return NULL;
+    }
+    c->rpos = 0;
+    c->rlen = (size_t)r;
+  }
+  buf[n] = 0;
+  return buf;
+}
+
+/* -1 when the input encodes a NUL (out then holds what came before it). */
+static int url_decode(const char *in, char *out, size_t cap, int plus_space) {
+  size_t o = 0;
+  for (const char *p = in; *p && o + 1 < cap; p++) {
+    if (*p == '%' && p[1] && p[2]) {
+      int hi = p[1] >= '0' && p[1] <= '9'   ? p[1] - '0'
+               : p[1] >= 'a' && p[1] <= 'f' ? p[1] - 'a' + 10
+               : p[1] >= 'A' && p[1] <= 'F' ? p[1] - 'A' + 10
+                                            : -1;
+      int lo = p[2] >= '0' && p[2] <= '9'   ? p[2] - '0'
+               : p[2] >= 'a' && p[2] <= 'f' ? p[2] - 'a' + 10
+               : p[2] >= 'A' && p[2] <= 'F' ? p[2] - 'A' + 10
+                                            : -1;
+      if (hi >= 0 && lo >= 0) {
+        char ch = (char)((hi << 4) | lo);
+        if (ch == 0) {
+          out[o] = 0;
+          return -1;
+        }
+        out[o++] = ch;
+        p += 2;
+        continue;
+      }
+    }
+    out[o++] = (*p == '+' && plus_space) ? ' ' : *p;
+  }
+  out[o] = 0;
+  return 0;
+}
+
+/* Comma-separated header tokens, compared without case ("Close"). */
+static int has_token(const char *val, const char *tok) {
+  size_t n = strlen(tok);
+  for (const char *p = val; p && *p;) {
+    while (*p == ' ' || *p == '\t' || *p == ',')
+      p++;
+    size_t i = 0;
+    while (i < n && p[i] && (p[i] | 0x20) == (tok[i] | 0x20))
+      i++;
+    if (i == n && (p[i] == 0 || p[i] == ',' || p[i] == ' ' || p[i] == '\t'))
+      return 1;
+    p = strchr(p, ',');
+  }
+  return 0;
+}
+
+static int key_is(const char *line, const char *key) {
+  size_t n = strlen(key);
+  for (size_t i = 0; i < n; i++) {
+    char a = line[i], b = key[i];
+    if (a >= 'A' && a <= 'Z')
+      a = (char)(a - 'A' + 'a');
+    if (b >= 'A' && b <= 'Z')
+      b = (char)(b - 'A' + 'a');
+    if (a != b || !a)
+      return 0;
+  }
+  return line[n] == ':';
+}
+
+/* Copy a header value into the connection (they must not point into the
+ * line buffer, which is reused for the next header). */
+static const char *store_str(cst_http_conn_t *c, const char *val) {
+  size_t n = strlen(val);
+  if (c->hdrs_used + n + 1 > sizeof(c->hdrs))
+    return NULL;
+  char *dst = c->hdrs + c->hdrs_used;
+  memcpy(dst, val, n + 1);
+  c->hdrs_used += n + 1;
+  return dst;
+}
+
+/* 1 = parsed, 0 = the client went away or waited too long, -1 = malformed. */
+static int read_request(cst_http_conn_t *c, size_t *want_body) {
+  cst_http_server_t *s = c->srv;
+  char line[HTTP_LINE_MAX];
+  cst_http_req_t *r = &c->req;
+  int first = c->nreq == 0; /* a keep-alive pause gets the idle timeout */
+  memset(r, 0, sizeof(*r));
+  c->hdrs_used = 0;
+  c->expect_continue = 0;
+  *want_body = 0;
+  int rc = rd_line(c, line, sizeof(line),
+                   os_now_ms() + (first ? s->o.read_timeout_ms
+                                        : s->o.idle_timeout_ms));
+  if (rc == RD_TOO_LONG)
+    return -1;
+  if (rc <= 0)
+    return 0;
+  char *sp1 = strchr(line, ' ');
+  if (!sp1)
+    return -1;
+  *sp1 = 0;
+  char *target = sp1 + 1;
+  char *version = strchr(target, ' ');
+  if (version) {
+    *version++ = 0;
+  } else {
+    version = (char *)"HTTP/1.0";
+  }
+  if (!line[0] || strlen(line) >= sizeof(r->method))
+    return -1;
+  snprintf(r->method, sizeof(r->method), "%s", line);
+  r->keep_alive = strncmp(version, "HTTP/1.", 7) == 0 &&
+                  version[7] >= '1' && version[7] <= '9';
+  /* absolute-form ("http://host/path") is legal: keep the path */
+  if (target[0] != '/') {
+    char *scheme = strstr(target, "://");
+    target = scheme ? strchr(scheme + 3, '/') : NULL;
+  }
+  if (!target || target[0] != '/')
+    return -1;
+  {
+    char raw[sizeof(r->path)];
+    snprintf(raw, sizeof(raw), "%s", target);
+    char *q = strchr(raw, '?');
+    if (q) {
+      *q = 0;
+      snprintf(r->query, sizeof(r->query), "%s", q + 1);
+    }
+    if (url_decode(raw, r->path, sizeof(r->path), 0) != 0)
+      return -1;
+    size_t plen = strlen(r->path);
+    if (plen == 0 || strstr(r->path, ".."))
+      return -1;
+  }
+  size_t hdr_bytes = 0;
+  size_t content_length = 0;
+  int have_length = 0;
+  double deadline = os_now_ms() + s->o.read_timeout_ms;
+  for (;;) {
+    rc = rd_line(c, line, sizeof(line), deadline);
+    if (rc <= 0)
+      return -1;
+    if (!line[0])
+      break;
+    hdr_bytes += strlen(line) + 2;
+    if (hdr_bytes > HTTP_HDR_MAX)
+      return -1;
+    const char *colon = strchr(line, ':');
+    if (!colon)
+      return -1;
+    const char *val = colon + 1;
+    while (*val == ' ' || *val == '\t')
+      val++;
+    if (key_is(line, "content-length")) {
+      /* digits only, and one value: "5x" or two lengths would let the
+       * rest of the body run as a second request behind a proxy */
+      char *end = NULL;
+      errno = 0;
+      unsigned long long v = strtoull(val, &end, 10);
+      while (end && (*end == ' ' || *end == '\t'))
+        end++;
+      if (*val < '0' || *val > '9' || !end || *end || errno == ERANGE ||
+          v > (unsigned long long)SIZE_MAX ||
+          (have_length && content_length != (size_t)v))
+        return -1;
+      content_length = (size_t)v;
+      have_length = 1;
+    } else if (key_is(line, "transfer-encoding")) {
+      return -1; /* chunked request bodies are not supported */
+    } else if (key_is(line, "connection")) {
+      if (has_token(val, "close"))
+        r->keep_alive = 0;
+      else if (has_token(val, "keep-alive"))
+        r->keep_alive = 1;
+    } else if (key_is(line, "expect")) {
+      /* answered once auth and the size cap have passed */
+      c->expect_continue = has_token(val, "100-continue");
+    } else if (key_is(line, "authorization")) {
+      r->authorization = store_str(c, val);
+    } else if (key_is(line, "cookie")) {
+      r->cookie = store_str(c, val);
+    } else if (key_is(line, "origin")) {
+      r->origin = store_str(c, val);
+    } else if (key_is(line, "host")) {
+      r->host = store_str(c, val);
+    } else if (key_is(line, "content-type")) {
+      r->content_type = store_str(c, val);
+    } else if (key_is(line, "user-agent")) {
+      r->user_agent = store_str(c, val);
+    } else if (key_is(line, "last-event-id")) {
+      r->last_event_id = store_str(c, val);
+    }
+  }
+  if (have_length)
+    *want_body = content_length;
+  else if (strcmp(r->method, "POST") == 0)
+    /* No Content-Length means no body (RFC 9112 6.3): curl -X POST sends
+     * exactly that, and the zero-body endpoints (cancel, undo, quit) would
+     * otherwise be unreachable from a hand-written client. Bytes that
+     * follow are not ours to guess at, so the connection ends here. */
+    r->keep_alive = 0;
+  return 1;
+}
+
+/* --- writing -------------------------------------------------------------- */
+
+static int send_head(cst_http_conn_t *c, int status, const char *ctype,
+                     size_t len, int chunked) {
+  cst_buf_t out = {0};
+  cst_buf_printf(&out, "HTTP/1.1 %d %s\r\nContent-Type: %s\r\n",
+                 status, status_text(status), ctype ? ctype : "text/plain");
+  cst_buf_puts(&out, "Cache-Control: no-store\r\n");
+  cst_buf_puts(&out, c->req.keep_alive ? "Connection: keep-alive\r\n"
+                                       : "Connection: close\r\n");
+  if (chunked) {
+    cst_buf_puts(&out, "Transfer-Encoding: chunked\r\n");
+  } else {
+    cst_buf_printf(&out, "Content-Length: %zu\r\n", len);
+  }
+  cst_buf_puts(&out, "\r\n");
+  int rc = out.buf ? os_net_send_all(c->sock, out.buf, out.len, 0) : -1;
+  cst_buf_free(&out);
+  return rc;
+}
+
+int cst_http_send(cst_http_conn_t *c, int status, const char *ctype,
+                  const void *body, size_t n) {
+  if (!c || c->sent)
+    return -1;
+  c->sent = 1;
+  if (send_head(c, status, ctype, n, 0) != 0) {
+    c->failed = 1;
+    return -1;
+  }
+  if (n && os_net_send_all(c->sock, body, n, 0) != 0) {
+    c->failed = 1;
+    return -1;
+  }
+  return 0;
+}
+
+int cst_http_send_str(cst_http_conn_t *c, int status, const char *ctype,
+                      const char *s) {
+  return cst_http_send(c, status, ctype, s ? s : "", s ? strlen(s) : 0);
+}
+
+int cst_http_send_json(cst_http_conn_t *c, int status, const char *json) {
+  return cst_http_send_str(c, status, "application/json; charset=utf-8",
+                           json ? json : "null");
+}
+
+int cst_http_send_err(cst_http_conn_t *c, int status, const char *msg) {
+  cst_buf_t b = {0};
+  cst_buf_puts(&b, "{\"error\":\"");
+  for (const char *p = msg ? msg : "error"; *p; p++) {
+    if (*p == '"' || *p == '\\')
+      cst_buf_printf(&b, "\\%c", *p);
+    else if ((unsigned char)*p < 0x20)
+      cst_buf_printf(&b, "\\u%04x", (unsigned char)*p);
+    else
+      cst_buf_append(&b, p, 1);
+  }
+  cst_buf_puts(&b, "\"}");
+  int rc = cst_http_send_json(c, status, b.buf);
+  cst_buf_free(&b);
+  return rc;
+}
+
+int cst_http_sent(const cst_http_conn_t *c) { return c ? c->sent : 0; }
+
+int cst_http_stream_begin(cst_http_conn_t *c, const char *ctype) {
+  if (!c || c->sent)
+    return -1;
+  c->sent = 1;
+  c->streaming = 1;
+  if (send_head(c, 200, ctype, 0, 1) != 0) {
+    c->failed = 1;
+    return -1;
+  }
+  return 0;
+}
+
+int cst_http_stream_write(cst_http_conn_t *c, const void *data, size_t n) {
+  if (!c || !c->streaming || c->failed)
+    return -1;
+  if (n == 0)
+    return 0;
+  cst_buf_t b = {0};
+  cst_buf_printf(&b, "%zx\r\n", n);
+  cst_buf_append(&b, data, n);
+  cst_buf_puts(&b, "\r\n");
+  int rc = b.buf ? os_net_send_all(c->sock, b.buf, b.len, 0) : -1;
+  cst_buf_free(&b);
+  if (rc != 0)
+    c->failed = 1;
+  return rc;
+}
+
+int cst_http_stream_end(cst_http_conn_t *c) {
+  if (!c || !c->streaming)
+    return -1;
+  c->streaming = 0;
+  if (c->failed)
+    return -1;
+  const char *end = "0\r\n\r\n";
+  if (os_net_send_all(c->sock, end, strlen(end), 0) != 0) {
+    c->failed = 1;
+    return -1;
+  }
+  return 0;
+}
+
+const cst_http_req_t *cst_http_request(cst_http_conn_t *c) {
+  return c ? &c->req : NULL;
+}
+
+int cst_http_query(const cst_http_req_t *req, const char *key, char *out,
+                   size_t out_sz) {
+  if (!req || !key || !out || out_sz == 0)
+    return -1;
+  size_t klen = strlen(key);
+  const char *p = req->query;
+  while (p && *p) {
+    const char *amp = strchr(p, '&');
+    size_t seg = amp ? (size_t)(amp - p) : strlen(p);
+    const char *eq = memchr(p, '=', seg);
+    size_t name_len = eq ? (size_t)(eq - p) : seg;
+    if (name_len == klen && strncmp(p, key, klen) == 0) {
+      char raw[1024];
+      size_t vlen = eq ? seg - name_len - 1 : 0;
+      if (vlen >= sizeof(raw))
+        vlen = sizeof(raw) - 1;
+      if (eq)
+        memcpy(raw, eq + 1, vlen);
+      raw[vlen] = 0;
+      url_decode(raw, out, out_sz, 1);
+      return 0;
+    }
+    p = amp ? amp + 1 : NULL;
+  }
+  return -1;
+}
+
+/* --- connections ---------------------------------------------------------- */
+
+static const cst_http_route_t *find_route(const cst_http_server_t *s,
+                                          const cst_http_req_t *req) {
+  const cst_http_route_t *fallback = NULL;
+  for (int i = 0; i < s->nroutes; i++) {
+    const cst_http_route_t *r = &s->routes[i];
+    if (strcmp(r->method, "*") != 0 && strcmp(r->method, req->method) != 0)
+      continue;
+    if (strcmp(r->path, "*") == 0) {
+      fallback = r;
+      continue;
+    }
+    if (strcmp(r->path, req->path) == 0)
+      return r;
+  }
+  return fallback;
+}
+
+/* Route, auth and the size cap are settled before the body is read: an
+ * unauthenticated client must not make us buffer 32 MiB. */
+static void serve(cst_http_server_t *s, cst_http_conn_t *c, size_t want) {
+  const cst_http_route_t *route = find_route(s, &c->req);
+  size_t cap = route && route->max_body ? route->max_body : s->o.max_body;
+  if (want > 0)
+    c->req.keep_alive = 0; /* until the body is read, the stream is ours */
+  if (!route) {
+    cst_http_send_err(c, 404, "not found");
+    return;
+  }
+  if (route->auth && s->o.auth && s->o.auth(&c->req, s->o.auth_ud) != 0) {
+    cst_http_send_err(c, 401, "unauthorized");
+    return;
+  }
+  if (want > cap) {
+    cst_http_send_err(c, 413, "request body too large");
+    return;
+  }
+  if (want > 0) {
+    if (c->expect_continue) {
+      const char *cont = "HTTP/1.1 100 Continue\r\n\r\n";
+      os_net_send_all(c->sock, cont, strlen(cont), 5000);
+    }
+    char *body = rd_body(c, want, s->o.read_timeout_ms);
+    if (!body) {
+      c->failed = 1;
+      return;
+    }
+    c->body = body;
+    c->req.body = body;
+    c->req.body_len = want;
+    c->req.keep_alive = c->keep_alive_req;
+  }
+  int rc = route->fn(c, route->ud);
+  if (!c->sent)
+    cst_http_send_err(c, rc == 0 ? 500 : 404,
+                      rc == 0 ? "handler sent no response" : "not found");
+}
+
+static void *conn_main(void *arg) {
+  cst_http_conn_t *c = arg;
+  cst_http_server_t *s = c->srv;
+  for (;;) {
+    size_t want = 0;
+    int rc = read_request(c, &want);
+    if (rc < 0) {
+      /* malformed (bad request line, traversal, unsupported transfer
+       * encoding): say so instead of closing silently */
+      c->sent = 0;
+      c->req.keep_alive = 0;
+      cst_http_send_err(c, 400, "malformed request");
+      break;
+    }
+    if (rc == 0)
+      break;
+    c->nreq++;
+    c->sent = 0;
+    c->streaming = 0;
+    c->keep_alive_req = c->req.keep_alive;
+    serve(s, c, want);
+    if (s->o.on_log) {
+      char line[512];
+      snprintf(line, sizeof(line), "%s %.480s -> %d", c->req.method, c->req.path,
+               c->failed ? 499 : (c->sent ? 200 : 500));
+      s->o.on_log(line, s->o.log_ud);
+    }
+    free(c->body);
+    c->body = NULL;
+    c->req.body = NULL;
+    c->req.body_len = 0;
+    c->req.authorization = c->req.cookie = c->req.origin = NULL;
+    c->req.host = c->req.content_type = c->req.user_agent = NULL;
+    c->req.last_event_id = NULL;
+    if (!c->req.keep_alive || s->stopping || c->failed)
+      break;
+  }
+  /* unlink first: stop() shuts down every listed socket, and a closed fd
+   * number may already belong to someone else */
+  pthread_mutex_lock(&s->mu);
+  if (c->prev)
+    c->prev->next = c->next;
+  else
+    s->conns_first = c->next;
+  if (c->next)
+    c->next->prev = c->prev;
+  pthread_mutex_unlock(&s->mu);
+  os_net_shutdown(c->sock);
+  os_net_close(c->sock);
+  free(c);
+  pthread_mutex_lock(&s->mu);
+  s->nconn--;
+  pthread_cond_broadcast(&s->cv);
+  pthread_mutex_unlock(&s->mu);
+  return NULL;
+}
+
+static void *accept_main(void *arg) {
+  cst_http_server_t *s = arg;
+  while (!s->stopping) {
+    int timed_out = 0;
+    os_socket_t sock = os_net_accept(s->listener, 500, &timed_out);
+    if (sock == OS_SOCKET_BAD) {
+      if (!timed_out) { /* EMFILE and friends: the listener stays readable */
+        struct timespec ts;
+        clock_gettime(CLOCK_REALTIME, &ts);
+        ts.tv_nsec += 100000000;
+        if (ts.tv_nsec >= 1000000000) {
+          ts.tv_sec++;
+          ts.tv_nsec -= 1000000000;
+        }
+        pthread_mutex_lock(&s->mu);
+        if (!s->stopping)
+          pthread_cond_timedwait(&s->cv, &s->mu, &ts);
+        pthread_mutex_unlock(&s->mu);
+      }
+      continue;
+    }
+    if (s->stopping) {
+      os_net_close(sock);
+      break;
+    }
+    pthread_mutex_lock(&s->mu);
+    int over = s->nconn >= s->o.max_conn;
+    if (!over)
+      s->nconn++;
+    pthread_mutex_unlock(&s->mu);
+    if (over) {
+      const char *busy = "HTTP/1.1 503 Service Unavailable\r\n"
+                         "Content-Length: 0\r\nConnection: close\r\n\r\n";
+      os_net_send_all(sock, busy, strlen(busy), 2000);
+      os_net_close(sock);
+      continue;
+    }
+    cst_http_conn_t *c = calloc(1, sizeof(*c));
+    if (!c) {
+      pthread_mutex_lock(&s->mu);
+      s->nconn--;
+      pthread_cond_broadcast(&s->cv);
+      pthread_mutex_unlock(&s->mu);
+      os_net_close(sock);
+      continue;
+    }
+    c->srv = s;
+    c->sock = sock;
+    pthread_mutex_lock(&s->mu);
+    c->next = s->conns_first;
+    if (c->next)
+      c->next->prev = c;
+    s->conns_first = c;
+    pthread_mutex_unlock(&s->mu);
+    pthread_t th;
+    if (pthread_create(&th, NULL, conn_main, c) != 0) {
+      pthread_mutex_lock(&s->mu);
+      s->conns_first = c->next;
+      if (c->next)
+        c->next->prev = NULL;
+      s->nconn--;
+      pthread_cond_broadcast(&s->cv);
+      pthread_mutex_unlock(&s->mu);
+      os_net_close(sock);
+      free(c);
+      continue;
+    }
+    pthread_detach(th);
+  }
+  return NULL;
+}
+
+cst_http_server_t *cst_http_start(const cst_http_opts_t *o, char *err,
+                                  size_t err_sz) {
+  if (!o)
+    return NULL;
+  if (os_net_init() != 0) {
+    if (err)
+      snprintf(err, err_sz, "network init failed");
+    return NULL;
+  }
+  cst_http_server_t *s = calloc(1, sizeof(*s));
+  if (!s)
+    return NULL;
+  s->o = *o;
+  s->o.max_body = o->max_body ? o->max_body : HTTP_DEFAULT_BODY;
+  s->o.max_conn = o->max_conn ? o->max_conn : HTTP_DEFAULT_CONN;
+  if (!s->o.read_timeout_ms)
+    s->o.read_timeout_ms = HTTP_READ_TIMEOUT;
+  if (!s->o.idle_timeout_ms)
+    s->o.idle_timeout_ms = HTTP_IDLE_TIMEOUT;
+  if (o->nroutes > 0) {
+    s->routes = calloc((size_t)o->nroutes, sizeof(*s->routes));
+    if (!s->routes) {
+      free(s);
+      return NULL;
+    }
+    memcpy(s->routes, o->routes, (size_t)o->nroutes * sizeof(*s->routes));
+    s->nroutes = o->nroutes;
+  }
+  pthread_mutex_init(&s->mu, NULL);
+  pthread_cond_init(&s->cv, NULL);
+  s->listener = os_net_listen(o->host, o->port, err, err_sz);
+  if (s->listener == OS_SOCKET_BAD) {
+    free(s->routes);
+    free(s);
+    return NULL;
+  }
+  s->port = os_net_port(s->listener);
+  if (pthread_create(&s->accept_th, NULL, accept_main, s) != 0) {
+    os_net_close(s->listener);
+    free(s->routes);
+    free(s);
+    if (err)
+      snprintf(err, err_sz, "cannot start the accept thread");
+    return NULL;
+  }
+  s->accept_started = 1;
+  return s;
+}
+
+int cst_http_port(const cst_http_server_t *s) { return s ? s->port : 0; }
+
+int cst_http_stopping(const cst_http_server_t *s) {
+  return s ? s->stopping : 1;
+}
+
+int cst_http_stop(cst_http_server_t *s) {
+  if (!s)
+    return 0;
+  pthread_mutex_lock(&s->mu);
+  s->stopping = 1;
+  for (cst_http_conn_t *c = s->conns_first; c; c = c->next)
+    os_net_shutdown(c->sock);
+  pthread_mutex_unlock(&s->mu);
+  os_net_shutdown(s->listener);
+  if (s->accept_started) {
+    pthread_join(s->accept_th, NULL);
+    s->accept_started = 0;
+  }
+  /* Handler threads own their connection until they return; the shutdown
+   * above is what wakes them. Bounded wait so free() stays safe. */
+  pthread_mutex_lock(&s->mu);
+  for (int i = 0; i < 300 && s->nconn > 0; i++) {
+    struct timespec ts;
+    clock_gettime(CLOCK_REALTIME, &ts);
+    ts.tv_nsec += 100000000; /* 100 ms */
+    if (ts.tv_nsec >= 1000000000) {
+      ts.tv_sec++;
+      ts.tv_nsec -= 1000000000;
+    }
+    pthread_cond_timedwait(&s->cv, &s->mu, &ts);
+  }
+  int left = s->nconn;
+  pthread_mutex_unlock(&s->mu);
+  os_net_close(s->listener);
+  return left;
+}
+
+void cst_http_free(cst_http_server_t *s) {
+  if (!s)
+    return;
+  pthread_mutex_lock(&s->mu);
+  int left = s->nconn;
+  pthread_mutex_unlock(&s->mu);
+  if (left > 0)
+    return; /* a handler still runs on it (see stop()): leak, not crash */
+  pthread_mutex_destroy(&s->mu);
+  pthread_cond_destroy(&s->cv);
+  free(s->routes);
+  free(s);
+}

src/keymap.c

@@ -48,6 +48,8 @@ static const cst_key_action_info_t INFO[CST_KA_COUNT] = {
     [CST_KA_COPY] = {"copy", "Session", "copy the last reply", "/copy"},
     [CST_KA_EXPORT] = {"export", "Session", "export the transcript",
                        "/export"},
+    [CST_KA_PASTE_IMAGE] = {"paste_image", "Session",
+                            "attach the clipboard image", "/attach paste"},
     [CST_KA_MODEL] = {"model", "Model", "pick the model", "/model"},
     [CST_KA_PROVIDER] = {"provider", "Model", "switch provider", "/provider"},
     [CST_KA_EFFORT] = {"effort", "Model", "reasoning effort", "/effort"},
@@ -89,6 +91,7 @@ static const struct {
     {CST_KA_COMPACT, "<leader> c"},
     {CST_KA_COPY, "<leader> y"},
     {CST_KA_EXPORT, "<leader> x"},
+    {CST_KA_PASTE_IMAGE, "ctrl+v"},
     {CST_KA_MODEL, "<leader> m"},
     {CST_KA_PROVIDER, "<leader> p"},
     {CST_KA_EFFORT, "<leader> e"},

src/llm_openai.c

@@ -61,6 +61,9 @@ static void llm_apply_ca_bundle(CURL *curl) {
 #endif
 }
 
+#include "cst_attach.h"
+#include "cst_models.h"
+
 /* --- wire body ----------------------------------------------------------- */
 
 static size_t wire_tool_cap(const cst_llm_request_t *req) {
@@ -116,6 +119,217 @@ static cJSON *clean_string(const char *s, size_t cap) {
   return j;
 }
 
+/* --- multimodal content --------------------------------------------------
+ * OpenAI-compatible servers take a parts array where a plain string is also
+ * accepted, so text-only messages keep the string form and only those with
+ * images switch to parts. Images live in the session store and are read (and
+ * base64'd) here, once per request. */
+
+/* The message's "content" as a parts array, converting a string in place. */
+static cJSON *content_parts(cJSON *msg) {
+  cJSON *c = cJSON_GetObjectItemCaseSensitive(msg, "content");
+  if (cJSON_IsArray(c))
+    return c;
+  cJSON *arr = cJSON_CreateArray();
+  if (cJSON_IsString(c)) {
+    cJSON *t = cJSON_CreateObject();
+    cJSON_AddStringToObject(t, "type", "text");
+    cJSON_AddStringToObject(t, "text", c->valuestring);
+    cJSON_AddItemToArray(arr, t);
+  }
+  cJSON_ReplaceItemInObjectCaseSensitive(msg, "content", arr);
+  return arr;
+}
+
+/* Append text, joining it onto a trailing text part when there is one.
+ * Takes ownership of txt. */
+static void parts_add_text(cJSON *parts, cJSON *txt) {
+  if (!txt)
+    txt = cJSON_CreateString("");
+  cJSON *last = cJSON_GetArrayItem(parts, cJSON_GetArraySize(parts) - 1);
+  const cJSON *lt = last ? cJSON_GetObjectItemCaseSensitive(last, "type") : NULL;
+  if (cJSON_IsString(lt) && strcmp(lt->valuestring, "text") == 0) {
+    const cJSON *old = cJSON_GetObjectItemCaseSensitive(last, "text");
+    cst_buf_t b = {0};
+    if (cJSON_IsString(old))
+      cst_buf_puts(&b, old->valuestring);
+    if (b.len)
+      cst_buf_puts(&b, "\n\n");
+    cst_buf_puts(&b, txt->valuestring ? txt->valuestring : "");
+    cJSON_ReplaceItemInObjectCaseSensitive(
+        last, "text", cJSON_CreateString(b.buf ? b.buf : ""));
+    cst_buf_free(&b);
+    cJSON_Delete(txt);
+    return;
+  }
+  if (!txt->valuestring || !txt->valuestring[0]) {
+    cJSON_Delete(txt);
+    return;
+  }
+  cJSON *t = cJSON_CreateObject();
+  cJSON_AddStringToObject(t, "type", "text");
+  cJSON_AddItemToObject(t, "text", txt);
+  cJSON_AddItemToArray(parts, t);
+}
+
+/* One stored image as an image_url part, or NULL with why filled in. */
+static cJSON *image_part(const cst_llm_request_t *req,
+                         const cst_attachment_t *a, size_t *budget, char *why,
+                         size_t why_sz) {
+  why[0] = 0;
+  if (!req->session_path || !req->session_path[0]) {
+    snprintf(why, why_sz, "there is no session store to read it from");
+    return NULL;
+  }
+  char err[256];
+  size_t n = 0;
+  char *data = cst_attach_read(req->session_path, a, &n, err, sizeof(err));
+  if (!data) {
+    snprintf(why, why_sz, "%s", err);
+    return NULL;
+  }
+  if (n > *budget) {
+    snprintf(why, why_sz, "%d KB left in the %d MB image budget",
+             (int)(*budget / 1024), (int)(CST_ATTACH_MAX_TOTAL >> 20));
+    free(data);
+    return NULL;
+  }
+  *budget -= n;
+  char mime[32];
+  cst_attach_sniff(data, n, mime, sizeof(mime)); /* read verified it */
+  char *b64 = cst_base64_encode(data, n);
+  free(data);
+  if (!b64) {
+    snprintf(why, why_sz, "out of memory");
+    return NULL;
+  }
+  cst_buf_t b = {0};
+  cst_buf_puts(&b, "data:");
+  cst_buf_puts(&b, mime);
+  cst_buf_puts(&b, ";base64,");
+  cst_buf_puts(&b, b64);
+  free(b64);
+  if (!b.buf) {
+    snprintf(why, why_sz, "out of memory");
+    return NULL;
+  }
+  cJSON *p = cJSON_CreateObject();
+  cJSON_AddStringToObject(p, "type", "image_url");
+  cJSON *iu = cJSON_AddObjectToObject(p, "image_url");
+  cJSON_AddStringToObject(iu, "url", b.buf);
+  if (a->detail[0] && strcmp(a->detail, "auto") != 0)
+    cJSON_AddStringToObject(iu, "detail", a->detail);
+  cst_buf_free(&b);
+  return p;
+}
+
+/* Append every attachment of m as image parts (or a note saying why not). */
+static void parts_add_images(const cst_llm_request_t *req, cJSON *parts,
+                             const cst_message_t *m, size_t *budget) {
+  int n = m->nattach;
+  if (n > CST_ATTACH_MAX_COUNT) {
+    char note[160];
+    snprintf(note, sizeof(note), "[%d of %d images sent]", CST_ATTACH_MAX_COUNT,
+             n);
+    parts_add_text(parts, cJSON_CreateString(note));
+    n = CST_ATTACH_MAX_COUNT;
+  }
+  for (int i = 0; i < n; i++) {
+    const cst_attachment_t *a = &m->attach[i];
+    char why[256];
+    cJSON *p = image_part(req, a, budget, why, sizeof(why));
+    if (p) {
+      cJSON_AddItemToArray(parts, p);
+      continue;
+    }
+    char note[512];
+    snprintf(note, sizeof(note), "[image \"%.120s\" not sent: %.200s]",
+             a->name, why);
+    parts_add_text(parts, cJSON_CreateString(note));
+  }
+}
+
+/* Images a tool result produced are deferred: an assistant tool_call must be
+ * answered by tool messages only, so they ride in one extra user message
+ * after the run of tool messages ends. *pending collects it. */
+static void defer_images(const cst_llm_request_t *req, const cst_message_t *m,
+                         cJSON **pending, size_t *budget) {
+  cJSON *p = *pending;
+  if (!p) {
+    p = cJSON_CreateObject();
+    cJSON_AddStringToObject(p, "role", "user");
+    cJSON_AddArrayToObject(p, "content");
+    *pending = p;
+  }
+  parts_add_images(req, cJSON_GetObjectItemCaseSensitive(p, "content"), m,
+                   budget);
+}
+
+/* m's text plus one line per image it would have carried (malloc'd). */
+static char *image_notes(const cst_message_t *m, const char *why) {
+  cst_buf_t b = {0};
+  cst_buf_puts(&b, m->content ? m->content : "");
+  for (int i = 0; i < m->nattach; i++) {
+    char d[128];
+    cst_attach_describe(&m->attach[i], d, sizeof(d));
+    cst_buf_printf(&b, "%s[image \"%.120s\" (%s) not sent: %s]",
+                   b.len ? "\n" : "", m->attach[i].name, d, why);
+  }
+  return cst_buf_steal(&b);
+}
+
+/* --- cache breakpoints (Anthropic-style) ----------------------------------
+ * At most 4 per request. The system prompt one also covers tools[]; the
+ * newest message one moves forward every step; the newest real user message
+ * keeps a hit when a long tool run pushes the previous one out of the
+ * provider's lookback. */
+
+static void mark_message(cJSON *msg, const char *ttl) {
+  const cJSON *c = cJSON_GetObjectItemCaseSensitive(msg, "content");
+  if (cJSON_IsString(c) ? !c->valuestring[0] : !cJSON_IsArray(c))
+    return;
+  cJSON *parts = content_parts(msg);
+  cJSON *last = cJSON_GetArrayItem(parts, cJSON_GetArraySize(parts) - 1);
+  if (!cJSON_IsObject(last) ||
+      cJSON_GetObjectItemCaseSensitive(last, "cache_control"))
+    return;
+  cJSON *cc = cJSON_AddObjectToObject(last, "cache_control");
+  cJSON_AddStringToObject(cc, "type", "ephemeral");
+  if (ttl && ttl[0])
+    cJSON_AddStringToObject(cc, "ttl", ttl);
+}
+
+static int msg_role_is(const cJSON *msg, const char *role) {
+  const cJSON *r = cJSON_GetObjectItemCaseSensitive(msg, "role");
+  return cJSON_IsString(r) && strcmp(r->valuestring, role) == 0;
+}
+
+static int msg_has_content(const cJSON *msg) {
+  const cJSON *c = cJSON_GetObjectItemCaseSensitive(msg, "content");
+  return cJSON_IsString(c) ? c->valuestring[0] != 0 : cJSON_IsArray(c);
+}
+
+static void cache_marks(cJSON *msgs, const char *ttl) {
+  int n = cJSON_GetArraySize(msgs);
+  cJSON *first = cJSON_GetArrayItem(msgs, 0);
+  if (first && msg_role_is(first, "system"))
+    mark_message(first, ttl);
+  int last = -1;
+  for (int i = n - 1; i > 0 && last < 0; i--)
+    if (msg_has_content(cJSON_GetArrayItem(msgs, i)))
+      last = i;
+  if (last < 0)
+    return;
+  mark_message(cJSON_GetArrayItem(msgs, last), ttl);
+  for (int i = last - 1; i > 0; i--) {
+    cJSON *m = cJSON_GetArrayItem(msgs, i);
+    if (msg_role_is(m, "user") && msg_has_content(m)) {
+      mark_message(m, ttl);
+      break;
+    }
+  }
+}
+
 static const char *role_api(cst_role_t r) {
   switch (r) {
   case CST_ROLE_SYSTEM:
@@ -146,34 +360,80 @@ char *cst_llm_build_body(const cst_llm_request_t *req) {
   cJSON *msgs = cJSON_AddArrayToObject(root, "messages");
   size_t tcap = wire_tool_cap(req);
   cJSON *prev_user = NULL; /* merge consecutive user messages */
+  cJSON *pending = NULL;   /* images from tool results, waiting for a break */
+  size_t img_budget = CST_ATTACH_MAX_TOTAL;
+  const char *noimg = getenv("CST_NO_IMAGES");
+  const char *img_off =
+      noimg && noimg[0] && noimg[0] != '0'
+          ? "image sending is disabled (CST_NO_IMAGES)"
+      : req->images_off ? "this model does not take images"
+                        : NULL;
 
   for (int i = 0; i < req->nmsgs; i++) {
-    const cst_message_t *m = &req->msgs[i];
+    cst_message_t mm = req->msgs[i];
+    const cst_message_t *m = &mm;
     cst_role_t role = m->role;
     if (role == CST_ROLE_TOOL && !m->tool_call_id[0])
       role = CST_ROLE_USER;
+    int has_img = m->attach && m->nattach > 0;
+    char *noted = NULL;
+    if (has_img && img_off) {
+      /* plain text: text-only APIs may refuse content arrays */
+      noted = image_notes(m, img_off);
+      if (noted)
+        mm.content = noted;
+      has_img = 0;
+    }
+
+    /* Every tool_call must be answered by tool messages, so tool-produced
+     * images only leave the queue when the run of tool results is over. */
+    if (role != CST_ROLE_TOOL && pending) {
+      cJSON_AddItemToArray(msgs, pending);
+      prev_user = pending;
+      pending = NULL;
+    }
 
     if (role == CST_ROLE_USER) {
       /* Text-protocol result frames are capped by the agent before framing
        * (their byte counts must stay exact), so never cap user text here. */
-      cJSON *c = clean_string(m->content, 0);
-      if (prev_user) {
-        cJSON *pc = cJSON_GetObjectItemCaseSensitive(prev_user, "content");
-        cst_buf_t b = {0};
-        cst_buf_puts(&b, pc->valuestring);
-        cst_buf_puts(&b, "\n\n");
-        cst_buf_puts(&b, c->valuestring);
-        cJSON_ReplaceItemInObjectCaseSensitive(prev_user, "content",
-                                               cJSON_CreateString(b.buf));
-        cst_buf_free(&b);
-        cJSON_Delete(c);
+      cJSON *pc = prev_user
+                      ? cJSON_GetObjectItemCaseSensitive(prev_user, "content")
+                      : NULL;
+      if (!has_img && !cJSON_IsArray(pc)) {
+        cJSON *c = clean_string(m->content, 0);
+        if (prev_user) {
+          cst_buf_t b = {0};
+          cst_buf_puts(&b, pc->valuestring);
+          cst_buf_puts(&b, "\n\n");
+          cst_buf_puts(&b, c->valuestring);
+          cJSON_ReplaceItemInObjectCaseSensitive(prev_user, "content",
+                                                 cJSON_CreateString(b.buf));
+          cst_buf_free(&b);
+          cJSON_Delete(c);
+          free(noted);
+          continue;
+        }
+        cJSON *o = cJSON_CreateObject();
+        cJSON_AddStringToObject(o, "role", "user");
+        cJSON_AddItemToObject(o, "content", c);
+        cJSON_AddItemToArray(msgs, o);
+        prev_user = o;
+        free(noted);
         continue;
       }
-      cJSON *o = cJSON_CreateObject();
-      cJSON_AddStringToObject(o, "role", "user");
-      cJSON_AddItemToObject(o, "content", c);
-      cJSON_AddItemToArray(msgs, o);
-      prev_user = o;
+      cJSON *o = prev_user;
+      if (!o) {
+        o = cJSON_CreateObject();
+        cJSON_AddStringToObject(o, "role", "user");
+        cJSON_AddArrayToObject(o, "content");
+        cJSON_AddItemToArray(msgs, o);
+        prev_user = o;
+      }
+      cJSON *parts = content_parts(o);
+      parts_add_text(parts, clean_string(m->content, 0));
+      if (has_img)
+        parts_add_images(req, parts, m, &img_budget);
+      free(noted);
       continue;
     }
     prev_user = NULL;
@@ -198,17 +458,39 @@ char *cst_llm_build_body(const cst_llm_request_t *req) {
     } else {
       cJSON_AddItemToObject(o, "content", clean_string(m->content, 0));
     }
+    if (role == CST_ROLE_ASSISTANT) {
+      if (req->send_reasoning && m->reasoning && m->reasoning[0])
+        cJSON_AddItemToObject(o, "reasoning_content",
+                              clean_string(m->reasoning, 0));
+      if (m->prefix)
+        cJSON_AddTrueToObject(o, "prefix");
+    }
     cJSON_AddItemToArray(msgs, o);
+    if (role == CST_ROLE_TOOL && has_img)
+      defer_images(req, m, &pending, &img_budget);
+    free(noted);
   }
+  if (pending)
+    cJSON_AddItemToArray(msgs, pending);
 
   if (req->enable_tools) {
-    cJSON *tools = cst_tools_schema_cfg(req->tool_cfg);
+    cJSON *tools = req->tools_json ? cJSON_Parse(req->tools_json)
+                                   : cst_tools_schema_cfg(req->tool_cfg);
     if (tools) {
       cJSON_AddItemToObject(root, "tools", tools);
       cJSON_AddStringToObject(root, "tool_choice",
                               req->tool_choice_none ? "none" : "auto");
     }
   }
+  if (req->cache_style == CST_CACHE_OPENAI && req->cache_key &&
+      req->cache_key[0]) {
+    cJSON_AddStringToObject(root, "prompt_cache_key", req->cache_key);
+    const char *ret = getenv("CST_CACHE_RETENTION");
+    if (ret && ret[0])
+      cJSON_AddStringToObject(root, "prompt_cache_retention", ret);
+  } else if (req->cache_style == CST_CACHE_ANTHROPIC) {
+    cache_marks(msgs, req->cache_ttl);
+  }
   char *out = cJSON_PrintUnformatted(root);
   cJSON_Delete(root);
   return out;
@@ -371,11 +653,22 @@ static void handle_payload(sse_t *s, const char *payload) {
     const cJSON *pt = cJSON_GetObjectItemCaseSensitive(usage, "prompt_tokens");
     const cJSON *ct =
         cJSON_GetObjectItemCaseSensitive(usage, "completion_tokens");
+    /* DeepSeek: prompt_cache_hit/miss_tokens. OpenAI and routers:
+     * prompt_tokens_details.cached_tokens (+ cache_write_tokens).
+     * Anthropic fields passed through: cache_read/creation_input_tokens. */
     const cJSON *hit =
         cJSON_GetObjectItemCaseSensitive(usage, "prompt_cache_hit_tokens");
+    const cJSON *miss =
+        cJSON_GetObjectItemCaseSensitive(usage, "prompt_cache_miss_tokens");
     const cJSON *det =
         cJSON_GetObjectItemCaseSensitive(usage, "prompt_tokens_details");
     const cJSON *cached = cJSON_GetObjectItemCaseSensitive(det, "cached_tokens");
+    const cJSON *dwrite =
+        cJSON_GetObjectItemCaseSensitive(det, "cache_write_tokens");
+    const cJSON *aread =
+        cJSON_GetObjectItemCaseSensitive(usage, "cache_read_input_tokens");
+    const cJSON *awrite =
+        cJSON_GetObjectItemCaseSensitive(usage, "cache_creation_input_tokens");
     if (cJSON_IsNumber(pt))
       s->st->prompt_tokens = (long)pt->valuedouble;
     if (cJSON_IsNumber(ct))
@@ -384,6 +677,19 @@ static void handle_payload(sse_t *s, const char *payload) {
       s->st->cached_tokens = (long)hit->valuedouble;
     else if (cJSON_IsNumber(cached))
       s->st->cached_tokens = (long)cached->valuedouble;
+    else if (cJSON_IsNumber(aread))
+      s->st->cached_tokens = (long)aread->valuedouble;
+    if (cJSON_IsNumber(dwrite))
+      s->st->cache_write_tokens = (long)dwrite->valuedouble;
+    else if (cJSON_IsNumber(awrite))
+      s->st->cache_write_tokens = (long)awrite->valuedouble;
+    if (cJSON_IsNumber(miss)) {
+      s->st->cache_miss_tokens = (long)miss->valuedouble;
+    } else {
+      long m = s->st->prompt_tokens - s->st->cached_tokens -
+               s->st->cache_write_tokens;
+      s->st->cache_miss_tokens = m > 0 ? m : 0;
+    }
   }
   const cJSON *choices = cJSON_GetObjectItemCaseSensitive(root, "choices");
   const cJSON *ch = cJSON_IsArray(choices) ? cJSON_GetArrayItem(choices, 0)
@@ -526,15 +832,37 @@ static void trace_path(const char *dir, int seq, const char *ext, char *out,
   snprintf(out, n, "%s/%04d.%s", dir, seq, ext);
 }
 
+static void format_http_error(sse_t *s, long http, char *err, size_t err_sz);
+
+/* NNNN.sse is fed as the stream; with an NNNN.status other than 200 it is
+ * the error body of that HTTP status instead. */
 static int replay_run(sse_t *s, const char *dir, int seq, char *err,
                       size_t err_sz) {
   char path[OS_PATH_MAX];
+  trace_path(dir, seq, "status", path, sizeof(path));
+  FILE *sf = fopen(path, "rb");
+  long status = 200;
+  if (sf) {
+    if (fscanf(sf, "%ld", &status) != 1)
+      status = 200;
+    fclose(sf);
+  }
   trace_path(dir, seq, "sse", path, sizeof(path));
   FILE *fp = fopen(path, "rb");
   if (!fp) {
     snprintf(err, err_sz, "replay: missing %s", path);
     return -1;
   }
+  if (status != 200) {
+    char eb[4096];
+    size_t got = fread(eb, 1, sizeof(eb), fp);
+    fclose(fp);
+    cst_buf_append(&s->errbody, eb, got);
+    if (s->st)
+      s->st->http_status = status;
+    format_http_error(s, status, err, err_sz);
+    return -1;
+  }
   size_t chunk = 16;
   const char *e = getenv("CST_REPLAY_CHUNK");
   if (e && atoi(e) > 0)
@@ -742,7 +1070,7 @@ finish:
 
 /* --- model listing -------------------------------------------------------- */
 
-#define MODELS_BODY_MAX (2 * 1024 * 1024)
+#define MODELS_BODY_MAX (8 * 1024 * 1024)
 
 static size_t models_write_cb(char *ptr, size_t size, size_t nmemb, void *ud) {
   cst_buf_t *b = ud;
@@ -752,18 +1080,97 @@ static size_t models_write_cb(char *ptr, size_t size, size_t nmemb, void *ud) {
   return n;
 }
 
-static int add_model(char out[][128], int n, int max_out, const char *id) {
-  if (!id || !id[0] || n >= max_out || strlen(id) >= 128)
+/* A number, or a numeric string (OpenRouter prices are strings). */
+static int json_num(const cJSON *v, double *out) {
+  if (cJSON_IsNumber(v)) {
+    *out = v->valuedouble;
+    return 0;
+  }
+  if (cJSON_IsString(v) && v->valuestring[0]) {
+    char *end;
+    double d = strtod(v->valuestring, &end);
+    if (end != v->valuestring && !*end) {
+      *out = d;
+      return 0;
+    }
+  }
+  return -1;
+}
+
+static int has_image(const cJSON *arr) {
+  const cJSON *x;
+  cJSON_ArrayForEach(x, arr) {
+    if (cJSON_IsString(x) && strcmp(x->valuestring, "image") == 0)
+      return 1;
+  }
+  return 0;
+}
+
+/* Optional OpenRouter-style metadata: context_length (or context_window /
+ * max_model_len), architecture.input_modalities, modalities, and pricing in
+ * USD per token. */
+static void model_meta(const cJSON *it, cst_model_meta_t *m) {
+  static const char *const ctx_keys[] = {"context_length", "context_window",
+                                         "max_model_len"};
+  for (size_t k = 0; k < sizeof(ctx_keys) / sizeof(ctx_keys[0]); k++) {
+    double d;
+    if (json_num(cJSON_GetObjectItemCaseSensitive(it, ctx_keys[k]), &d) == 0 &&
+        d > 0) {
+      m->context = (long)d;
+      break;
+    }
+  }
+  const cJSON *arch = cJSON_GetObjectItemCaseSensitive(it, "architecture");
+  const cJSON *in = cJSON_GetObjectItemCaseSensitive(arch, "input_modalities");
+  const cJSON *mods = cJSON_GetObjectItemCaseSensitive(it, "modalities");
+  if (cJSON_IsObject(mods))
+    mods = cJSON_GetObjectItemCaseSensitive(mods, "input");
+  const cJSON *modality = cJSON_GetObjectItemCaseSensitive(arch, "modality");
+  if (cJSON_IsArray(in))
+    m->vision = has_image(in);
+  else if (cJSON_IsArray(mods))
+    m->vision = has_image(mods);
+  else if (cJSON_IsString(modality)) {
+    const char *arrow = strstr(modality->valuestring, "->");
+    size_t l = arrow ? (size_t)(arrow - modality->valuestring)
+                     : strlen(modality->valuestring);
+    char left[64];
+    snprintf(left, sizeof(left), "%.*s", (int)l, modality->valuestring);
+    m->vision = strstr(left, "image") != NULL;
+  }
+  const cJSON *pr = cJSON_GetObjectItemCaseSensitive(it, "pricing");
+  double miss, out;
+  if (json_num(cJSON_GetObjectItemCaseSensitive(pr, "prompt"), &miss) == 0 &&
+      json_num(cJSON_GetObjectItemCaseSensitive(pr, "completion"), &out) == 0 &&
+      miss >= 0 && out >= 0) {
+    double hit = miss, write = miss;
+    json_num(cJSON_GetObjectItemCaseSensitive(pr, "input_cache_read"), &hit);
+    json_num(cJSON_GetObjectItemCaseSensitive(pr, "input_cache_write"), &write);
+    m->has_price = 1;
+    m->miss = miss * 1e6;
+    m->out = out * 1e6;
+    m->hit = (hit >= 0 ? hit : miss) * 1e6;
+    m->write = (write >= 0 ? write : miss) * 1e6;
+  }
+}
+
+static int add_model(cst_model_meta_t *out, int n, int max_out,
+                     const char *id, const cJSON *it) {
+  if (!id || !id[0] || n >= max_out || strlen(id) >= sizeof(out->id))
     return n;
   for (int i = 0; i < n; i++)
-    if (strcmp(out[i], id) == 0)
+    if (strcmp(out[i].id, id) == 0)
       return n;
-  snprintf(out[n], 128, "%s", id);
+  memset(&out[n], 0, sizeof(out[n]));
+  out[n].vision = -1;
+  snprintf(out[n].id, sizeof(out[n].id), "%s", id);
+  if (cJSON_IsObject(it))
+    model_meta(it, &out[n]);
   return n + 1;
 }
 
 /* {"data":[{"id":..}]}, {"models":[{"id"|"name":..}]} or a bare array. */
-static int parse_models(const char *json, char out[][128], int max_out) {
+static int parse_models(const char *json, cst_model_meta_t *out, int max_out) {
   cJSON *root = cJSON_Parse(json);
   if (!root)
     return -1;
@@ -781,9 +1188,9 @@ static int parse_models(const char *json, char out[][128], int max_out) {
       if (!cJSON_IsString(id))
         id = cJSON_GetObjectItemCaseSensitive(it, "name");
       if (cJSON_IsString(id))
-        n = add_model(out, n, max_out, id->valuestring);
+        n = add_model(out, n, max_out, id->valuestring, it);
       else if (cJSON_IsString(it))
-        n = add_model(out, n, max_out, it->valuestring);
+        n = add_model(out, n, max_out, it->valuestring, NULL);
     }
   }
   cJSON_Delete(root);
@@ -793,6 +1200,24 @@ static int parse_models(const char *json, char out[][128], int max_out) {
 int cst_llm_list_models(const char *api_base, const char *api_key,
                         char out[][128], int max_out, char *err,
                         size_t err_sz) {
+  if (!out || max_out <= 0)
+    return cst_llm_list_models_meta(api_base, api_key, NULL, 0, err, err_sz);
+  cst_model_meta_t *m = calloc((size_t)max_out, sizeof(*m));
+  if (!m) {
+    if (err && err_sz)
+      snprintf(err, err_sz, "out of memory");
+    return -1;
+  }
+  int n = cst_llm_list_models_meta(api_base, api_key, m, max_out, err, err_sz);
+  for (int i = 0; i < n; i++)
+    snprintf(out[i], 128, "%s", m[i].id);
+  free(m);
+  return n;
+}
+
+int cst_llm_list_models_meta(const char *api_base, const char *api_key,
+                             cst_model_meta_t *out, int max_out, char *err,
+                             size_t err_sz) {
   char dummy[8];
   if (!err || !err_sz) {
     err = dummy;

src/main.c

@@ -1,7 +1,9 @@
 #include "cst_agent.h"
 #include "cst_ext.h"
+#include "cst_models.h"
 #include "cst_tools.h"
 #include "cst_version.h"
+#include "cst_webui.h"
 #include "os_compat.h"
 
 #include <curl/curl.h>
@@ -20,7 +22,8 @@
 static void usage(const char *argv0) {
   fprintf(stderr,
           "Usage: %s [options]        (works in the current directory)\n"
-          "  -P, --provider NAME   minimax | deepseek | openai (last used)\n"
+          "  -P, --provider NAME   minimax | deepseek | openai | teamorouter\n"
+          "                        (last used)\n"
           "  -m, --model NAME      model (last used for the provider)\n"
           "  -e, --effort LEVEL    low | medium | high | max (last used)\n"
           "  -w, --workspace DIR   project directory (default: current)\n"
@@ -28,6 +31,8 @@ static void usage(const char *argv0) {
           "  -N, --new             start a new session\n"
           "  -R, --resume ID       open a session by id or unique prefix\n"
           "  -L, --list-sessions   list sessions and exit\n"
+          "      --list-models [P] what is known about each provider's models\n"
+          "                        (built-in, <config>/models.json, GET /models)\n"
           "  -A, --approval MODE   ask | auto (default: edits run, shell in\n"
           "                        the sandbox or by safe rules) | yolo\n"
           "  -y, --yolo            same as --approval yolo (this run only)\n"
@@ -37,6 +42,13 @@ static void usage(const char *argv0) {
           "  -T, --tools PROFILE   default (all tools) | minimal (paper set)\n"
           "  -n, --max-steps N     model calls per turn (30)\n"
           "  -H, --headless -p TEXT  run one prompt without the TUI\n"
+          "      --web             serve the UI over HTTP on 127.0.0.1:8787\n"
+          "      --web-port N      port (default 8787, 0 = pick a free one)\n"
+          "      --web-host ADDR   bind address (default 127.0.0.1; a\n"
+          "                        non-loopback address requires a token)\n"
+          "      --web-token T     require ?token=T / Authorization: Bearer T\n"
+          "      --web-dev DIR     serve the UI from DIR (development)\n"
+          "      --web-open        open the browser at startup\n"
           "  -a, --ask-key         enter and save the provider's API key\n"
           "  -k, --api-key KEY     use KEY for this run only (not saved)\n"
           "  -b, --api-base URL    OpenAI-compatible base URL (…/v1)\n"
@@ -80,6 +92,62 @@ static int parse_confirm(const char *s, cst_agent_config_t *cfg) {
   return 0;
 }
 
+static void list_one_model(const char *provider, const char *id,
+                           const char *where) {
+  cst_model_info_t mi;
+  cst_model_info(provider, id, &mi);
+  char tag[48], price[128] = "";
+  cst_model_info_label(&mi, tag, sizeof(tag));
+  if (mi.has_price)
+    snprintf(price, sizeof(price), "  %s%g/%g/%g per 1M (miss/hit/out)",
+             mi.price.currency, mi.price.miss, mi.price.hit, mi.price.out);
+  printf("  %-40s %-18s %-8s%s  [%s]\n", id, tag, where, price, mi.source);
+}
+
+/* --list-models [provider]: the merged registry, to check models.json. */
+static int list_models(const char *only) {
+  char user[1100] = "";
+  cst_models_user_path(user, sizeof(user));
+  FILE *uf = user[0] ? fopen(user, "rb") : NULL;
+  printf("user file: %s%s\n", user[0] ? user : "(no config dir)",
+         uf ? "" : " (none)");
+  if (uf)
+    fclose(uf);
+  if (cst_models_load_error()[0])
+    printf("warning: %s\n", cst_models_load_error());
+  int shown = 0;
+  static cst_model_meta_t cached[1024];
+  for (int i = 0; i < cst_provider_count(); i++) {
+    const cst_provider_t *p = cst_provider_at(i);
+    if (only && only[0] && strcmp(p->name, only) != 0)
+      continue;
+    shown++;
+    printf("\n%s  %s  (%s; key %s)\n", p->name, p->api_base,
+           cst_provider_source(p), p->key_env[0] ? p->key_env : "-");
+    char listed[16][128];
+    int nl = cst_provider_models(p, listed, 16);
+    for (int k = 0; k < nl; k++)
+      list_one_model(p->name, listed[k],
+                     strcmp(listed[k], p->model) == 0 ? "default" : "listed");
+    long age = 0;
+    int nc = cst_models_cache_load(p->name, cached, 1024, &age);
+    if (nc > 0) {
+      printf("  -- %d from GET /models, fetched %ldh ago%s\n", nc,
+             age / 3600, age >= CST_MODELS_CACHE_TTL ? " (stale)" : "");
+      for (int k = 0; k < nc; k++)
+        list_one_model(p->name, cached[k].id, "api");
+    } else if (!nl) {
+      printf("  (no models listed; the first one GET /models returns is "
+             "used)\n");
+    }
+  }
+  if (only && only[0] && !shown) {
+    fprintf(stderr, "unknown provider: %s\n", only);
+    return 1;
+  }
+  return 0;
+}
+
 static int list_sessions(const char *ws) {
   static char ids[200][128];
   int n = cst_agent_store_list(ws, ids, 200);
@@ -187,6 +255,16 @@ static int demo_ctl_impl(const char *workspace) {
   return 0;
 }
 
+/* 0..65535, digits only: atoi turned "70000" into port 4464, "abc" into 0. */
+static int parse_port(const char *s, int *out) {
+  char *end = NULL;
+  long v = strtol(s, &end, 10);
+  if (!s[0] || *end || v < 0 || v > 65535)
+    return -1;
+  *out = (int)v;
+  return 0;
+}
+
 int main(int argc, char **argv) {
   if (os_console_init() != 0)
     fprintf(stderr, "warning: the process code page is not UTF-8 (Windows 10 "
@@ -260,6 +338,19 @@ int main(int argc, char **argv) {
   const char *prompt = NULL;
   int new_session = 0, do_list = 0;
   const char *resume_id = NULL;
+  /* WebUI (--web): a second front end on the same engine. */
+  int web_mode = 0;
+  cst_webui_opts_t web;
+  memset(&web, 0, sizeof(web));
+  web.port = CST_WEBUI_DEFAULT_PORT; /* 0 would mean "pick a free one" */
+  const char *env = getenv("CST_WEB_PORT");
+  if (env && env[0] && parse_port(env, &web.port) != 0) {
+    fprintf(stderr, "CST_WEB_PORT=%s is not a port (0-65535)\n", env);
+    return 1;
+  }
+  web.host = getenv("CST_WEB_HOST");
+  web.token = getenv("CST_WEB_TOKEN");
+  web.root = getenv("CST_WEB_ROOT");
 
   static struct option opts[] = {
       {"workspace", required_argument, 0, 'w'},
@@ -285,6 +376,13 @@ int main(int argc, char **argv) {
       {"effort", required_argument, 0, 'e'},
       {"help", no_argument, 0, 'h'},
       {"version", no_argument, 0, 'V'},
+      {"list-models", optional_argument, 0, 0x100},
+      {"web", no_argument, 0, 0x101},
+      {"web-port", required_argument, 0, 0x102},
+      {"web-host", required_argument, 0, 0x103},
+      {"web-token", required_argument, 0, 0x104},
+      {"web-dev", required_argument, 0, 0x105},
+      {"web-open", no_argument, 0, 0x106},
       {0, 0, 0, 0}};
   int c;
   while ((c = getopt_long(argc, argv, "w:s:b:k:m:P:r:n:T:Hp:dahVNcR:LyA:C:e:", opts, NULL)) !=
@@ -384,6 +482,41 @@ int main(int argc, char **argv) {
       usage(argv[0]);
       curl_global_cleanup();
       return 0;
+    case 0x100: {
+      const char *only = optarg;
+      if (!only && optind < argc && argv[optind][0] != '-')
+        only = argv[optind++];
+      int rc = list_models(only);
+      curl_global_cleanup();
+      return rc;
+    }
+    case 0x101:
+      web_mode = 1;
+      break;
+    case 0x102:
+      if (parse_port(optarg, &web.port) != 0) {
+        fprintf(stderr, "--web-port %s is not a port (0-65535)\n", optarg);
+        curl_global_cleanup();
+        return 1;
+      }
+      web_mode = 1;
+      break;
+    case 0x103:
+      web.host = optarg;
+      web_mode = 1;
+      break;
+    case 0x104:
+      web.token = optarg;
+      web_mode = 1;
+      break;
+    case 0x105:
+      web.root = optarg;
+      web_mode = 1;
+      break;
+    case 0x106:
+      web.open_browser = 1;
+      web_mode = 1;
+      break;
     case 'V':
       printf("cst-agent %s\n", CST_VERSION);
       curl_global_cleanup();
@@ -531,7 +664,7 @@ int main(int argc, char **argv) {
       return 0;
     }
   }
-  if (!cfg.api_key[0] && cfg.headless) {
+  if (!cfg.api_key[0] && (cfg.headless || web_mode)) {
     fprintf(stderr,
             "no API key for %s: start cst-agent once to enter it, or run "
             "cst-agent --ask-key --provider %s\n",
@@ -539,6 +672,30 @@ int main(int argc, char **argv) {
     curl_global_cleanup();
     return 1;
   }
+  /* Router presets have no fixed model: take the first one the API lists
+   * (the TUI does the same after its /models probe). */
+  if (!cfg.model[0] && (cfg.headless || web_mode)) {
+    static cst_model_meta_t list[512];
+    char err[256] = "";
+    long age = 0;
+    int n = cst_models_cache_load(cfg.provider, list, 1, &age);
+    if (n <= 0 || age >= CST_MODELS_CACHE_TTL) {
+      int r = cst_llm_list_models_meta(cfg.api_base, cfg.api_key, list, 512,
+                                       err, sizeof(err));
+      if (r >= 0)
+        cst_models_cache_save(cfg.provider, cfg.api_base, list, r);
+      if (r >= 0 || n <= 0)
+        n = r;
+    }
+    if (n > 0) {
+      snprintf(cfg.model, sizeof(cfg.model), "%s", list[0].id);
+    } else {
+      fprintf(stderr, "no model for %s: pass --model (%s)\n", cfg.provider,
+              err[0] ? err : "the API listed none");
+      curl_global_cleanup();
+      return 1;
+    }
+  }
 
   fprintf(stderr,
           "using %s model=%s effort=%s protocol=%s tools=%s max_steps=%d\n",
@@ -561,7 +718,10 @@ int main(int argc, char **argv) {
   }
 
   int rc = 0;
-  if (cfg.headless) {
+  if (web_mode) {
+    web.prompt = prompt; /* --web -p "...": run one turn at startup */
+    rc = cst_webui_run(agent, &web);
+  } else if (cfg.headless) {
     if (!prompt) {
       fprintf(stderr, "--headless requires --prompt\n");
       rc = 1;

src/mcp.c

@@ -6,6 +6,8 @@
 #endif
 
 #include "cst_mcp.h"
+#include "cst_agent.h"
+#include "cst_attach.h"
 
 #include <pthread.h>
 #include <stdatomic.h>
@@ -602,7 +604,56 @@ static int auto_approved(const mcp_srv_t *s, const char *tool) {
   return 0;
 }
 
-static void put_content(cst_buf_t *b, const cJSON *item) {
+/* Images a tool call returned, stored beside the session. */
+typedef struct {
+  const char *session;
+  const char *server;
+  cst_attachment_t *list;
+  int n, cap;
+} mcp_imgs_t;
+
+/* An image content item goes into the session store and rides along with the
+ * tool result; the text keeps a one-line description. 0 when stored. */
+static int put_image(cst_buf_t *b, const cJSON *item, mcp_imgs_t *im) {
+  const cJSON *d = cJSON_GetObjectItemCaseSensitive(item, "data");
+  if (!im || !cJSON_IsString(d))
+    return -1;
+  char err[256] = "no session to store the image in";
+  if (im->n >= CST_ATTACH_MAX_COUNT) {
+    snprintf(err, sizeof(err), "more than %d images", CST_ATTACH_MAX_COUNT);
+  } else if (im->session && im->session[0]) {
+    size_t n = 0;
+    char *raw = cst_base64_decode(d->valuestring, strlen(d->valuestring), &n);
+    char name[96];
+    snprintf(name, sizeof(name), "%s-%d", im->server, im->n + 1);
+    cst_attachment_t *a =
+        raw ? cst_attach_import_bytes(im->session, name, raw, n, err,
+                                      sizeof(err))
+            : NULL;
+    if (!raw)
+      snprintf(err, sizeof(err), "bad base64");
+    free(raw);
+    if (a) {
+      snprintf(a->origin, sizeof(a->origin), "mcp");
+      int pushed = cst_attachments_push(&im->list, &im->n, &im->cap, a) == 0;
+      char desc[128];
+      cst_attach_describe(a, desc, sizeof(desc));
+      cst_attach_free(a);
+      if (pushed) {
+        cst_buf_printf(b, "[image %s (shown to you as an image)]", desc);
+        return 0;
+      }
+      snprintf(err, sizeof(err), "out of memory");
+    }
+  }
+  const cJSON *mt = cJSON_GetObjectItemCaseSensitive(item, "mimeType");
+  cst_buf_printf(b, "[image %s, %zu bytes base64, not shown: %s]",
+                 cJSON_IsString(mt) ? mt->valuestring : "",
+                 strlen(d->valuestring), err);
+  return -1;
+}
+
+static void put_content(cst_buf_t *b, const cJSON *item, mcp_imgs_t *im) {
   const cJSON *type = cJSON_GetObjectItemCaseSensitive(item, "type");
   const char *t = cJSON_IsString(type) ? type->valuestring : "";
   if (b->len && b->buf[b->len - 1] != '\n')
@@ -611,6 +662,9 @@ static void put_content(cst_buf_t *b, const cJSON *item) {
     const cJSON *x = cJSON_GetObjectItemCaseSensitive(item, "text");
     if (cJSON_IsString(x))
       cst_buf_puts(b, x->valuestring);
+  } else if (strcmp(t, "image") == 0 &&
+             cJSON_IsString(cJSON_GetObjectItemCaseSensitive(item, "data"))) {
+    put_image(b, item, im);
   } else if (strcmp(t, "image") == 0 || strcmp(t, "audio") == 0) {
     const cJSON *mt = cJSON_GetObjectItemCaseSensitive(item, "mimeType");
     const cJSON *d = cJSON_GetObjectItemCaseSensitive(item, "data");
@@ -660,7 +714,6 @@ static int set_out(cst_tool_result_t *r, int code, const char *fmt, ...) {
 
 static int mcp_tool_run(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
                         cst_tool_result_t *r, void *ud) {
-  (void)ctx;
   mtool_t *mt = ud;
   mcp_srv_t *s = mt->srv;
   pthread_mutex_lock(&s->mu);
@@ -690,9 +743,12 @@ static int mcp_tool_run(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
   const cJSON *res = cJSON_GetObjectItemCaseSensitive(resp, "result");
   const cJSON *content = cJSON_GetObjectItemCaseSensitive(res, "content");
   cst_buf_t b = {0};
+  mcp_imgs_t im = {0};
+  im.session = ctx && ctx->agent ? cst_agent_session_path(ctx->agent) : NULL;
+  im.server = s->name;
   const cJSON *it = NULL;
   cJSON_ArrayForEach(it, content) {
-    put_content(&b, it);
+    put_content(&b, it, &im);
     if (b.len > MCP_OUT_MAX)
       break;
   }
@@ -716,6 +772,8 @@ static int mcp_tool_run(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
   cJSON_Delete(resp);
   r->out_len = b.len;
   r->out = cst_buf_steal(&b);
+  r->attach = im.list; /* one block, freed by cst_tool_result_free */
+  r->nattach = im.n;
   return 0;
 }
 

src/model_registry.c

@@ -0,0 +1,818 @@
+#include "cst_models.h"
+
+#include "cJSON.h"
+#include "os_compat.h"
+
+#include <ctype.h>
+#include <pthread.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <time.h>
+
+static const char BUILTIN[] = {
+#include "models_builtin.inc"
+    0};
+
+const char *cst_models_builtin_json(void) { return BUILTIN; }
+
+#define MAX_PROV 32
+#define MAX_PMODELS 16
+#define MAX_RULES 256
+
+typedef struct {
+  cst_provider_t pub; /* points into the buffers below */
+  char name[64];
+  char api_base[256];
+  char model[128];
+  char key_env[64];
+  int passback, prefix;
+  char effort[16]; /* "", "passthrough", "openai" */
+  char models[MAX_PMODELS][128];
+  int nmodels;
+  const char *source;
+} prov_t;
+
+enum { F_CONTEXT = 1, F_VISION = 2, F_CACHE = 4, F_REASONING = 8, F_PRICE = 16 };
+
+typedef struct {
+  char match[128]; /* lowercase */
+  int spec;        /* literal characters: higher is more specific */
+  unsigned has;    /* F_* set by this rule */
+  long context;
+  int vision, cache, reasoning;
+  cst_price_t price;
+} rule_t;
+
+typedef struct {
+  char provider[64];
+  long fetched_at;
+  cst_model_meta_t m;
+} cached_t;
+
+static pthread_mutex_t g_mu = PTHREAD_MUTEX_INITIALIZER;
+
+static struct {
+  int loaded;
+  prov_t prov[MAX_PROV];
+  int nprov;
+  rule_t builtin[MAX_RULES];
+  int nbuiltin;
+  rule_t user[MAX_RULES];
+  int nuser;
+  cached_t *cache;
+  int ncache;
+  char err[1400];
+} R;
+
+/* --- parsing ------------------------------------------------------------- */
+
+static void lower_copy(char *out, size_t n, const char *s) {
+  size_t i = 0;
+  for (; s && s[i] && i + 1 < n; i++)
+    out[i] = (char)tolower((unsigned char)s[i]);
+  out[i] = 0;
+}
+
+static const char *jstr(const cJSON *o, const char *k) {
+  const cJSON *v = cJSON_GetObjectItemCaseSensitive(o, k);
+  return cJSON_IsString(v) ? v->valuestring : NULL;
+}
+
+static void fix_pub(prov_t *p) {
+  p->pub.name = p->name;
+  p->pub.api_base = p->api_base;
+  p->pub.model = p->model;
+  p->pub.key_env = p->key_env;
+}
+
+static prov_t *prov_by_name(const char *name) {
+  for (int i = 0; i < R.nprov; i++)
+    if (strcmp(R.prov[i].name, name) == 0)
+      return &R.prov[i];
+  return NULL;
+}
+
+static void parse_providers(const cJSON *obj, const char *source) {
+  const cJSON *it = NULL;
+  cJSON_ArrayForEach(it, obj) {
+    if (!cJSON_IsObject(it) || !it->string || !it->string[0])
+      continue;
+    prov_t *p = prov_by_name(it->string);
+    if (!p) {
+      if (R.nprov >= MAX_PROV)
+        continue;
+      p = &R.prov[R.nprov++];
+      memset(p, 0, sizeof(*p));
+      snprintf(p->name, sizeof(p->name), "%s", it->string);
+      fix_pub(p);
+    }
+    p->source = source;
+    const char *s;
+    if ((s = jstr(it, "api_base")))
+      snprintf(p->api_base, sizeof(p->api_base), "%s", s);
+    if ((s = jstr(it, "key_env")))
+      snprintf(p->key_env, sizeof(p->key_env), "%s", s);
+    if ((s = jstr(it, "default_model")))
+      snprintf(p->model, sizeof(p->model), "%s", s);
+    if ((s = jstr(it, "effort")))
+      snprintf(p->effort, sizeof(p->effort), "%s", s);
+    const cJSON *b = cJSON_GetObjectItemCaseSensitive(it, "reasoning_passback");
+    if (cJSON_IsBool(b))
+      p->passback = cJSON_IsTrue(b);
+    b = cJSON_GetObjectItemCaseSensitive(it, "prefix_completion");
+    if (cJSON_IsBool(b))
+      p->prefix = cJSON_IsTrue(b);
+    const cJSON *ms = cJSON_GetObjectItemCaseSensitive(it, "models");
+    if (cJSON_IsArray(ms)) {
+      p->nmodels = 0;
+      const cJSON *m = NULL;
+      cJSON_ArrayForEach(m, ms) {
+        if (cJSON_IsString(m) && m->valuestring[0] && p->nmodels < MAX_PMODELS)
+          snprintf(p->models[p->nmodels++], 128, "%s", m->valuestring);
+      }
+    }
+  }
+}
+
+static int parse_price(const cJSON *o, cst_price_t *pr) {
+  const cJSON *miss = cJSON_GetObjectItemCaseSensitive(o, "miss");
+  const cJSON *out = cJSON_GetObjectItemCaseSensitive(o, "out");
+  if (!cJSON_IsNumber(miss) || !cJSON_IsNumber(out))
+    return -1;
+  memset(pr, 0, sizeof(*pr));
+  pr->miss = miss->valuedouble;
+  pr->out = out->valuedouble;
+  const cJSON *v = cJSON_GetObjectItemCaseSensitive(o, "hit");
+  pr->hit = cJSON_IsNumber(v) ? v->valuedouble : pr->miss;
+  v = cJSON_GetObjectItemCaseSensitive(o, "write");
+  pr->write = cJSON_IsNumber(v) ? v->valuedouble : pr->miss;
+  const char *c = jstr(o, "currency");
+  snprintf(pr->currency, sizeof(pr->currency), "%s", c ? c : "$");
+  pr->offpeak_half =
+      cJSON_IsTrue(cJSON_GetObjectItemCaseSensitive(o, "offpeak_half"));
+  return 0;
+}
+
+static int parse_rule(const cJSON *o, rule_t *r) {
+  const char *m = jstr(o, "match");
+  if (!m || !m[0])
+    return -1;
+  memset(r, 0, sizeof(*r));
+  lower_copy(r->match, sizeof(r->match), m);
+  for (const char *q = r->match; *q; q++)
+    if (*q != '*')
+      r->spec++;
+  const cJSON *v = cJSON_GetObjectItemCaseSensitive(o, "context");
+  if (cJSON_IsNumber(v) && v->valuedouble > 0) {
+    r->context = (long)v->valuedouble;
+    r->has |= F_CONTEXT;
+  }
+  v = cJSON_GetObjectItemCaseSensitive(o, "vision");
+  if (cJSON_IsBool(v)) {
+    r->vision = cJSON_IsTrue(v);
+    r->has |= F_VISION;
+  }
+  v = cJSON_GetObjectItemCaseSensitive(o, "reasoning");
+  if (cJSON_IsBool(v)) {
+    r->reasoning = cJSON_IsTrue(v);
+    r->has |= F_REASONING;
+  }
+  const char *c = jstr(o, "cache");
+  if (c) {
+    if (strcmp(c, "openai") == 0)
+      r->cache = CST_CACHE_OPENAI;
+    else if (strcmp(c, "anthropic") == 0)
+      r->cache = CST_CACHE_ANTHROPIC;
+    else
+      r->cache = CST_CACHE_AUTO;
+    r->has |= F_CACHE;
+  }
+  v = cJSON_GetObjectItemCaseSensitive(o, "price");
+  if (cJSON_IsObject(v) && parse_price(v, &r->price) == 0)
+    r->has |= F_PRICE;
+  return 0;
+}
+
+static int parse_doc(const char *json, int user, char *err, size_t err_sz) {
+  cJSON *doc = cJSON_Parse(json);
+  if (!cJSON_IsObject(doc)) {
+    cJSON_Delete(doc);
+    snprintf(err, err_sz, "not a JSON object");
+    return -1;
+  }
+  parse_providers(cJSON_GetObjectItemCaseSensitive(doc, "providers"),
+                  user ? "user" : "built-in");
+  rule_t *rules = user ? R.user : R.builtin;
+  int *n = user ? &R.nuser : &R.nbuiltin;
+  const cJSON *it = NULL;
+  cJSON_ArrayForEach(it, cJSON_GetObjectItemCaseSensitive(doc, "models")) {
+    if (*n < MAX_RULES && parse_rule(it, &rules[*n]) == 0)
+      (*n)++;
+  }
+  cJSON_Delete(doc);
+  return 0;
+}
+
+static char *read_file(const char *path) {
+  FILE *f = fopen(path, "rb");
+  if (!f)
+    return NULL;
+  char *buf = NULL;
+  size_t len = 0;
+  char chunk[8192];
+  size_t got;
+  while ((got = fread(chunk, 1, sizeof(chunk), f)) > 0 && len < (8u << 20)) {
+    char *nb = realloc(buf, len + got + 1);
+    if (!nb)
+      break;
+    buf = nb;
+    memcpy(buf + len, chunk, got);
+    len += got;
+  }
+  fclose(f);
+  if (buf)
+    buf[len] = 0;
+  return buf;
+}
+
+static int cache_path(const char *provider, char *out, size_t n) {
+  char dir[1024];
+  if (!provider || !provider[0] || os_config_dir(dir, sizeof(dir)) != 0)
+    return -1;
+  for (const char *q = provider; *q; q++)
+    if (!isalnum((unsigned char)*q) && !strchr("._-", *q))
+      return -1;
+  int w = snprintf(out, n, "%s/models-cache/%s.json", dir, provider);
+  return w > 0 && (size_t)w < n ? 0 : -1;
+}
+
+static void meta_from_json(const cJSON *o, cst_model_meta_t *m) {
+  memset(m, 0, sizeof(*m));
+  m->vision = -1;
+  const char *id = jstr(o, "id");
+  snprintf(m->id, sizeof(m->id), "%s", id ? id : "");
+  const cJSON *v = cJSON_GetObjectItemCaseSensitive(o, "context");
+  if (cJSON_IsNumber(v) && v->valuedouble > 0)
+    m->context = (long)v->valuedouble;
+  v = cJSON_GetObjectItemCaseSensitive(o, "vision");
+  if (cJSON_IsBool(v))
+    m->vision = cJSON_IsTrue(v);
+  v = cJSON_GetObjectItemCaseSensitive(o, "price");
+  cst_price_t pr;
+  if (cJSON_IsObject(v) && parse_price(v, &pr) == 0) {
+    m->has_price = 1;
+    m->miss = pr.miss;
+    m->hit = pr.hit;
+    m->write = pr.write;
+    m->out = pr.out;
+  }
+}
+
+/* Appends provider's cache file to R.cache (caller holds the lock). */
+static void load_cache(const char *provider) {
+  char path[1100];
+  if (cache_path(provider, path, sizeof(path)) != 0)
+    return;
+  char *txt = read_file(path);
+  cJSON *doc = txt ? cJSON_Parse(txt) : NULL;
+  free(txt);
+  const cJSON *fa = cJSON_GetObjectItemCaseSensitive(doc, "fetched_at");
+  long at = cJSON_IsNumber(fa) ? (long)fa->valuedouble : 0;
+  const cJSON *it = NULL;
+  cJSON_ArrayForEach(it, cJSON_GetObjectItemCaseSensitive(doc, "models")) {
+    cst_model_meta_t m;
+    meta_from_json(it, &m);
+    if (!m.id[0])
+      continue;
+    cached_t *nc = realloc(R.cache, (size_t)(R.ncache + 1) * sizeof(*nc));
+    if (!nc)
+      break;
+    R.cache = nc;
+    cached_t *c = &R.cache[R.ncache++];
+    snprintf(c->provider, sizeof(c->provider), "%s", provider);
+    c->fetched_at = at;
+    c->m = m;
+  }
+  cJSON_Delete(doc);
+}
+
+static void drop_cache(const char *provider) {
+  int w = 0;
+  for (int i = 0; i < R.ncache; i++)
+    if (provider && strcmp(R.cache[i].provider, provider) != 0)
+      R.cache[w++] = R.cache[i];
+  R.ncache = w;
+}
+
+static void reset_locked(void) {
+  R.nprov = 0;
+  R.nbuiltin = 0;
+  R.nuser = 0;
+  drop_cache(NULL);
+  R.err[0] = 0;
+}
+
+static void load_caches_locked(void) {
+  for (int i = 0; i < R.nprov; i++)
+    load_cache(R.prov[i].name);
+}
+
+int cst_models_user_path(char *out, size_t out_sz) {
+  char dir[1024];
+  if (os_config_dir(dir, sizeof(dir)) != 0)
+    return -1;
+  int w = snprintf(out, out_sz, "%s/models.json", dir);
+  return w > 0 && (size_t)w < out_sz ? 0 : -1;
+}
+
+static void load_default_locked(void) {
+  reset_locked();
+  char e[128];
+  if (parse_doc(BUILTIN, 0, e, sizeof(e)) != 0)
+    snprintf(R.err, sizeof(R.err), "built-in model data: %s", e);
+  char path[1100];
+  char *user = cst_models_user_path(path, sizeof(path)) == 0
+                   ? read_file(path)
+                   : NULL;
+  if (user && parse_doc(user, 1, e, sizeof(e)) != 0)
+    snprintf(R.err, sizeof(R.err), "%s: %s", path, e);
+  free(user);
+  load_caches_locked();
+  R.loaded = 1;
+}
+
+static void ensure_locked(void) {
+  if (!R.loaded)
+    load_default_locked();
+}
+
+void cst_models_reload(void) {
+  pthread_mutex_lock(&g_mu);
+  load_default_locked();
+  pthread_mutex_unlock(&g_mu);
+}
+
+int cst_models_load_json(const char *builtin_json, const char *user_json,
+                         char *err, size_t err_sz) {
+  char dummy[8];
+  if (!err || !err_sz) {
+    err = dummy;
+    err_sz = sizeof(dummy);
+  }
+  err[0] = 0;
+  pthread_mutex_lock(&g_mu);
+  reset_locked();
+  int rc = 0;
+  if (builtin_json && parse_doc(builtin_json, 0, err, err_sz) != 0)
+    rc = -1;
+  if (rc == 0 && user_json && parse_doc(user_json, 1, err, err_sz) != 0)
+    rc = -1;
+  load_caches_locked();
+  R.loaded = 1;
+  pthread_mutex_unlock(&g_mu);
+  return rc;
+}
+
+const char *cst_models_load_error(void) {
+  pthread_mutex_lock(&g_mu);
+  ensure_locked();
+  pthread_mutex_unlock(&g_mu);
+  return R.err;
+}
+
+/* --- providers ----------------------------------------------------------- */
+
+const cst_provider_t *cst_provider_find(const char *name) {
+  if (!name || !name[0])
+    return NULL;
+  pthread_mutex_lock(&g_mu);
+  ensure_locked();
+  prov_t *p = prov_by_name(name);
+  pthread_mutex_unlock(&g_mu);
+  return p ? &p->pub : NULL;
+}
+
+const cst_provider_t *cst_provider_default(void) {
+  const cst_provider_t *p = cst_provider_find(getenv("CST_PROVIDER"));
+  return p ? p : cst_provider_at(0);
+}
+
+int cst_provider_count(void) {
+  pthread_mutex_lock(&g_mu);
+  ensure_locked();
+  int n = R.nprov;
+  pthread_mutex_unlock(&g_mu);
+  return n;
+}
+
+const cst_provider_t *cst_provider_at(int i) {
+  pthread_mutex_lock(&g_mu);
+  ensure_locked();
+  const cst_provider_t *p = i >= 0 && i < R.nprov ? &R.prov[i].pub : NULL;
+  pthread_mutex_unlock(&g_mu);
+  return p;
+}
+
+const char *cst_provider_source(const cst_provider_t *p) {
+  for (int i = 0; p && i < MAX_PROV; i++)
+    if (p == &R.prov[i].pub)
+      return R.prov[i].source ? R.prov[i].source : "built-in";
+  return "";
+}
+
+int cst_provider_models(const cst_provider_t *p, char out[][128], int max) {
+  int n = 0;
+  pthread_mutex_lock(&g_mu);
+  for (int i = 0; p && i < R.nprov; i++) {
+    if (p != &R.prov[i].pub)
+      continue;
+    for (int k = 0; k < R.prov[i].nmodels && n < max; k++)
+      snprintf(out[n++], 128, "%s", R.prov[i].models[k]);
+  }
+  pthread_mutex_unlock(&g_mu);
+  return n;
+}
+
+static int push_name(char out[][128], int *n, int max, const char *name) {
+  if (!name || !name[0] || *n >= max)
+    return 0;
+  for (int i = 0; i < *n; i++)
+    if (strcmp(out[i], name) == 0)
+      return 0;
+  snprintf(out[(*n)++], 128, "%s", name);
+  return 1;
+}
+
+int cst_models_list(const char *current, char out[][128], int max_out) {
+  if (!out || max_out <= 0)
+    return 0;
+  int n = 0;
+  const char *env = getenv("CST_MODELS");
+  if (env && env[0]) {
+    char buf[1024];
+    snprintf(buf, sizeof(buf), "%s", env);
+    for (char *tok = buf; *tok;) {
+      while (*tok == ':' || *tok == ',' || *tok == ' ')
+        tok++;
+      char *end = tok;
+      while (*end && *end != ':' && *end != ',')
+        end++;
+      char save = *end;
+      *end = 0;
+      char *t = end;
+      while (t > tok && (t[-1] == ' ' || t[-1] == '\t'))
+        *--t = 0;
+      push_name(out, &n, max_out, tok);
+      *end = save;
+      tok = *end ? end + 1 : end;
+    }
+  } else {
+    pthread_mutex_lock(&g_mu);
+    ensure_locked();
+    for (int i = 0; i < R.nprov; i++)
+      for (int k = 0; k < R.prov[i].nmodels; k++)
+        push_name(out, &n, max_out, R.prov[i].models[k]);
+    pthread_mutex_unlock(&g_mu);
+  }
+  push_name(out, &n, max_out, current);
+  return n;
+}
+
+/* --- model lookup -------------------------------------------------------- */
+
+/* '*' matches any run; without one the pattern is a prefix. */
+static int glob(const char *p, const char *s) {
+  if (!strchr(p, '*'))
+    return strncmp(s, p, strlen(p)) == 0;
+  while (*p) {
+    if (*p == '*') {
+      while (*p == '*')
+        p++;
+      if (!*p)
+        return 1;
+      for (; *s; s++)
+        if (glob(p, s))
+          return 1;
+      return 0;
+    }
+    if (*p != *s)
+      return 0;
+    p++;
+    s++;
+  }
+  return !*s;
+}
+
+static void set_field(cst_model_info_t *o, unsigned f, const rule_t *r) {
+  switch (f) {
+  case F_CONTEXT:
+    o->context = r->context;
+    break;
+  case F_VISION:
+    o->vision = r->vision;
+    break;
+  case F_CACHE:
+    o->cache_style = r->cache;
+    break;
+  case F_REASONING:
+    o->reasoning = r->reasoning;
+    break;
+  case F_PRICE:
+    o->price = r->price;
+    o->has_price = 1;
+    break;
+  }
+}
+
+static void add_source(cst_model_info_t *o, const char *src) {
+  if (strstr(o->source, src))
+    return;
+  size_t l = strlen(o->source);
+  snprintf(o->source + l, sizeof(o->source) - l, "%s%s", l ? "+" : "", src);
+}
+
+static void apply_rules(const rule_t *rules, int n, const char *full,
+                        const char *bare, unsigned *have, cst_model_info_t *o,
+                        const char *src) {
+  for (unsigned f = 1; f <= F_PRICE; f <<= 1) {
+    if (*have & f)
+      continue;
+    const rule_t *best = NULL;
+    for (int i = 0; i < n; i++) {
+      const rule_t *r = &rules[i];
+      if (!(r->has & f) || (best && r->spec <= best->spec))
+        continue;
+      if (glob(r->match, strchr(r->match, '/') ? full : bare))
+        best = r;
+    }
+    if (best) {
+      set_field(o, f, best);
+      *have |= f;
+      add_source(o, src);
+    }
+  }
+}
+
+static void apply_cache(const char *provider, const char *model,
+                        unsigned *have, cst_model_info_t *o) {
+  for (int i = 0; i < R.ncache; i++) {
+    const cached_t *c = &R.cache[i];
+    if ((provider && strcmp(c->provider, provider) != 0) ||
+        strcmp(c->m.id, model) != 0)
+      continue;
+    unsigned before = *have;
+    if (!(*have & F_CONTEXT) && c->m.context > 0) {
+      o->context = c->m.context;
+      *have |= F_CONTEXT;
+    }
+    if (!(*have & F_VISION) && c->m.vision >= 0) {
+      o->vision = c->m.vision;
+      *have |= F_VISION;
+    }
+    if (!(*have & F_PRICE) && c->m.has_price) {
+      memset(&o->price, 0, sizeof(o->price));
+      snprintf(o->price.currency, sizeof(o->price.currency), "$");
+      o->price.miss = c->m.miss;
+      o->price.hit = c->m.hit;
+      o->price.write = c->m.write;
+      o->price.out = c->m.out;
+      o->has_price = 1;
+      *have |= F_PRICE;
+    }
+    if (*have != before)
+      add_source(o, "api");
+    return;
+  }
+}
+
+static int env_price(cst_price_t *out) {
+  const char *e = getenv("CST_PRICE");
+  if (!e || !e[0])
+    return -1;
+  memset(out, 0, sizeof(*out));
+  char cur[8] = "";
+  int n = sscanf(e, "%lf,%lf,%lf,%lf,%7s", &out->miss, &out->hit, &out->out,
+                 &out->write, cur);
+  if (n < 3)
+    return -1;
+  if (n < 4)
+    out->write = out->miss;
+  snprintf(out->currency, sizeof(out->currency), "%s", cur);
+  return 0;
+}
+
+void cst_model_info(const char *provider, const char *model,
+                    cst_model_info_t *out) {
+  memset(out, 0, sizeof(*out));
+  out->vision = -1;
+  unsigned have = 0;
+  const char *e = getenv("CST_CTX_TOKENS");
+  if (e && atol(e) > 0) {
+    out->context = atol(e);
+    have |= F_CONTEXT;
+    add_source(out, "env");
+  }
+  if (env_price(&out->price) == 0) {
+    out->has_price = 1;
+    have |= F_PRICE;
+    add_source(out, "env");
+  }
+  if (model && model[0]) {
+    char full[256], bare[256];
+    lower_copy(full, sizeof(full), model);
+    const char *slash = strrchr(full, '/');
+    snprintf(bare, sizeof(bare), "%s", slash && slash[1] ? slash + 1 : full);
+    pthread_mutex_lock(&g_mu);
+    ensure_locked();
+    apply_rules(R.user, R.nuser, full, bare, &have, out, "user");
+    if (provider && !prov_by_name(provider))
+      provider = NULL;
+    apply_cache(provider, model, &have, out);
+    apply_rules(R.builtin, R.nbuiltin, full, bare, &have, out, "built-in");
+    pthread_mutex_unlock(&g_mu);
+  }
+  if (!(have & F_CONTEXT)) {
+    out->context = 128000;
+    add_source(out, "default");
+  }
+}
+
+void cst_model_info_label(const cst_model_info_t *mi, char *out, size_t n) {
+  char ctx[32];
+  if (mi->context >= 1000000)
+    snprintf(ctx, sizeof(ctx), "%.0fM", (double)mi->context / 1e6);
+  else
+    snprintf(ctx, sizeof(ctx), "%ldK", (mi->context + 500) / 1000);
+  snprintf(out, n, "%s%s", ctx,
+           mi->vision == 1   ? " · vision"
+           : mi->vision == 0 ? " · text only"
+                             : "");
+}
+
+/* --- wrappers kept for the rest of the code ------------------------------ */
+
+long cst_model_context_tokens(const char *model) {
+  cst_model_info_t i;
+  cst_model_info(NULL, model, &i);
+  return i.context;
+}
+
+int cst_model_price(const char *model, cst_price_t *out) {
+  cst_model_info_t i;
+  cst_model_info(NULL, model, &i);
+  *out = i.price;
+  if (!i.has_price)
+    memset(out, 0, sizeof(*out));
+  return i.has_price ? 0 : -1;
+}
+
+/* "https://api.deepseek.com/v1" -> "api.deepseek.com" */
+static void host_of(const char *url, char *out, size_t n) {
+  const char *s = strstr(url, "://");
+  s = s ? s + 3 : url;
+  size_t i = 0;
+  for (; s[i] && s[i] != '/' && i + 1 < n; i++)
+    out[i] = s[i];
+  out[i] = 0;
+}
+
+void cst_model_caps(const char *provider, const char *api_base,
+                    const char *model, cst_model_caps_t *out) {
+  memset(out, 0, sizeof(*out));
+  pthread_mutex_lock(&g_mu);
+  ensure_locked();
+  /* provider extensions follow the provider, or its host behind any name */
+  for (int i = 0; i < R.nprov; i++) {
+    const prov_t *p = &R.prov[i];
+    if (!p->passback && !p->prefix)
+      continue;
+    char host[256];
+    host_of(p->api_base, host, sizeof(host));
+    if ((provider && strcmp(provider, p->name) == 0) ||
+        (api_base && host[0] && strstr(api_base, host))) {
+      out->reasoning_passback |= p->passback;
+      out->prefix_completion |= p->prefix;
+    }
+  }
+  pthread_mutex_unlock(&g_mu);
+  cst_model_info_t mi;
+  cst_model_info(provider, model, &mi);
+  out->vision = mi.vision;
+  const char *e = getenv("CST_NO_CACHE_HINTS");
+  if ((e && e[0] == '1') || !model)
+    return;
+  out->cache_style = mi.cache_style;
+}
+
+const char *cst_effort_wire(const char *provider, const char *model,
+                            const char *effort) {
+  if (!cst_effort_valid(effort) || !provider || !model)
+    return NULL;
+  char mode[16] = "";
+  pthread_mutex_lock(&g_mu);
+  ensure_locked();
+  const prov_t *p = prov_by_name(provider);
+  if (p)
+    snprintf(mode, sizeof(mode), "%s", p->effort);
+  pthread_mutex_unlock(&g_mu);
+  if (strcmp(mode, "passthrough") == 0)
+    return effort;
+  if (strcmp(mode, "openai") == 0) {
+    cst_model_info_t mi;
+    cst_model_info(provider, model, &mi);
+    if (mi.reasoning)
+      return strcmp(effort, "max") == 0 ? "high" : effort;
+  }
+  return NULL;
+}
+
+/* --- fetched cache ------------------------------------------------------- */
+
+int cst_models_cache_save(const char *provider, const char *api_base,
+                          const cst_model_meta_t *list, int n) {
+  char path[1100];
+  if (!list || n < 0 || cache_path(provider, path, sizeof(path)) != 0)
+    return -1;
+  char dir[1100];
+  snprintf(dir, sizeof(dir), "%s", path);
+  char *sl = strrchr(dir, '/');
+  if (sl)
+    *sl = 0;
+  os_mkdir_p(dir, 0700);
+
+  long now = (long)time(NULL);
+  cJSON *doc = cJSON_CreateObject();
+  cJSON_AddNumberToObject(doc, "fetched_at", (double)now);
+  if (api_base)
+    cJSON_AddStringToObject(doc, "api_base", api_base);
+  cJSON *arr = cJSON_AddArrayToObject(doc, "models");
+  for (int i = 0; i < n; i++) {
+    const cst_model_meta_t *m = &list[i];
+    cJSON *o = cJSON_CreateObject();
+    cJSON_AddStringToObject(o, "id", m->id);
+    if (m->context > 0)
+      cJSON_AddNumberToObject(o, "context", (double)m->context);
+    if (m->vision >= 0)
+      cJSON_AddBoolToObject(o, "vision", m->vision);
+    if (m->has_price) {
+      cJSON *p = cJSON_AddObjectToObject(o, "price");
+      cJSON_AddStringToObject(p, "currency", "$");
+      cJSON_AddNumberToObject(p, "miss", m->miss);
+      cJSON_AddNumberToObject(p, "hit", m->hit);
+      cJSON_AddNumberToObject(p, "write", m->write);
+      cJSON_AddNumberToObject(p, "out", m->out);
+    }
+    cJSON_AddItemToArray(arr, o);
+  }
+  char *txt = cJSON_Print(doc);
+  cJSON_Delete(doc);
+  if (!txt)
+    return -1;
+  char tmp[1200];
+  snprintf(tmp, sizeof(tmp), "%s.tmp", path);
+  FILE *f = fopen(tmp, "wb");
+  int rc = -1;
+  if (f) {
+    size_t len = strlen(txt);
+    rc = fwrite(txt, 1, len, f) == len ? 0 : -1;
+    if (fclose(f) != 0)
+      rc = -1;
+    if (rc == 0)
+      rc = os_rename_replace(tmp, path);
+    if (rc != 0)
+      remove(tmp);
+  }
+  free(txt);
+  if (rc == 0) {
+    pthread_mutex_lock(&g_mu);
+    ensure_locked();
+    drop_cache(provider);
+    load_cache(provider);
+    pthread_mutex_unlock(&g_mu);
+  }
+  return rc;
+}
+
+int cst_models_cache_load(const char *provider, cst_model_meta_t *out, int max,
+                          long *age_s) {
+  if (age_s)
+    *age_s = 0;
+  if (!provider)
+    return -1;
+  pthread_mutex_lock(&g_mu);
+  ensure_locked();
+  int n = 0, found = 0;
+  for (int i = 0; i < R.ncache; i++) {
+    const cached_t *c = &R.cache[i];
+    if (strcmp(c->provider, provider) != 0)
+      continue;
+    if (!found && age_s)
+      *age_s = (long)time(NULL) - c->fetched_at;
+    found = 1;
+    if (out && n < max)
+      out[n++] = c->m;
+  }
+  pthread_mutex_unlock(&g_mu);
+  return found ? n : -1;
+}

src/models.c

@@ -1,113 +1,37 @@
+#ifndef _DEFAULT_SOURCE
+#define _DEFAULT_SOURCE
+#endif
+
 #include "cst_agent.h"
 
-#include <stdio.h>
-#include <stdlib.h>
 #include <string.h>
+#include <time.h>
 
-#define MODEL_MAX_LEN 128
+/* Provider and model data live in model_registry.c (cst_models.h). */
 
-static const cst_provider_t PROVIDERS[] = {
-    {"minimax", "https://api.minimax.cn/v1", "MiniMax-M2.7", "MINIMAX_API_KEY"},
-    {"deepseek", "https://api.deepseek.com/v1", "deepseek-flash",
-     "DEEPSEEK_API_KEY"},
-    {"openai", "https://api.openai.com/v1", "gpt-4.1-mini", "OPENAI_API_KEY"},
-};
-
-const cst_provider_t *cst_provider_find(const char *name) {
-  if (!name || !name[0])
-    return NULL;
-  for (size_t i = 0; i < sizeof(PROVIDERS) / sizeof(PROVIDERS[0]); i++) {
-    if (strcmp(PROVIDERS[i].name, name) == 0)
-      return &PROVIDERS[i];
-  }
-  return NULL;
-}
-
-const cst_provider_t *cst_provider_default(void) {
-  const cst_provider_t *p = cst_provider_find(getenv("CST_PROVIDER"));
-  return p ? p : &PROVIDERS[0];
-}
-
-static int already(char out[][MODEL_MAX_LEN], int n, const char *name) {
-  for (int i = 0; i < n; i++) {
-    if (strcmp(out[i], name) == 0)
-      return 1;
-  }
-  return 0;
-}
-
-static int push(char out[][MODEL_MAX_LEN], int *n, int max, const char *name) {
-  if (!name || !name[0] || *n >= max)
+int cst_price_is_peak(time_t when) {
+  time_t bj = when + 8 * 3600;
+  struct tm tmv;
+#ifdef _WIN32
+  gmtime_s(&tmv, &bj);
+#else
+  gmtime_r(&bj, &tmv);
+#endif
+  if (tmv.tm_wday == 0 || tmv.tm_wday == 6)
     return 0;
-  if (already(out, *n, name))
-    return 0;
-  snprintf(out[*n], MODEL_MAX_LEN, "%s", name);
-  (*n)++;
-  return 1;
+  return (tmv.tm_hour >= 9 && tmv.tm_hour < 12) ||
+         (tmv.tm_hour >= 14 && tmv.tm_hour < 18);
 }
 
-int cst_models_list(const char *current, char out[][128], int max_out) {
-  if (!out || max_out <= 0)
+double cst_price_cost(const cst_price_t *p, long miss, long hit, long write,
+                      long out, time_t when) {
+  if (!p)
     return 0;
-  int n = 0;
-
-  const char *env = getenv("CST_MODELS");
-  if (env && env[0]) {
-    char buf[1024];
-    snprintf(buf, sizeof(buf), "%s", env);
-    char *p = buf;
-    while (*p && n < max_out) {
-      while (*p == ':' || *p == ' ' || *p == ',')
-        p++;
-      if (!*p)
-        break;
-      char *start = p;
-      while (*p && *p != ':' && *p != ',')
-        p++;
-      char save = *p;
-      *p = 0;
-      char *end = start + strlen(start);
-      while (end > start && (end[-1] == ' ' || end[-1] == '\t'))
-        *--end = 0;
-      push(out, &n, max_out, start);
-      *p = save;
-      if (*p)
-        p++;
-    }
-  } else {
-    push(out, &n, max_out, "deepseek-flash");
-    push(out, &n, max_out, "deepseek-v4-pro");
-    push(out, &n, max_out, "MiniMax-M2.7");
-    push(out, &n, max_out, "MiniMax-M2.5");
-    push(out, &n, max_out, "gpt-4.1-mini");
-    push(out, &n, max_out, "gpt-4o");
-  }
-
-  if (current && current[0])
-    push(out, &n, max_out, current);
-
-  return n;
-}
-
-/* Context window in tokens (CST_CTX_TOKENS overrides). Prefix match. */
-long cst_model_context_tokens(const char *model) {
-  const char *e = getenv("CST_CTX_TOKENS");
-  if (e && atol(e) > 0)
-    return atol(e);
-  static const struct {
-    const char *prefix;
-    long tokens;
-  } T[] = {{"deepseek", 128000}, {"MiniMax", 196608}, {"minimax", 196608},
-           {"gpt-4.1", 1047576}, {"gpt-4o", 128000},  {"gpt-5", 400000},
-           {"o3", 200000},       {"o4", 200000},      {"claude", 200000},
-           {"qwen", 131072},     {"glm", 128000},     {"kimi", 131072}};
-  if (model) {
-    for (size_t i = 0; i < sizeof(T) / sizeof(T[0]); i++) {
-      if (strncmp(model, T[i].prefix, strlen(T[i].prefix)) == 0)
-        return T[i].tokens;
-    }
-  }
-  return 128000;
+  double c = (miss * p->miss + hit * p->hit + write * p->write +
+              out * p->out) / 1e6;
+  if (p->offpeak_half && !cst_price_is_peak(when))
+    c /= 2;
+  return c;
 }
 
 int cst_effort_valid(const char *effort) {
@@ -118,25 +42,3 @@ int cst_effort_valid(const char *effort) {
   }
   return 0;
 }
-
-const char *cst_effort_wire(const char *provider, const char *model,
-                            const char *effort) {
-  if (!cst_effort_valid(effort) || !provider || !model)
-    return NULL;
-  if (strcmp(provider, "deepseek") == 0)
-    return effort;
-  /* OpenAI reasoning models take low | medium | high. */
-  if (strcmp(provider, "openai") == 0 &&
-      (strncmp(model, "o1", 2) == 0 || strncmp(model, "o3", 2) == 0 ||
-       strncmp(model, "o4", 2) == 0 || strncmp(model, "gpt-5", 5) == 0))
-    return strcmp(effort, "max") == 0 ? "high" : effort;
-  return NULL;
-}
-
-int cst_provider_count(void) {
-  return (int)(sizeof(PROVIDERS) / sizeof(PROVIDERS[0]));
-}
-
-const cst_provider_t *cst_provider_at(int i) {
-  return i >= 0 && i < cst_provider_count() ? &PROVIDERS[i] : NULL;
-}

src/models_builtin.json

@@ -0,0 +1,73 @@
+{
+  "providers": {
+    "minimax": {
+      "api_base": "https://api.minimax.cn/v1",
+      "key_env": "MINIMAX_API_KEY",
+      "default_model": "MiniMax-M2.7",
+      "models": ["MiniMax-M2.7", "MiniMax-M2.5"]
+    },
+    "deepseek": {
+      "api_base": "https://api.deepseek.com/v1",
+      "key_env": "DEEPSEEK_API_KEY",
+      "default_model": "deepseek-flash",
+      "models": ["deepseek-flash", "deepseek-v4-pro"],
+      "reasoning_passback": true,
+      "prefix_completion": true,
+      "effort": "passthrough"
+    },
+    "openai": {
+      "api_base": "https://api.openai.com/v1",
+      "key_env": "OPENAI_API_KEY",
+      "default_model": "gpt-4.1-mini",
+      "models": ["gpt-4.1-mini", "gpt-4o"],
+      "effort": "openai"
+    },
+    "teamorouter": {
+      "api_base": "https://api.teamorouter.com/v1",
+      "key_env": "TEAMOROUTER_API_KEY",
+      "default_model": ""
+    }
+  },
+  "models": [
+    {"match": "deepseek", "context": 1000000, "vision": false,
+     "price": {"currency": "¥", "miss": 2, "hit": 0.04, "out": 8, "offpeak_half": true}},
+    {"match": "deepseek-flash", "vision": true},
+    {"match": "deepseek-chat", "vision": true},
+    {"match": "deepseek-reasoner", "vision": true},
+    {"match": "deepseek-v4-pro",
+     "price": {"currency": "¥", "miss": 9, "hit": 0.3, "out": 27, "offpeak_half": true}},
+    {"match": "deepseek-vl", "vision": true},
+    {"match": "minimax", "context": 196608, "vision": false},
+
+    {"match": "gpt-", "cache": "openai"},
+    {"match": "gpt-4.1", "context": 1047576, "vision": true,
+     "price": {"currency": "$", "miss": 2, "hit": 0.5, "out": 8}},
+    {"match": "gpt-4.1-mini",
+     "price": {"currency": "$", "miss": 0.4, "hit": 0.1, "out": 1.6}},
+    {"match": "gpt-4o", "context": 128000, "vision": true,
+     "price": {"currency": "$", "miss": 2.5, "hit": 1.25, "out": 10}},
+    {"match": "gpt-4o-mini",
+     "price": {"currency": "$", "miss": 0.15, "hit": 0.075, "out": 0.6}},
+    {"match": "gpt-5", "context": 400000, "vision": true, "reasoning": true},
+    {"match": "o1", "vision": true, "cache": "openai", "reasoning": true},
+    {"match": "o3", "context": 200000, "vision": true, "cache": "openai", "reasoning": true},
+    {"match": "o4", "context": 200000, "vision": true, "cache": "openai", "reasoning": true},
+
+    {"match": "anthropic/", "cache": "anthropic"},
+    {"match": "claude", "context": 200000, "vision": true, "cache": "anthropic"},
+    {"match": "claude-sonnet",
+     "price": {"currency": "$", "miss": 3, "hit": 0.3, "write": 3.75, "out": 15}},
+
+    {"match": "gemini", "context": 1048576, "vision": true},
+    {"match": "grok", "context": 256000},
+    {"match": "grok-4", "vision": true},
+    {"match": "qwen", "context": 131072},
+    {"match": "glm", "context": 128000},
+    {"match": "glm-*v*", "vision": true},
+    {"match": "kimi", "context": 131072},
+    {"match": "pixtral", "vision": true},
+    {"match": "llava", "vision": true},
+    {"match": "*-vl*", "vision": true},
+    {"match": "*vision*", "vision": true}
+  ]
+}

src/net.c

@@ -0,0 +1,335 @@
+#ifndef _DEFAULT_SOURCE
+#define _DEFAULT_SOURCE
+#endif
+
+#include "cst_net.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#ifdef _WIN32
+#ifndef WIN32_LEAN_AND_MEAN
+#define WIN32_LEAN_AND_MEAN
+#endif
+#if !defined(_WIN32_WINNT) || _WIN32_WINNT < 0x0600
+#undef _WIN32_WINNT
+#define _WIN32_WINNT 0x0600 /* WSAPoll */
+#endif
+#include <winsock2.h>
+#include <ws2tcpip.h>
+#else
+#include <arpa/inet.h>
+#include <errno.h>
+#include <fcntl.h>
+#include <netdb.h>
+#include <netinet/in.h>
+#include <netinet/tcp.h>
+#include <poll.h>
+#include <signal.h>
+#include <sys/socket.h>
+#include <unistd.h>
+#endif
+
+#ifndef MSG_NOSIGNAL
+#define MSG_NOSIGNAL 0
+#endif
+
+#define NET_SEND_TIMEOUT_MS 20000
+
+static void set_err(char *err, size_t err_sz, const char *what) {
+  if (err && err_sz)
+    snprintf(err, err_sz, "%s", what);
+}
+
+#ifdef _WIN32
+static void set_err_win(char *err, size_t err_sz, const char *what) {
+  if (err && err_sz)
+    snprintf(err, err_sz, "%s (winsock error %d)", what, WSAGetLastError());
+}
+#define SET_ERR(e, n, w) set_err_win(e, n, w)
+#define NET_FD(s) ((SOCKET)(s))
+static void net_close_raw(os_socket_t s) { closesocket((SOCKET)s); }
+static int net_last_would_block(void) {
+  int e = WSAGetLastError();
+  return e == WSAEWOULDBLOCK || e == WSAEINTR;
+}
+static int net_last_conn_reset(void) {
+  int e = WSAGetLastError();
+  return e == WSAECONNRESET || e == WSAECONNABORTED || e == WSAENOTSOCK;
+}
+#else
+#define SET_ERR(e, n, w) set_err(e, n, w)
+#define NET_FD(s) ((int)(s))
+static void net_close_raw(os_socket_t s) { close(s); }
+static int net_last_would_block(void) { return errno == EINTR; }
+static int net_last_conn_reset(void) {
+  return errno == ECONNRESET || errno == EPIPE || errno == EBADF;
+}
+#endif
+
+int os_net_init(void) {
+#ifdef _WIN32
+  WSADATA w;
+  if (WSAStartup(MAKEWORD(2, 2), &w) != 0)
+    return -1;
+#else
+  /* A hung-up client must not kill the process with SIGPIPE. */
+  signal(SIGPIPE, SIG_IGN);
+#endif
+  return 0;
+}
+
+void os_net_cleanup(void) {
+#ifdef _WIN32
+  WSACleanup();
+#endif
+}
+
+/* poll, not select: FD_SET past FD_SETSIZE writes out of bounds, and a
+ * failed connect shows up as an error event, not as writable, on Windows. */
+static int wait_io(os_socket_t s, int want_write, int timeout_ms) {
+#ifdef _WIN32
+  WSAPOLLFD p;
+  p.fd = NET_FD(s);
+  p.events = want_write ? POLLWRNORM : POLLRDNORM;
+  p.revents = 0;
+  int rc = WSAPoll(&p, 1, timeout_ms < 0 ? -1 : timeout_ms);
+#else
+  struct pollfd p;
+  p.fd = NET_FD(s);
+  p.events = want_write ? POLLOUT : POLLIN;
+  p.revents = 0;
+  int rc = poll(&p, 1, timeout_ms < 0 ? -1 : timeout_ms);
+#endif
+  if (rc > 0)
+    return 1;
+  if (rc == 0)
+    return 0; /* timed out */
+  return -1;
+}
+
+/* Host to bind: AF_INET unless the name is an IPv6 literal, so "localhost"
+ * and "127.0.0.1" always mean the IPv4 loopback a browser will reach. */
+static int resolve_bind(const char *host, int port, struct sockaddr_storage *sa,
+                        socklen_t *sa_len) {
+  memset(sa, 0, sizeof(*sa));
+  int family = AF_INET;
+  const char *h = host && host[0] ? host : "127.0.0.1";
+  if (strchr(h, ':'))
+    family = AF_INET6;
+  struct addrinfo hints, *res = NULL;
+  memset(&hints, 0, sizeof(hints));
+  hints.ai_family = family;
+  hints.ai_socktype = SOCK_STREAM;
+  hints.ai_flags = AI_PASSIVE;
+  char portstr[16];
+  snprintf(portstr, sizeof(portstr), "%d", port);
+  if (getaddrinfo(h, portstr, &hints, &res) != 0 || !res)
+    return -1;
+  memcpy(sa, res->ai_addr, res->ai_addrlen);
+  *sa_len = (socklen_t)res->ai_addrlen;
+  freeaddrinfo(res);
+  return 0;
+}
+
+os_socket_t os_net_listen(const char *host, int port, char *err, size_t err_sz) {
+  struct sockaddr_storage sa;
+  socklen_t sa_len;
+  if (resolve_bind(host, port, &sa, &sa_len) != 0) {
+    SET_ERR(err, err_sz, "cannot resolve the bind address");
+    return OS_SOCKET_BAD;
+  }
+  os_socket_t s = (os_socket_t)socket(sa.ss_family, SOCK_STREAM, 0);
+  if (s == OS_SOCKET_BAD) {
+    SET_ERR(err, err_sz, "cannot create a socket");
+    return OS_SOCKET_BAD;
+  }
+  int one = 1;
+#ifdef _WIN32
+  /* SO_REUSEADDR on Windows lets another process bind the same port and
+   * take over our connections */
+  setsockopt(NET_FD(s), SOL_SOCKET, SO_EXCLUSIVEADDRUSE, (const char *)&one,
+             sizeof(one));
+#else
+  setsockopt(NET_FD(s), SOL_SOCKET, SO_REUSEADDR, (const char *)&one,
+             sizeof(one));
+#endif
+#ifdef IPV6_V6ONLY
+  if (sa.ss_family == AF_INET6)
+    setsockopt(NET_FD(s), IPPROTO_IPV6, IPV6_V6ONLY, (const char *)&one,
+               sizeof(one));
+#endif
+  if (bind(NET_FD(s), (const struct sockaddr *)&sa, sa_len) != 0) {
+    SET_ERR(err, err_sz, "the address is already in use");
+    net_close_raw(s);
+    return OS_SOCKET_BAD;
+  }
+  if (listen(NET_FD(s), 32) != 0) {
+    SET_ERR(err, err_sz, "listen failed");
+    net_close_raw(s);
+    return OS_SOCKET_BAD;
+  }
+  return s;
+}
+
+int os_net_port(os_socket_t s) {
+  struct sockaddr_storage sa;
+  socklen_t len = sizeof(sa);
+  if (getsockname(NET_FD(s), (struct sockaddr *)&sa, &len) != 0)
+    return 0;
+  if (sa.ss_family == AF_INET)
+    return ntohs(((struct sockaddr_in *)&sa)->sin_port);
+  if (sa.ss_family == AF_INET6)
+    return ntohs(((struct sockaddr_in6 *)&sa)->sin6_port);
+  return 0;
+}
+
+void os_net_peer(os_socket_t s, char *out, size_t out_sz) {
+  if (!out || out_sz == 0)
+    return;
+  out[0] = 0;
+  struct sockaddr_storage sa;
+  socklen_t len = sizeof(sa);
+  if (getpeername(NET_FD(s), (struct sockaddr *)&sa, &len) != 0)
+    return;
+  char ip[64] = "";
+  int port = 0;
+  if (sa.ss_family == AF_INET) {
+    if (!inet_ntop(AF_INET, &((struct sockaddr_in *)&sa)->sin_addr, ip,
+                   sizeof(ip)))
+      return;
+    port = ntohs(((struct sockaddr_in *)&sa)->sin_port);
+  } else if (sa.ss_family == AF_INET6) {
+    if (!inet_ntop(AF_INET6, &((struct sockaddr_in6 *)&sa)->sin6_addr, ip,
+                   sizeof(ip)))
+      return;
+    port = ntohs(((struct sockaddr_in6 *)&sa)->sin6_port);
+  } else {
+    return;
+  }
+  if (strchr(ip, ':'))
+    snprintf(out, out_sz, "[%s]:%d", ip, port);
+  else
+    snprintf(out, out_sz, "%s:%d", ip, port);
+}
+
+os_socket_t os_net_connect(const char *host, int port, int timeout_ms) {
+  const char *h = host && host[0] ? host : "127.0.0.1";
+  struct addrinfo hints, *res = NULL;
+  memset(&hints, 0, sizeof(hints));
+  hints.ai_family = strchr(h, ':') ? AF_INET6 : AF_INET;
+  hints.ai_socktype = SOCK_STREAM;
+  char portstr[16];
+  snprintf(portstr, sizeof(portstr), "%d", port);
+  if (getaddrinfo(h, portstr, &hints, &res) != 0 || !res)
+    return OS_SOCKET_BAD;
+  os_socket_t s = (os_socket_t)socket(res->ai_family, SOCK_STREAM, 0);
+  if (s == OS_SOCKET_BAD) {
+    freeaddrinfo(res);
+    return OS_SOCKET_BAD;
+  }
+  /* Bounded wait: connect() non-blocking, poll, then read SO_ERROR. A dead
+   * server must not hang the caller. */
+#ifdef _WIN32
+  u_long nb = 1;
+  ioctlsocket(NET_FD(s), FIONBIO, &nb);
+#else
+  int fl = fcntl(s, F_GETFL, 0);
+  fcntl(s, F_SETFL, fl | O_NONBLOCK);
+#endif
+  int rc = connect(NET_FD(s), res->ai_addr, (int)res->ai_addrlen);
+  freeaddrinfo(res);
+  if (rc != 0) {
+#ifdef _WIN32
+    int in_progress = WSAGetLastError() == WSAEWOULDBLOCK;
+#else
+    int in_progress = errno == EINPROGRESS || errno == EINTR;
+#endif
+    if (!in_progress || wait_io(s, 1, timeout_ms) <= 0) {
+      net_close_raw(s);
+      return OS_SOCKET_BAD;
+    }
+    int soerr = 0;
+    socklen_t elen = sizeof(soerr);
+    if (getsockopt(NET_FD(s), SOL_SOCKET, SO_ERROR, (char *)&soerr, &elen) != 0 ||
+        soerr != 0) {
+      net_close_raw(s);
+      return OS_SOCKET_BAD;
+    }
+  }
+#ifdef _WIN32
+  nb = 0;
+  ioctlsocket(NET_FD(s), FIONBIO, &nb);
+#else
+  fcntl(s, F_SETFL, fl);
+#endif
+  return s;
+}
+
+os_socket_t os_net_accept(os_socket_t s, int timeout_ms, int *timed_out) {
+  if (timed_out)
+    *timed_out = 0;
+  int w = wait_io(s, 0, timeout_ms);
+  if (w == 0) {
+    if (timed_out)
+      *timed_out = 1;
+    return OS_SOCKET_BAD;
+  }
+  if (w < 0)
+    return OS_SOCKET_BAD;
+  os_socket_t c = (os_socket_t)accept(NET_FD(s), NULL, NULL);
+  if (c == OS_SOCKET_BAD)
+    return OS_SOCKET_BAD;
+  int one = 1;
+  setsockopt(NET_FD(c), IPPROTO_TCP, TCP_NODELAY, (const char *)&one,
+             sizeof(one));
+  return c;
+}
+
+long os_net_recv(os_socket_t s, void *buf, size_t n, int timeout_ms) {
+  int w = wait_io(s, 0, timeout_ms);
+  if (w == 0)
+    return -2;
+  if (w < 0)
+    return -1;
+  size_t want = n > (size_t)(1 << 20) ? (size_t)(1 << 20) : n;
+  int r = (int)recv(NET_FD(s), (char *)buf, (int)want, 0);
+  if (r == 0)
+    return 0;
+  if (r < 0)
+    return net_last_conn_reset() ? 0 : (net_last_would_block() ? -2 : -1);
+  return r;
+}
+
+int os_net_send_all(os_socket_t s, const void *buf, size_t n, int timeout_ms) {
+  const char *p = buf;
+  size_t off = 0;
+  while (off < n) {
+    int w = wait_io(s, 1, timeout_ms ? timeout_ms : NET_SEND_TIMEOUT_MS);
+    if (w <= 0)
+      return -1;
+    long r = (long)send(NET_FD(s), p + off, (int)(n - off), MSG_NOSIGNAL);
+    if (r <= 0) {
+      if (net_last_would_block())
+        continue;
+      return -1;
+    }
+    off += (size_t)r;
+  }
+  return 0;
+}
+
+void os_net_shutdown(os_socket_t s) {
+#ifdef _WIN32
+  shutdown((SOCKET)s, SD_BOTH);
+#else
+  shutdown(s, SHUT_RDWR);
+#endif
+}
+
+void os_net_close(os_socket_t s) {
+  if (s == OS_SOCKET_BAD)
+    return;
+  net_close_raw(s);
+}

src/os_compat.c

@@ -519,7 +519,7 @@ int os_run_timeout_effective(void) {
   const char *e = getenv("CST_SHELL_TIMEOUT");
   if (e && atoi(e) > 0)
     return atoi(e);
-  return 120;
+  return 0; /* no limit: a build, a test suite or a long clone must finish */
 }
 
 double os_now_ms(void) {
@@ -662,7 +662,8 @@ int os_run_capture_ex(const char *cwd, const char *const argv[],
   int truncated = 0, killed = 0;
   int status = 0, reaped = 0, bg_killed = 0;
   double reaped_at = 0, killed_at = 0;
-  double deadline = os_now_ms() + os_run_timeout_effective() * 1000.0;
+  int timeout_s = os_run_timeout_effective();
+  double deadline = timeout_s > 0 ? os_now_ms() + timeout_s * 1000.0 : 0;
   for (;;) {
     struct pollfd pfd = {pipefd[0], POLLIN, 0};
     int pr = poll(&pfd, 1, 100);
@@ -692,7 +693,7 @@ int os_run_capture_ex(const char *cwd, const char *const argv[],
     }
     /* Checked on every pass, so a chatty command still stops promptly. */
     if (!reaped && !killed &&
-        ((g_run_cancel && *g_run_cancel) || now > deadline)) {
+        ((g_run_cancel && *g_run_cancel) || (deadline > 0 && now > deadline))) {
       killed = (g_run_cancel && *g_run_cancel) ? 2 : 1;
       killed_at = now;
       kill(-pid, SIGTERM);

src/os_win.c

@@ -601,7 +601,10 @@ int os_run_capture_token(const char *cwd, const char *const argv[],
   buf[0] = 0;
   int truncated = 0, killed = 0, reaped = 0, bg_killed = 0;
   double reaped_at = 0, killed_at = 0;
-  double deadline = os_now_ms() + os_run_timeout_effective() * 1000.0;
+  /* no timeout unless one was asked for: a deadline far in the future keeps
+   * every `now > deadline` check working without a second code path */
+  int timeout_s = os_run_timeout_effective();
+  double deadline = timeout_s > 0 ? os_now_ms() + timeout_s * 1000.0 : 1e18;
   int idle = 0; /* empty polls in a row: wait longer once output stalls */
   for (;;) {
     DWORD avail = 0;

src/provider_switch.c

@@ -0,0 +1,193 @@
+#include "cst_provider_switch.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+int cst_ps_fetch(const char *provider, const char *api_base, const char *key,
+                 char ids[][128], int max, char *err, size_t err_sz) {
+  cst_model_meta_t *m = calloc((size_t)(max > 0 ? max : 1), sizeof(*m));
+  if (!m) {
+    snprintf(err, err_sz, "out of memory");
+    return -1;
+  }
+  int r = cst_llm_list_models_meta(api_base, key, m, max, err, err_sz);
+  if (r >= 0)
+    cst_models_cache_save(provider, api_base, m, r);
+  for (int i = 0; i < r; i++)
+    snprintf(ids[i], 128, "%s", m[i].id);
+  free(m);
+  return r;
+}
+
+int cst_ps_cached(const char *provider, char ids[][128], int max, int *fresh) {
+  *fresh = 0;
+  cst_model_meta_t *m = calloc((size_t)(max > 0 ? max : 1), sizeof(*m));
+  if (!m)
+    return -1;
+  long age = 0;
+  int n = cst_models_cache_load(provider, m, max, &age);
+  for (int i = 0; i < n; i++)
+    snprintf(ids[i], 128, "%s", m[i].id);
+  free(m);
+  *fresh = n > 0 && age >= 0 && age < CST_MODELS_CACHE_TTL;
+  return n > 0 ? n : -1;
+}
+
+const char *cst_ps_base(const cst_agent_config_t *cfg, const char *provider) {
+  if (cfg && strcmp(cfg->provider, provider) == 0)
+    return cfg->api_base;
+  const cst_provider_t *p = cst_provider_find(provider);
+  return p ? p->api_base : "";
+}
+
+int cst_ps_models(const cst_agent_config_t *cfg, int refresh,
+                  cst_ps_model_t *out, int max, int *api_rc, char *err,
+                  size_t err_sz) {
+  err[0] = 0;
+  *api_rc = -1;
+  char(*ids)[128] = calloc(CST_PS_MAX_MODELS, sizeof(*ids));
+  if (!ids) {
+    snprintf(err, err_sz, "out of memory");
+    return 0;
+  }
+  int fresh = 0;
+  int na = cst_ps_cached(cfg->provider, ids, CST_PS_MAX_MODELS, &fresh);
+  *api_rc = na;
+  if ((refresh || !fresh) && cfg->api_key[0]) {
+    char(*got)[128] = calloc(CST_PS_MAX_MODELS, sizeof(*got));
+    if (got) {
+      int r = cst_ps_fetch(cfg->provider, cfg->api_base, cfg->api_key, got,
+                           CST_PS_MAX_MODELS, err, err_sz);
+      *api_rc = r;
+      if (r >= 0) {
+        memcpy(ids, got, (size_t)r * sizeof(*ids));
+        na = r;
+      }
+      free(got);
+    }
+  }
+  int n = 0;
+  for (int i = 0; i < na && n < max; i++, n++) {
+    snprintf(out[n].id, sizeof(out[n].id), "%s", ids[i]);
+    out[n].api = 1;
+    cst_model_info(cfg->provider, ids[i], &out[n].info);
+  }
+  char builtin[32][128];
+  int nb = cst_models_list(cfg->model, builtin, 32);
+  for (int i = 0; i < nb && n < max; i++) {
+    int dup = 0;
+    for (int k = 0; k < na && !dup; k++)
+      dup = strcmp(ids[k], builtin[i]) == 0;
+    if (dup)
+      continue;
+    memcpy(out[n].id, builtin[i], sizeof(out[n].id));
+    out[n].id[sizeof(out[n].id) - 1] = 0;
+    out[n].api = 0;
+    cst_model_info(cfg->provider, builtin[i], &out[n].info);
+    n++;
+  }
+  free(ids);
+  return n;
+}
+
+int cst_ps_verify_save(const char *provider, const char *api_base,
+                       const char *key, char ids[][128], int max, int *nids,
+                       char *err, size_t err_sz) {
+  err[0] = 0;
+  char(*own)[128] = NULL;
+  if (!ids) {
+    own = calloc(CST_PS_MAX_MODELS, sizeof(*own));
+    if (!own) {
+      snprintf(err, err_sz, "out of memory");
+      return CST_PS_UNVERIFIED | CST_PS_UNSAVED;
+    }
+    ids = own;
+    max = CST_PS_MAX_MODELS;
+  }
+  int r = cst_ps_fetch(provider, api_base, key, ids, max, err, err_sz);
+  free(own);
+  if (nids)
+    *nids = r;
+  if (r == CST_MODELS_AUTH)
+    return CST_MODELS_AUTH;
+  int flags = r < 0 ? CST_PS_UNVERIFIED : 0;
+  if (r >= 0)
+    err[0] = 0;
+  if (cst_creds_save(provider, key) != 0)
+    flags |= CST_PS_UNSAVED;
+  return flags;
+}
+
+void cst_ps_apply_provider(cst_agent_config_t *cfg, const cst_provider_t *p,
+                           const char *key) {
+  cst_settings_t s;
+  cst_settings_load(&s);
+  const char *model = cst_settings_model(&s, p->name);
+  snprintf(cfg->provider, sizeof(cfg->provider), "%s", p->name);
+  snprintf(cfg->api_base, sizeof(cfg->api_base), "%s", p->api_base);
+  snprintf(cfg->model, sizeof(cfg->model), "%s", model ? model : p->model);
+  snprintf(cfg->api_key, sizeof(cfg->api_key), "%s", key);
+  cst_settings_remember(cfg);
+}
+
+int cst_ps_switch_provider(cst_agent_config_t *cfg, const char *name,
+                           const char *key, char *err, size_t err_sz) {
+  err[0] = 0;
+  const cst_provider_t *p = name ? cst_provider_find(name) : NULL;
+  if (!p) {
+    snprintf(err, err_sz, "unknown provider '%.64s'", name ? name : "");
+    return CST_PS_UNKNOWN;
+  }
+  char k[512];
+  int flags = 0;
+  char(*ids)[128] = calloc(CST_PS_MAX_MODELS, sizeof(*ids));
+  int nids = -1;
+  if (key && key[0]) {
+    snprintf(k, sizeof(k), "%s", key);
+    flags = cst_ps_verify_save(p->name, p->api_base, k, ids,
+                               ids ? CST_PS_MAX_MODELS : 0, &nids, err,
+                               err_sz);
+    if (flags < 0) {
+      memset(k, 0, sizeof(k));
+      free(ids);
+      return flags;
+    }
+  } else if (cst_creds_resolve(p->name, k, sizeof(k), NULL) != 0) {
+    free(ids);
+    snprintf(err, err_sz, "%s needs an API key", p->name);
+    return CST_PS_NEED_KEY;
+  }
+  cst_ps_apply_provider(cfg, p, k);
+  memset(k, 0, sizeof(k));
+  if (!cfg->model[0] && ids) {
+    /* a router preset: the first model the API lists */
+    int fresh = 0;
+    if (nids <= 0)
+      nids = cst_ps_cached(p->name, ids, CST_PS_MAX_MODELS, &fresh);
+    if (nids <= 0) {
+      char e2[256];
+      nids = cst_ps_fetch(p->name, cfg->api_base, cfg->api_key, ids,
+                          CST_PS_MAX_MODELS, e2, sizeof(e2));
+    }
+    if (nids > 0) {
+      snprintf(cfg->model, sizeof(cfg->model), "%s", ids[0]);
+      cst_settings_remember(cfg);
+    }
+  }
+  free(ids);
+  return flags;
+}
+
+int cst_ps_set_key(cst_agent_config_t *cfg, const char *key, char *err,
+                   size_t err_sz) {
+  if (!key || !key[0]) {
+    snprintf(err, err_sz, "empty key");
+    return CST_PS_NEED_KEY;
+  }
+  int r = cst_ps_verify_save(cfg->provider, cfg->api_base, key, NULL, 0, NULL,
+                             err, err_sz);
+  if (r >= 0)
+    snprintf(cfg->api_key, sizeof(cfg->api_key), "%s", key);
+  return r;
+}

src/sandbox_exec.c

@@ -86,8 +86,6 @@ static int g_abi;
 #define LL_FS_MAKE_SYM (1ULL << 12)
 #define LL_FS_REFER (1ULL << 13)    /* ABI 2 */
 #define LL_FS_TRUNCATE (1ULL << 14) /* ABI 3 */
-#define LL_NET_BIND_TCP (1ULL << 0)    /* ABI 4 */
-#define LL_NET_CONNECT_TCP (1ULL << 1) /* ABI 4 */
 
 struct ll_ruleset_attr {
   uint64_t handled_access_fs;
@@ -137,9 +135,7 @@ static int ll_prepare(const char *ws, const char *tmp, cst_sandbox_plan_t *p) {
   int abi = g_abi;
   struct ll_ruleset_attr attr;
   memset(&attr, 0, sizeof(attr));
-  attr.handled_access_fs = ll_write_rights(abi);
-  if (abi >= 4)
-    attr.handled_access_net = LL_NET_BIND_TCP | LL_NET_CONNECT_TCP;
+  attr.handled_access_fs = ll_write_rights(abi); /* network stays open */
   int fd = (int)syscall(__NR_landlock_create_ruleset, &attr, sizeof(attr), 0);
   if (fd < 0)
     return -1;
@@ -193,8 +189,7 @@ static int sb_prepare(const char *ws, const char *tmp, cst_sandbox_plan_t *p) {
            "(version 1)(allow default)(deny file-write*)"
            "(allow file-write* (subpath \"%s\") (subpath \"%s\") "
            "(literal \"/dev/null\") (literal \"/dev/tty\") "
-           "(literal \"/dev/dtracehelper\"))"
-           "(deny network*)",
+           "(literal \"/dev/dtracehelper\"))",
            qws, qtmp);
   return 0;
 }
@@ -290,9 +285,8 @@ static const int SC_NOTIFY[] = {
 #endif
 };
 
-/* Foreign ABIs are refused, IPv4/IPv6 sockets fail with EACCES, opens
- * without write flags pass untouched, write-type calls go to the
- * supervisor. */
+/* Foreign ABIs are refused, opens without write flags pass untouched,
+ * write-type calls go to the supervisor. */
 static void sc_build(sc_prog_t *p) {
   p->n = 0;
   SC_LD(offsetof(struct seccomp_data, arch));
@@ -303,12 +297,6 @@ static void sc_build(sc_prog_t *p) {
   sc_emit(p, BPF_JMP | BPF_JGE | BPF_K, 0, 1, 0x40000000U); /* x32 */
   SC_RET(SECCOMP_RET_ERRNO | EPERM);
 #endif
-  SC_JEQ(__NR_socket, 0, 5);
-  SC_LD(SC_ARG(0));
-  SC_JEQ(AF_INET, 2, 0);
-  SC_JEQ(AF_INET6, 1, 0);
-  SC_RET(SECCOMP_RET_ALLOW);
-  SC_RET(SECCOMP_RET_ERRNO | EACCES);
   SC_JEQ(__NR_io_uring_setup, 0, 1);
   SC_RET(SECCOMP_RET_ERRNO | EPERM);
   SC_JEQ(__NR_openat, 0, 4);
@@ -1446,9 +1434,7 @@ int cst_sandbox_blocked(const char *out, size_t n, int exit_code) {
   static const char *const SIGNS[] = {
       "Permission denied", "Read-only file system", "Operation not permitted",
       "EACCES",            "EPERM",                 "EROFS",
-      "[cst: sandbox",     "Network is unreachable",
-      /* curl when the socket itself was refused (seccomp) */
-      "Could not connect to server", "Failed to connect to",
+      "[cst: sandbox",
       /* localized strerror(EACCES/EPERM/EROFS) */
       "权限不够", "不允许的操作", "只读文件系统", "權限不足",
       "拒絕不符權限的操作", "許可がありません", "Keine Berechtigung",

src/session.c

@@ -7,6 +7,7 @@
 
 #include "cJSON.h"
 #include "cst_agent.h"
+#include "cst_attach.h"
 
 #include <pthread.h>
 #include <stdio.h>
@@ -97,7 +98,11 @@ static void msg_free(cst_message_t *m) {
   free(m->content);
   free(m->tool_calls_json);
   free(m->meta_json);
-  m->content = m->tool_calls_json = m->meta_json = NULL;
+  free(m->reasoning);
+  cst_attachments_free(m->attach, m->nattach);
+  m->content = m->tool_calls_json = m->meta_json = m->reasoning = NULL;
+  m->attach = NULL;
+  m->nattach = 0;
 }
 
 static int session_grow(cst_session_t *s) {
@@ -127,6 +132,16 @@ static int session_push_mem(cst_session_t *s, const cst_message_t *src) {
     d->tool_calls_json = xstrdup(src->tool_calls_json);
   if (src->meta_json && src->meta_json[0])
     d->meta_json = xstrdup(src->meta_json);
+  if (src->reasoning && src->reasoning[0])
+    d->reasoning = xstrdup(src->reasoning);
+  if (src->attach && src->nattach > 0) {
+    d->attach = cst_attachments_dup(src->attach, src->nattach);
+    if (!d->attach) {
+      msg_free(d);
+      return -1;
+    }
+    d->nattach = src->nattach;
+  }
   s->nmsgs++;
   return 0;
 }
@@ -174,9 +189,14 @@ static void load_existing(cst_session_t *s) {
     if (cJSON_IsObject(mo))
       meta = cJSON_PrintUnformatted(mo);
     m.meta_json = meta;
+    m.reasoning = (char *)jstr(o, "reasoning");
+    const cJSON *at = cJSON_GetObjectItemCaseSensitive(o, "attachments");
+    if (cJSON_IsArray(at))
+      m.attach = cst_attachments_from_json(at, &m.nattach);
     session_push_mem(s, &m);
     free(tcj);
     free(meta);
+    cst_attachments_free(m.attach, m.nattach);
     cJSON_Delete(o);
   }
   free(line);
@@ -249,6 +269,8 @@ static int write_line(FILE *fp, const cst_message_t *msg) {
       cJSON_AddStringToObject(o, "tool_calls_json", msg->tool_calls_json);
     }
   }
+  if (msg->reasoning && msg->reasoning[0])
+    cJSON_AddStringToObject(o, "reasoning", msg->reasoning);
   if (msg->meta_json && msg->meta_json[0]) {
     cJSON *mo = cJSON_Parse(msg->meta_json);
     if (cJSON_IsObject(mo))
@@ -256,6 +278,28 @@ static int write_line(FILE *fp, const cst_message_t *msg) {
     else
       cJSON_Delete(mo);
   }
+  if (msg->attach && msg->nattach > 0) {
+    cJSON *arr = cJSON_CreateArray();
+    for (int i = 0; i < msg->nattach; i++) {
+      const cst_attachment_t *a = &msg->attach[i];
+      cJSON *it = cJSON_CreateObject();
+      cJSON_AddStringToObject(it, "id", a->id);
+      cJSON_AddStringToObject(it, "name", a->name);
+      cJSON_AddStringToObject(it, "mime", a->mime);
+      cJSON_AddStringToObject(it, "rel", a->rel);
+      cJSON_AddNumberToObject(it, "bytes", (double)a->bytes);
+      if (a->width > 0 && a->height > 0) {
+        cJSON_AddNumberToObject(it, "width", a->width);
+        cJSON_AddNumberToObject(it, "height", a->height);
+      }
+      if (a->detail[0])
+        cJSON_AddStringToObject(it, "detail", a->detail);
+      if (a->origin[0])
+        cJSON_AddStringToObject(it, "origin", a->origin);
+      cJSON_AddItemToArray(arr, it);
+    }
+    cJSON_AddItemToObject(o, "attachments", arr);
+  }
   char *txt = cJSON_PrintUnformatted(o);
   cJSON_Delete(o);
   if (!txt)
@@ -310,6 +354,7 @@ int cst_session_clear(cst_session_t *s, int keep_system) {
       if (s->msgs[i].role == CST_ROLE_SYSTEM) {
         sys.role = CST_ROLE_SYSTEM;
         sys.content = xstrdup(s->msgs[i].content ? s->msgs[i].content : "");
+        sys.meta_json = xstrdup(s->msgs[i].meta_json);
         have_sys = sys.content != NULL;
         break;
       }
@@ -322,6 +367,7 @@ int cst_session_clear(cst_session_t *s, int keep_system) {
     write_line(s->fp, &sys);
   }
   free(sys.content);
+  free(sys.meta_json);
   pthread_mutex_unlock(&s->mu);
   return rc;
 }
@@ -339,6 +385,11 @@ int cst_session_rewrite(cst_session_t *s, const cst_message_t *msgs, int n) {
     copy[i].tool_calls_json =
         msgs[i].tool_calls_json ? strdup(msgs[i].tool_calls_json) : NULL;
     copy[i].meta_json = msgs[i].meta_json ? strdup(msgs[i].meta_json) : NULL;
+    copy[i].reasoning = msgs[i].reasoning ? strdup(msgs[i].reasoning) : NULL;
+    copy[i].attach = msgs[i].attach && msgs[i].nattach > 0
+                         ? cst_attachments_dup(msgs[i].attach, msgs[i].nattach)
+                         : NULL;
+    copy[i].nattach = copy[i].attach ? msgs[i].nattach : 0;
   }
   pthread_mutex_lock(&s->mu);
   free_all(s);
@@ -352,6 +403,8 @@ int cst_session_rewrite(cst_session_t *s, const cst_message_t *msgs, int n) {
     free(copy[i].content);
     free(copy[i].tool_calls_json);
     free(copy[i].meta_json);
+    free(copy[i].reasoning);
+    cst_attachments_free(copy[i].attach, copy[i].nattach);
   }
   free(copy);
   return rc;

src/tools/fs_tools.c

@@ -14,6 +14,7 @@
 
 #include <regex.h>
 
+#include "cst_attach.h"
 #include "cst_tools.h"
 #include "cst_util.h"
 #include "os_compat.h"
@@ -241,6 +242,47 @@ int cst_tool_read_file2(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
   return tool_take_buf(r, &b, 0);
 }
 
+/* --- view_image ---------------------------------------------------------- */
+
+/* Show an image to the model: the bytes are copied into the session's
+ * attachment store and travel as a multimodal content part of the result. */
+int cst_tool_view_image(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
+                        cst_tool_result_t *r) {
+  const char *path = tool_arg(c, "path");
+  if (!path || !path[0])
+    return tool_set_result(r, "error: missing path", 1);
+  const char *session = ctx->agent ? cst_agent_session_path(ctx->agent) : NULL;
+  if (!session || !session[0])
+    return tool_set_result(r, "error: no session to store the image in", 1);
+  char full[OS_PATH_MAX];
+  if (resolve(ctx, path, full, sizeof(full)) != 0)
+    return tool_set_resultf(r, 1,
+                            "error: path outside workspace or missing parent: "
+                            "%.200s",
+                            path);
+  if (is_dir(full))
+    return tool_set_resultf(r, 1, "error: %.200s is a directory", path);
+
+  char err[256];
+  cst_attachment_t *a = cst_attach_import_file(session, full, err, sizeof(err));
+  if (!a)
+    return tool_set_resultf(r, 1, "error: cannot show %.200s: %s", path, err);
+  snprintf(a->origin, sizeof(a->origin), "view_image");
+  const char *d = tool_arg(c, "detail");
+  if (d && (strcmp(d, "low") == 0 || strcmp(d, "high") == 0))
+    snprintf(a->detail, sizeof(a->detail), "%s", d);
+
+  char desc[128];
+  cst_attach_describe(a, desc, sizeof(desc));
+  cst_buf_t out = {0};
+  cst_buf_printf(&out, "view_image %.200s: %s\n(shown to you as an image)\n",
+                 path, desc);
+  int rc = tool_take_buf(r, &out, 0);
+  r->attach = a; /* one entry; freed as a block by cst_tool_result_free */
+  r->nattach = 1;
+  return rc;
+}
+
 /* --- edit_file ----------------------------------------------------------- */
 
 static size_t count_occ(const char *hay, size_t hn, const char *needle,

src/tools/registry.c

@@ -56,6 +56,15 @@ static const cst_tool_def_t TOOLS[] = {
       {"limit", I, 0, "maximum number of lines"},
       {"line_numbers", B, 0, "`N|` line prefixes (default true)"}},
      CST_TP_READ, 1, run_read_file, NULL, NO_DYN},
+    {"view_image",
+     "Show a local image to yourself: PNG, JPEG, GIF, WebP or BMP, checked by "
+     "content. The file is copied into the session store and comes back as an "
+     "image you can actually see (not as text). Use it for screenshots, "
+     "diagrams and UI checks; path resolves like read_file's.",
+     NULL,
+     {{"path", S, 1, "image file path relative to the workspace"},
+      {"detail", S, 0, "low or high (provider hint; default auto)"}},
+     CST_TP_READ, 0, cst_tool_view_image, NULL, NO_DYN},
     {"run_shell",
      "Run a non-interactive shell command in the workspace root for builds, "
      "tests, git and other CLIs (stdin is empty; long runs are killed). "
@@ -333,8 +342,8 @@ int cst_tool_active(const cst_agent_config_t *cfg, const cst_tool_def_t *t) {
     return 1;
   if (cfg->tool_profile == CST_TOOLS_MINIMAL && !t->minimal)
     return 0;
-  if ((cfg->plan_mode || cfg->read_only) &&
-      (t->perm == CST_TP_WRITE || t->perm == CST_TP_SHELL))
+  /* plan_mode is enforced when a call runs, so tools[] stays the same */
+  if (cfg->read_only && (t->perm == CST_TP_WRITE || t->perm == CST_TP_SHELL))
     return 0;
   if (cfg->depth > 0 && strcmp(t->name, "task") == 0)
     return 0;
@@ -413,16 +422,44 @@ static int is_minimal(const cst_agent_config_t *cfg) {
   return cfg && cfg->tool_profile == CST_TOOLS_MINIMAL;
 }
 
+static int is_external(const cst_tool_def_t *t) {
+  return t->owner && strncmp(t->owner, "builtin:", 8) != 0;
+}
+
+static int by_name(const void *x, const void *y) {
+  const cst_tool_def_t *a = *(const cst_tool_def_t *const *)x;
+  const cst_tool_def_t *b = *(const cst_tool_def_t *const *)y;
+  return strcmp(a->name, b->name);
+}
+
 void *cst_tools_schema_cfg(const cst_agent_config_t *cfg) {
   cJSON *arr = cJSON_CreateArray();
   if (!arr)
     return NULL;
   int legacy = is_minimal(cfg);
   int n = cst_tool_count();
+  /* Built-ins in registry order, then plugin/MCP tools by name: servers
+   * finish starting in any order, and tools[] is part of the cached prefix. */
+  const cst_tool_def_t **order = calloc((size_t)(n ? n : 1), sizeof(*order));
+  if (!order) {
+    cJSON_Delete(arr);
+    return NULL;
+  }
+  int nb = 0, no = 0;
   for (int i = 0; i < n; i++) {
     const cst_tool_def_t *t = cst_tool_at(i);
-    if (!t || !cst_tool_active(cfg, t))
-      continue;
+    if (t && cst_tool_active(cfg, t) && !is_external(t))
+      order[no++] = t;
+  }
+  nb = no;
+  for (int i = 0; i < n; i++) {
+    const cst_tool_def_t *t = cst_tool_at(i);
+    if (t && cst_tool_active(cfg, t) && is_external(t))
+      order[no++] = t;
+  }
+  qsort(order + nb, (size_t)(no - nb), sizeof(*order), by_name);
+  for (int i = 0; i < no; i++) {
+    const cst_tool_def_t *t = order[i];
     cJSON *tool = cJSON_CreateObject();
     cJSON_AddStringToObject(tool, "type", "function");
     cJSON *fn = cJSON_AddObjectToObject(tool, "function");
@@ -457,6 +494,7 @@ void *cst_tools_schema_cfg(const cst_agent_config_t *cfg) {
     }
     cJSON_AddItemToArray(arr, tool);
   }
+  free(order);
   return arr;
 }
 

src/tools/tools.c

@@ -10,6 +10,7 @@
 
 #include "cJSON.h"
 #include "cst_agent.h"
+#include "cst_attach.h"
 #include "cst_sandbox.h"
 #include "cst_util.h"
 #include "os_compat.h"
@@ -26,6 +27,9 @@ void cst_tool_result_free(cst_tool_result_t *r) {
   free(r->out);
   r->out = NULL;
   r->out_len = 0;
+  cst_attachments_free(r->attach, r->nattach);
+  r->attach = NULL;
+  r->nattach = 0;
 }
 
 void cst_tool_call_clear(ctl_tool_call_t *c) {

src/tools/tools_internal.h

@@ -48,6 +48,8 @@ int cst_tool_ask_user(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
                       cst_tool_result_t *r);
 int cst_tool_web_fetch(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
                        cst_tool_result_t *r);
+int cst_tool_view_image(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
+                        cst_tool_result_t *r);
 
 int cst_preview_write_file(const cst_tool_ctx_t *ctx,
                            const ctl_tool_call_t *c, char **out);

src/tui.c

@@ -4,10 +4,14 @@
 
 #include "cJSON.h"
 #include "cst_agent.h"
+#include "cst_attach.h"
+#include "cst_clipboard.h"
 #include "cst_keymap.h"
 #include "cst_ext.h"
 #include "cst_mcp.h"
+#include "cst_models.h"
 #include "cst_plugins.h"
+#include "cst_provider_switch.h"
 #include "cst_skills.h"
 #include "cst_subagent.h"
 #include "cst_textsel.h"
@@ -340,6 +344,7 @@ typedef struct {
   size_t cur; /* cursor byte offset into inbuf */
   int in_paste;
   int paste_cr; /* last pasted byte was CR (fold CRLF) */
+  size_t paste_at, paste_len0; /* cursor and length when the paste began */
   char status_msg[512];
   char title[128]; /* session title or first prompt, for the header */
   struct timespec ctrlc_at;
@@ -374,6 +379,7 @@ typedef struct {
   char *prompt_hist[PROMPT_HIST_CAP];
   int prompt_hist_n;
   int hist_browse;
+  char *hist_draft; /* the live input while browsing */
 
   /* Busy-turn FIFO */
   char *queue[QUEUE_CAP];
@@ -1981,6 +1987,12 @@ static int ctx_percent(const tui_t *t, long *used) {
   return win > 0 ? (int)(*used * 100 / win) : 0;
 }
 
+static const char *money_sym(const char *cur) {
+  if (g_ascii && strcmp(cur, "¥") == 0)
+    return "CNY ";
+  return cur;
+}
+
 static int approval_mode(const tui_t *t) {
   const cst_agent_config_t *cfg = cst_agent_config(t->agent);
   if (!cfg)
@@ -2019,8 +2031,20 @@ static void draw_status(tui_t *t) {
     int pct = ctx_percent(t, &used);
     char tok[32];
     fmt_tokens(used, tok, sizeof(tok));
-    snprintf(right, sizeof(right), "%s (%d%%)%s\033[97mctrl+p\033[39m commands",
-             tok, pct, dot_sep());
+    char usage[64] = "";
+    cst_usage_t u;
+    cst_agent_usage(t->agent, &u, NULL);
+    if (u.requests > 0 && u.prompt > 0) {
+      int n = snprintf(usage, sizeof(usage), "%shit %ld%%", dot_sep(),
+                       u.cached * 100 / u.prompt);
+      if (u.priced && n > 0 && (size_t)n < sizeof(usage))
+        snprintf(usage + n, sizeof(usage) - (size_t)n, "%s%s%s%.2f",
+                 dot_sep(), g_ascii ? "~" : "≈", money_sym(u.currency),
+                 u.cost);
+    }
+    snprintf(right, sizeof(right),
+             "%s (%d%%)%s%s\033[97mctrl+p\033[39m commands", tok, pct, usage,
+             dot_sep());
     rw = vis_cols(right);
     if (rw > w)
       rw = w;
@@ -2078,7 +2102,14 @@ static void draw_mode_line(tui_t *t, WINDOW *w, int y, int maxw) {
   x += draw_ansi_at(w, y, x, room - x + 2, cfg->provider, CP_BOX_MUTED, 0, 0);
   if (eff) {
     x += draw_ansi_at(w, y, x, room - x + 2, dot_sep(), CP_BOX_MUTED, 0, 0);
-    draw_ansi_at(w, y, x, room - x + 2, eff, CP_BOX_PRIMARY, 0, 0);
+    x += draw_ansi_at(w, y, x, room - x + 2, eff, CP_BOX_PRIMARY, 0, 0);
+  }
+  int npick = cst_agent_pending_count(t->agent);
+  if (npick > 0) {
+    char mark[32];
+    snprintf(mark, sizeof(mark), "%d image%s", npick, npick > 1 ? "s" : "");
+    x += draw_ansi_at(w, y, x, room - x + 2, dot_sep(), CP_BOX_MUTED, 0, 0);
+    draw_ansi_at(w, y, x, room - x + 2, mark, CP_BOX_PRIMARY, 0, 0);
   }
   if (rw)
     draw_ansi_at(w, y, maxw - rw - 2, rw, right, rpair, 0, 0);
@@ -2789,11 +2820,23 @@ static void reload_hist_from_session(tui_t *t) {
       else
         b->expanded = 0;
       t->last_tool_idx = t->hist.n - 1;
+    } else if (cst_message_is_note(m)) {
+      b->kind = BLK_SYSTEM;
+      const char *c = m->content ? m->content : "";
+      const char *nl = strchr(c, '\n');
+      block_set_body(b, c, nl ? (size_t)(nl - c) : strlen(c));
     } else if (m->role == CST_ROLE_USER) {
       b->kind = BLK_USER;
       block_set_title(b, "You");
-      block_set_body(b, m->content ? m->content : "",
-                     m->content ? strlen(m->content) : 0);
+      cst_buf_t ub = {0};
+      cst_buf_puts(&ub, m->content ? m->content : "");
+      for (int k = 0; k < m->nattach; k++) {
+        char d[128];
+        cst_attach_describe(&m->attach[k], d, sizeof(d));
+        cst_buf_printf(&ub, "\n[image %s · %s]", m->attach[k].name, d);
+      }
+      block_set_body(b, ub.buf ? ub.buf : "", ub.len);
+      cst_buf_free(&ub);
       b->expanded = 1;
     } else if (m->role == CST_ROLE_ASSISTANT) {
       b->kind = BLK_ASSISTANT;
@@ -3122,28 +3165,16 @@ static size_t word_right(const tui_t *t, size_t at) {
   return at;
 }
 
-/* Move to the previous/next logical line keeping the column (in chars).
- * Returns 0 when already on the first/last line. */
+static size_t input_hit(const tui_t *t, int want_row, int want_col);
+
+/* Move to the previous/next visual row (soft-wrapped or not) keeping the
+ * screen column. Returns 0 when already on the first/last row. */
 static int input_line_move(tui_t *t, int dir) {
-  size_t ls = line_start(t, t->cur);
-  int col = 0;
-  for (size_t i = ls; i < t->cur; i += next_len(t, i))
-    col++;
-  size_t target;
-  if (dir < 0) {
-    if (ls == 0)
-      return 0;
-    target = line_start(t, ls - 1);
-  } else {
-    size_t le = line_end(t, t->cur);
-    if (le >= t->in_len)
-      return 0;
-    target = le + 1;
-  }
-  size_t te = line_end(t, target);
-  while (col-- > 0 && target < te)
-    target += next_len(t, target);
-  t->cur = target;
+  int cr, cc;
+  int rows = input_layout(t, NULL, NULL, &cr, &cc);
+  if (cr + dir < 0 || cr + dir >= rows)
+    return 0;
+  t->cur = input_hit(t, cr + dir, cc);
   return 1;
 }
 
@@ -3821,7 +3852,7 @@ static int secret_input_run(tui_t *t, const char *title, const char *hint,
  * File-scope so a probe still running when the TUI exits writes nowhere
  * stale. */
 
-#define AM_MAX 64
+#define AM_MAX 512 /* routers list hundreds; the picker filters as you type */
 enum { AM_NONE = 0, AM_RUNNING, AM_OK, AM_FAILED, AM_AUTH };
 
 static pthread_mutex_t g_am_mu = PTHREAD_MUTEX_INITIALIZER;
@@ -3839,6 +3870,7 @@ typedef struct {
   char provider[32];
   char base[512];
   char key[512];
+  int have_cache; /* a cached list is showing: keep it if the fetch fails */
 } probe_arg_t;
 
 static void am_store(const char *provider, int r, char ids[][128],
@@ -3859,8 +3891,10 @@ static void *probe_thread(void *arg) {
   probe_arg_t *a = arg;
   static char ids[AM_MAX][128]; /* one probe runs per provider switch */
   char err[256];
-  int r = cst_llm_list_models(a->base, a->key, ids, AM_MAX, err, sizeof(err));
-  am_store(a->provider, r, ids, err);
+  int r = cst_ps_fetch(a->provider, a->base, a->key, ids, AM_MAX, err,
+                       sizeof(err));
+  if (r >= 0 || r == CST_MODELS_AUTH || !a->have_cache)
+    am_store(a->provider, r, ids, err);
   memset(a->key, 0, sizeof(a->key));
   free(a);
   pthread_mutex_lock(&g_am_mu);
@@ -3869,30 +3903,32 @@ static void *probe_thread(void *arg) {
   return NULL;
 }
 
-/* Base URL for a provider: the live config for the current one (it may be
- * overridden), else the preset. */
-static const char *provider_base(const tui_t *t, const char *provider) {
-  const cst_agent_config_t *cfg = cst_agent_config(t->agent);
-  if (cfg && strcmp(cfg->provider, provider) == 0)
-    return cfg->api_base;
-  const cst_provider_t *p = cst_provider_find(provider);
-  return p ? p->api_base : "";
-}
-
 static void start_probe(tui_t *t) {
   const cst_agent_config_t *cfg = cst_agent_config(t->agent);
   if (!cfg || !cfg->api_key[0] || g_am_threads > 0)
     return;
+  static char ids[AM_MAX][128];
+  int fresh = 0;
+  int nc = cst_ps_cached(cfg->provider, ids, AM_MAX, &fresh);
+  pthread_mutex_lock(&g_am_mu);
+  snprintf(g_am.provider, sizeof(g_am.provider), "%s", cfg->provider);
+  pthread_mutex_unlock(&g_am_mu);
+  if (nc > 0)
+    am_store(cfg->provider, nc, ids, "");
+  if (fresh)
+    return;
   probe_arg_t *a = calloc(1, sizeof(*a));
   if (!a)
     return;
   snprintf(a->provider, sizeof(a->provider), "%s", cfg->provider);
   snprintf(a->base, sizeof(a->base), "%s", cfg->api_base);
   snprintf(a->key, sizeof(a->key), "%s", cfg->api_key);
+  a->have_cache = nc > 0;
   pthread_mutex_lock(&g_am_mu);
-  snprintf(g_am.provider, sizeof(g_am.provider), "%s", cfg->provider);
-  g_am.state = AM_RUNNING;
-  g_am.n = 0;
+  if (nc <= 0) {
+    g_am.state = AM_RUNNING;
+    g_am.n = 0;
+  }
   g_am_threads++;
   pthread_mutex_unlock(&g_am_mu);
   pthread_t th;
@@ -3920,15 +3956,23 @@ static int am_models(const char *provider, char out[][128], int max) {
   return n;
 }
 
-/* After a probe: flag a model the API does not list. */
+/* After a probe: flag a model the API does not list; with no model yet
+ * (router presets) take the first one listed. */
 static void am_check_model(tui_t *t) {
-  const cst_agent_config_t *cfg = cst_agent_config(t->agent);
+  cst_agent_config_t *cfg = cst_agent_config_mut(t->agent);
   char msg[400] = "";
+  int picked = 0;
   pthread_mutex_lock(&g_am_mu);
   if (cfg && strcmp(g_am.provider, cfg->provider) == 0) {
     if (g_am.state == AM_AUTH) {
       snprintf(msg, sizeof(msg), "the %s API key was rejected — /key to "
                                  "replace it", cfg->provider);
+    } else if (g_am.state == AM_OK && g_am.n > 0 && !cfg->model[0]) {
+      snprintf(cfg->model, sizeof(cfg->model), "%s", g_am.ids[0]);
+      snprintf(msg, sizeof(msg), "model → %.127s (%d listed by %s) — /model "
+                                 "to change",
+               cfg->model, g_am.n, cfg->provider);
+      picked = 1;
     } else if (g_am.state == AM_OK && g_am.n > 0) {
       int found = 0;
       for (int i = 0; i < g_am.n && !found; i++)
@@ -3939,6 +3983,8 @@ static void am_check_model(tui_t *t) {
     }
   }
   pthread_mutex_unlock(&g_am_mu);
+  if (picked)
+    cst_settings_remember(cfg);
   if (msg[0])
     set_status(t, msg);
 }
@@ -3949,13 +3995,14 @@ static int obtain_key(tui_t *t, const char *provider, char *out, size_t n,
     return 0;
   char dir[1024] = "the config directory";
   os_config_dir(dir, sizeof(dir));
-  const char *base = provider_base(t, provider);
+  const char *base = cst_ps_base(cst_agent_config(t->agent), provider);
   char title[128], hint[1300];
   snprintf(title, sizeof(title), "API key for %s", provider);
   snprintf(hint, sizeof(hint), "%.200s · saved to %.900s/credentials (only you "
                                "can read it)",
            base, dir);
   char note[300] = "";
+  int flags;
   for (;;) {
     if (secret_input_run(t, title, hint, out, n) != 0)
       return -1;
@@ -3963,8 +4010,10 @@ static int obtain_key(tui_t *t, const char *provider, char *out, size_t n,
     draw_status(t);
     static char ids[AM_MAX][128];
     char err[256];
-    int r = cst_llm_list_models(base, out, ids, AM_MAX, err, sizeof(err));
-    if (r == CST_MODELS_AUTH) {
+    int r = -1;
+    flags = cst_ps_verify_save(provider, base, out, ids, AM_MAX, &r, err,
+                               sizeof(err));
+    if (flags == CST_MODELS_AUTH) {
       snprintf(hint, sizeof(hint), "%s rejected that key (%.200s) — paste "
                                    "another one",
                base, err);
@@ -3974,13 +4023,13 @@ static int obtain_key(tui_t *t, const char *provider, char *out, size_t n,
     snprintf(g_am.provider, sizeof(g_am.provider), "%s", provider);
     pthread_mutex_unlock(&g_am_mu);
     am_store(provider, r, ids, err);
-    if (r < 0)
+    if (flags & CST_PS_UNVERIFIED)
       snprintf(note, sizeof(note), "could not verify the key (%.200s); "
                                    "saved anyway",
                err);
     break;
   }
-  if (cst_creds_save(provider, out) != 0)
+  if (flags & CST_PS_UNSAVED)
     set_status(t, "warning: could not save the key; it is used for this run "
                   "only");
   else if (note[0])
@@ -4192,6 +4241,16 @@ static void cmd_delete(tui_t *t, char *arg, int *quit) {
   push_system_line(t, "(deleted session %s)", victim);
 }
 
+/* "name   1M · vision  (api)" for the /model picker. */
+static void model_label(const char *provider, const char *name, int api,
+                        char *out, size_t n) {
+  cst_model_info_t mi;
+  cst_model_info(provider, name, &mi);
+  char tag[40];
+  cst_model_info_label(&mi, tag, sizeof(tag));
+  snprintf(out, n, "%-40.72s %.32s%s", name, tag, api ? "  (api)" : "");
+}
+
 static void cmd_model(tui_t *t, char *arg, int *quit) {
   (void)quit;
   cst_agent_config_t *cfg = cst_agent_config_mut(t->agent);
@@ -4202,8 +4261,8 @@ static void cmd_model(tui_t *t, char *arg, int *quit) {
       set_status(t, "fetching the model list…");
       draw_status(t);
       char err[256];
-      na = cst_llm_list_models(cfg->api_base, cfg->api_key, names, AM_MAX, err,
-                               sizeof(err));
+      na = cst_ps_fetch(cfg->provider, cfg->api_base, cfg->api_key, names,
+                        AM_MAX, err, sizeof(err));
       pthread_mutex_lock(&g_am_mu);
       snprintf(g_am.provider, sizeof(g_am.provider), "%s", cfg->provider);
       pthread_mutex_unlock(&g_am_mu);
@@ -4216,7 +4275,7 @@ static void cmd_model(tui_t *t, char *arg, int *quit) {
     if (na < 0)
       na = 0;
     for (int i = 0; i < na; i++)
-      snprintf(labels[i], 128, "%.100s  (api)", names[i]);
+      model_label(cfg->provider, names[i], 1, labels[i], 128);
     char builtin[32][128];
     int nb = cst_models_list(cfg->model, builtin, 32);
     int n = na;
@@ -4227,7 +4286,7 @@ static void cmd_model(tui_t *t, char *arg, int *quit) {
       if (dup)
         continue;
       memcpy(names[n], builtin[i], 128);
-      memcpy(labels[n], builtin[i], 128);
+      model_label(cfg->provider, builtin[i], 0, labels[n], 128);
       n++;
     }
     int cur_idx = -1;
@@ -4242,8 +4301,13 @@ static void cmd_model(tui_t *t, char *arg, int *quit) {
     snprintf(cfg->model, sizeof(cfg->model), "%.127s", arg);
   }
   cst_settings_remember(cfg);
-  push_system_line(t, "(model → %s, context %ld tokens)", cfg->model,
-                   cst_model_context_tokens(cfg->model));
+  cst_model_info_t mi;
+  cst_model_info(cfg->provider, cfg->model, &mi);
+  push_system_line(t, "(model → %s, context %ld tokens%s)", cfg->model,
+                   mi.context,
+                   mi.vision == 1   ? ", takes images"
+                   : mi.vision == 0 ? ", text only"
+                                    : "");
 }
 
 static void cmd_key(tui_t *t, char *arg, int *quit) {
@@ -4310,15 +4374,18 @@ static void cmd_provider(tui_t *t, char *arg, int *quit) {
     }
   } else {
     int n = cst_provider_count();
-    char items[16][128];
+    char items[32][128];
     int cur_idx = 0;
-    for (int i = 0; i < n && i < 16; i++) {
+    for (int i = 0; i < n && i < 32; i++) {
       const cst_provider_t *q = cst_provider_at(i);
-      snprintf(items[i], 128, "%-9s %s  (%s)", q->name, q->api_base, q->model);
+      snprintf(items[i], 128, "%-11.24s %.48s  (%.24s%s)", q->name,
+               q->api_base, q->model[0] ? q->model : "models from API",
+               strcmp(cst_provider_source(q), "user") == 0 ? " · models.json"
+                                                           : "");
       if (strcmp(q->name, cfg->provider) == 0)
         cur_idx = i;
     }
-    int pick = picker_run(t, "Provider", items, n < 16 ? n : 16, cur_idx);
+    int pick = picker_run(t, "Provider", items, n < 32 ? n : 32, cur_idx);
     if (pick < 0)
       return;
     p = cst_provider_at(pick);
@@ -4328,15 +4395,8 @@ static void cmd_provider(tui_t *t, char *arg, int *quit) {
     push_system_line(t, "(provider unchanged: %s needs an API key)", p->name);
     return;
   }
-  cst_settings_t s;
-  cst_settings_load(&s);
-  const char *model = cst_settings_model(&s, p->name);
-  snprintf(cfg->provider, sizeof(cfg->provider), "%s", p->name);
-  snprintf(cfg->api_base, sizeof(cfg->api_base), "%s", p->api_base);
-  snprintf(cfg->model, sizeof(cfg->model), "%s", model ? model : p->model);
-  snprintf(cfg->api_key, sizeof(cfg->api_key), "%s", key);
+  cst_ps_apply_provider(cfg, p, key);
   memset(key, 0, sizeof(key));
-  cst_settings_remember(cfg);
   push_system_line(t, "(provider → %s · %s · model %s)", p->name, p->api_base,
                    cfg->model);
   if (am_models(p->name, NULL, 0) < 0)
@@ -4557,6 +4617,15 @@ static void cmd_status(tui_t *t, char *arg, int *quit) {
   push_system_line(t, "  provider   %s  %s", cfg->provider, cfg->api_base);
   push_system_line(t, "  model      %s  context %ld/%ld tokens (%ld%%)",
                    cfg->model, used, win, win ? used * 100 / win : 0);
+  {
+    cst_model_info_t mi;
+    cst_model_info(cfg->provider, cfg->model, &mi);
+    char tag[48];
+    cst_model_info_label(&mi, tag, sizeof(tag));
+    push_system_line(t, "  model info %s · from %s%s%s", tag, mi.source,
+                     cst_models_load_error()[0] ? " · " : "",
+                     cst_models_load_error());
+  }
   push_system_line(t, "  effort     %s%s", cfg->effort,
                    cst_effort_wire(cfg->provider, cfg->model, cfg->effort)
                        ? ""
@@ -4585,6 +4654,57 @@ static void cmd_status(tui_t *t, char *arg, int *quit) {
                    notes && notes[0] ? "AGENTS.md loaded" : "(no AGENTS.md)");
   push_system_line(t, "  undo       %d turn(s) can be undone",
                    cst_agent_undo_available(t->agent));
+  cst_usage_t u;
+  cst_agent_usage(t->agent, &u, NULL);
+  if (u.requests > 0 && u.prompt > 0)
+    push_system_line(t, "  cache      %ld%% of %ld prompt tokens hit  (/cost)",
+                     u.cached * 100 / u.prompt, u.prompt);
+}
+
+static void push_usage(tui_t *t, const char *label, const cst_usage_t *u) {
+  if (u->requests == 0) {
+    push_system_line(t, "  %-9s no requests yet", label);
+    return;
+  }
+  long hitp = u->prompt > 0 ? u->cached * 100 / u->prompt : 0;
+  push_system_line(t,
+                   "  %-9s %d request(s) · prompt %ld (hit %ld = %ld%%, miss "
+                   "%ld) · output %ld",
+                   label, u->requests, u->prompt, u->cached, hitp, u->miss,
+                   u->out);
+  if (u->write)
+    push_system_line(t, "  %-9s cache write %ld tokens", "", u->write);
+  if (u->priced)
+    push_system_line(t, "  %-9s %s %s%.4f", "", g_ascii ? "~" : "≈",
+                     money_sym(u->currency), u->cost);
+}
+
+static void cmd_cost(tui_t *t, char *arg, int *quit) {
+  (void)arg;
+  (void)quit;
+  const cst_agent_config_t *cfg = cst_agent_config(t->agent);
+  cst_usage_t s, last;
+  cst_agent_usage(t->agent, &s, &last);
+  push_system_line(t, "Token use and cost (%s):", cfg->model);
+  push_usage(t, "session", &s);
+  push_usage(t, "last turn", &last);
+  cst_price_t p;
+  if (cst_model_price(cfg->model, &p) != 0) {
+    push_system_line(t, "  price     unknown for this model; set "
+                        "CST_PRICE=miss,hit,out[,write[,currency]] (per 1M "
+                        "tokens)");
+    return;
+  }
+  const char *c = money_sym(p.currency);
+  push_system_line(t,
+                   "  price     per 1M tokens: miss %s%.2f · hit %s%.2f · "
+                   "output %s%.2f",
+                   c, p.miss, c, p.hit, c, p.out);
+  if (p.offpeak_half)
+    push_system_line(t,
+                     "  now       %s (off-peak is half price: outside "
+                     "Mon–Fri 9–12 / 14–18 Beijing time)",
+                     cst_price_is_peak(time(NULL)) ? "peak" : "off-peak");
 }
 
 static void cmd_todo(tui_t *t, char *arg, int *quit) {
@@ -4696,8 +4816,17 @@ static void cmd_export(tui_t *t, char *arg, int *quit) {
     if (msg_is_tool_result(m)) {
       fprintf(fp, "**Tool result** `%s`\n\n", m->tool_name);
       md_fence(fp, c, 4000);
+    } else if (cst_message_is_note(m)) {
+      fprintf(fp, "> %.*s\n\n", (int)strcspn(c, "\n"), c);
     } else if (m->role == CST_ROLE_USER) {
       fprintf(fp, "## User\n\n%s\n\n", c);
+      for (int k = 0; k < m->nattach; k++) {
+        char d[128];
+        cst_attach_describe(&m->attach[k], d, sizeof(d));
+        fprintf(fp, "- image `%s` (%s)\n", m->attach[k].name, d);
+      }
+      if (m->nattach)
+        fputc('\n', fp);
     } else {
       fprintf(fp, "## Assistant\n\n%s\n\n", c);
       if (m->tool_calls_json && m->tool_calls_json[0]) {
@@ -4711,6 +4840,116 @@ static void cmd_export(tui_t *t, char *arg, int *quit) {
   push_system_line(t, "(exported to %s)", path);
 }
 
+/* The newest `added` picks, and a warning when the model would not see them. */
+static void report_attached(tui_t *t, int added) {
+  int n = cst_agent_pending_count(t->agent);
+  for (int i = n - added; i < n; i++) {
+    char line[256];
+    if (i >= 0 &&
+        cst_agent_pending_describe(t->agent, i, line, sizeof(line)) == 0)
+      push_system_line(t, "Attached %s — it goes with your next message.",
+                       line);
+  }
+  if (added > 0 && cst_agent_sees_images(t->agent) == 0)
+    push_system_line(t, "Note: %s does not take images; they are sent as a "
+                        "text note until you /model to one that does.",
+                     cst_agent_config(t->agent)->model);
+}
+
+/* /attach: stage images for the next user message. The bytes are copied into
+ * the session's attachment directory now, so a picture picked from /tmp keeps
+ * working after the file is gone. */
+static void cmd_attach(tui_t *t, char *arg, int *quit) {
+  (void)quit;
+  int n = cst_agent_pending_count(t->agent);
+  if (!arg || !arg[0] || strcmp(arg, "list") == 0) {
+    if (n == 0) {
+      push_system_line(t, "No images picked. Usage: /attach <path>");
+      return;
+    }
+    push_system_line(t, "%d image%s with the next message (sent once):", n,
+                     n > 1 ? "s" : "");
+    for (int i = 0; i < n; i++) {
+      char line[256];
+      if (cst_agent_pending_describe(t->agent, i, line, sizeof(line)) == 0)
+        push_system_line(t, "  %d. %s", i + 1, line);
+    }
+    push_system_line(t, "(/attach clear drops them)");
+    return;
+  }
+  if (strcmp(arg, "clear") == 0 || strcmp(arg, "none") == 0) {
+    cst_agent_pending_clear(t->agent);
+    push_system_line(t, "Dropped the picked images.");
+    return;
+  }
+  char err[256];
+  if (strcmp(arg, "paste") == 0) {
+    char *img = NULL;
+    size_t len = 0;
+    if (cst_clipboard_image(&img, &len, err, sizeof(err)) != 0) {
+      push_system_line(t, "Error: %s", err);
+      return;
+    }
+    char mime[32], name[32];
+    const char *ext = cst_attach_sniff(img, len, mime, sizeof(mime)) == 0 &&
+                              strchr(mime, '/')
+                          ? strchr(mime, '/') + 1
+                          : "png";
+    snprintf(name, sizeof(name), "clipboard.%s", ext);
+    int rc = cst_agent_attach_bytes(t->agent, name, img, len, err, sizeof(err));
+    free(img);
+    if (rc != 0) {
+      push_system_line(t, "Error: %s", err);
+      return;
+    }
+    report_attached(t, 1);
+    return;
+  }
+  if (cst_agent_attach_file(t->agent, arg, err, sizeof(err)) != 0) {
+    push_system_line(t, "Error: %s", err);
+    return;
+  }
+  report_attached(t, 1);
+}
+
+static int file_is_image(const char *path) {
+  FILE *f = fopen(path, "rb");
+  if (!f)
+    return 0;
+  unsigned char head[16];
+  size_t got = fread(head, 1, sizeof(head), f);
+  fclose(f);
+  char mime[32];
+  return cst_attach_sniff(head, got, mime, sizeof(mime)) == 0;
+}
+
+/* A paste that is nothing but image file paths (a file dropped on the
+ * terminal) attaches those files instead of typing the paths. */
+static void paste_image_paths(tui_t *t) {
+  size_t from = t->paste_at, to = t->cur;
+  if (to <= from || to - from != t->in_len - t->paste_len0 ||
+      to - from > CST_PASTE_MAX_PATHS * CST_PASTE_PATH_MAX)
+    return;
+  static char paths[CST_PASTE_MAX_PATHS][CST_PASTE_PATH_MAX];
+  int n = cst_paste_paths(t->inbuf + from, to - from, paths,
+                          CST_PASTE_MAX_PATHS);
+  if (n <= 0)
+    return;
+  for (int i = 0; i < n; i++)
+    if (!file_is_image(paths[i]))
+      return;
+  input_erase(t, from, to);
+  int added = 0;
+  for (int i = 0; i < n; i++) {
+    char err[256];
+    if (cst_agent_attach_file(t->agent, paths[i], err, sizeof(err)) == 0)
+      added++;
+    else
+      push_system_line(t, "Error: %s", err);
+  }
+  report_attached(t, added);
+}
+
 #ifdef _WIN32
 #define COPY_VIA "clipboard"
 #else
@@ -5004,7 +5243,7 @@ static void show_subagent(tui_t *t, const char *pid,
   const char *final = NULL;
   for (int i = 0; i < n; i++) {
     const cst_message_t *m = cst_session_get(s, i);
-    if (!m->content)
+    if (!m->content || cst_message_is_note(m))
       continue;
     if (m->role == CST_ROLE_USER && !m->tool_call_id[0]) {
       push_system_line(t, "  prompt: %.300s", m->content);
@@ -5077,6 +5316,151 @@ static void cmd_quit(tui_t *t, char *arg, int *quit) {
   *quit = 1;
 }
 
+/* /web: the WebUI is a second front end for the same engine and is designed to
+ * run as its own process, so this starts one on the same workspace and leaves
+ * the TUI holding the terminal. The child gets a fresh session: two writers on
+ * one session file is the one thing that would corrupt it. */
+#ifndef _WIN32
+#include <fcntl.h>
+#include <sys/wait.h> /* waitpid: collect the WebUI started by the last /web */
+#endif
+#ifndef CST_WEBUI_DEFAULT_PORT
+#define CST_WEBUI_DEFAULT_PORT 8787 /* keep in sync with include/cst_webui.h */
+#endif
+static void cmd_web(tui_t *t, char *arg, int *quit) {
+  (void)arg;
+  (void)quit;
+#ifdef _WIN32
+  push_system_line(t, "open another terminal and run: cst-agent --web");
+#else
+  static pid_t spawned = 0;
+  if (spawned > 0) {          /* collect the one we started last time */
+    waitpid(spawned, NULL, WNOHANG);
+    spawned = 0;
+  }
+  char dir[4096], exe[4096 + 16];
+  if (os_exe_dir(dir, sizeof(dir)) != 0) {
+    push_system_line(t, "cannot locate this binary: run cst-agent --web yourself");
+    return;
+  }
+  snprintf(exe, sizeof(exe), "%s/cst-agent", dir);
+  const cst_agent_config_t *cfg = cst_agent_config(t->agent);
+  const char *ws = (cfg && cfg->workspace_root[0]) ? cfg->workspace_root : ".";
+  char logf[4096 + 32];
+  snprintf(logf, sizeof(logf), "%s/.agent", ws);
+  os_mkdir_p(logf, 0755);
+  snprintf(logf, sizeof(logf), "%s/.agent/webui.log", ws);
+  /* The WebUI talks to what this session talks to (-b, -m, a /provider
+   * switch...). The key goes through the environment, not argv (ps). */
+  const char *argv[20];
+  int na = 0;
+  argv[na++] = "cst-agent";
+  argv[na++] = "--web";
+  argv[na++] = "--workspace";
+  argv[na++] = ws;
+  argv[na++] = "--new";
+  if (cfg && cfg->provider[0])
+    argv[na++] = "--provider", argv[na++] = cfg->provider;
+  if (cfg && cfg->model[0])
+    argv[na++] = "--model", argv[na++] = cfg->model;
+  if (cfg && cfg->api_base[0])
+    argv[na++] = "--api-base", argv[na++] = cfg->api_base;
+  if (cfg && cfg->effort[0])
+    argv[na++] = "--effort", argv[na++] = cfg->effort;
+  if (cfg)
+    argv[na++] = "--approval", argv[na++] = cst_approval_name(cfg->approval);
+  argv[na] = NULL;
+  size_t nenv = 0;
+  while (environ[nenv])
+    nenv++;
+  char **envp = calloc(nenv + 2, sizeof(char *));
+  char keyvar[600] = "";
+  if (!envp) {
+    push_system_line(t, "out of memory");
+    return;
+  }
+  size_t ne = 0;
+  for (size_t i = 0; i < nenv; i++)
+    if (strncmp(environ[i], "CST_API_KEY=", 12) != 0)
+      envp[ne++] = environ[i];
+  if (cfg && cfg->api_key[0]) {
+    snprintf(keyvar, sizeof(keyvar), "CST_API_KEY=%s", cfg->api_key);
+    envp[ne++] = keyvar;
+  }
+  envp[ne] = NULL;
+  pid_t pid = fork();
+  if (pid < 0) {
+    free(envp);
+    push_system_line(t, "cannot start a second process");
+    return;
+  }
+  if (pid == 0) {
+    setsid();
+    /* never inherit the TUI's terminal: its output would land on our screen */
+    int in = open("/dev/null", O_RDONLY);
+    if (in >= 0 && in != STDIN_FILENO) {
+      dup2(in, STDIN_FILENO);
+      close(in);
+    }
+    int fd = open(logf, O_WRONLY | O_CREAT | O_TRUNC, 0600);
+    if (fd < 0)
+      fd = open("/dev/null", O_WRONLY);
+    if (fd >= 0) {
+      dup2(fd, STDOUT_FILENO);
+      dup2(fd, STDERR_FILENO);
+      if (fd > 2)
+        close(fd);
+    }
+    execve(exe, (char *const *)argv, envp);
+    _exit(127);
+  }
+  free(envp);
+  spawned = pid;
+  /* Wait (2 s at most) for the URL it prints once it listens: the port may
+   * come from CST_WEB_PORT, or it may not start at all. */
+  char url[512] = "";
+  int died = 0;
+  for (int i = 0; i < 40 && !url[0] && !died; i++) {
+    usleep(50000);
+    FILE *fp = fopen(logf, "r");
+    char line[512];
+    while (fp && fgets(line, sizeof(line), fp)) {
+      if (strncmp(line, "webui: http", 11) == 0) {
+        line[strcspn(line, "\r\n")] = 0;
+        snprintf(url, sizeof(url), "%s", line + 7);
+        break;
+      }
+    }
+    if (fp)
+      fclose(fp);
+    if (!url[0] && waitpid(pid, NULL, WNOHANG) == pid) {
+      died = 1;
+      spawned = 0;
+    }
+  }
+  /* its --new made the WebUI's session CURRENT; a plain `cst-agent` later
+   * should still resume this one */
+  char sid[128] = "";
+  cst_agent_session_id(t->agent, sid, sizeof(sid));
+  if (sid[0])
+    cst_agent_store_set_current(ws, sid);
+  char msg[4200];
+  if (died)
+    snprintf(msg, sizeof(msg), "the WebUI did not start (port busy?): see %s",
+             logf);
+  else if (url[0])
+    snprintf(msg, sizeof(msg), "WebUI started in the background: %s (new session)",
+             url);
+  else
+    snprintf(msg, sizeof(msg), "WebUI starting in the background "
+                               "(http://127.0.0.1:%d/ unless CST_WEB_PORT says "
+                               "otherwise)", CST_WEBUI_DEFAULT_PORT);
+  push_system_line(t, msg);
+  snprintf(msg, sizeof(msg), "its log: %s", logf);
+  push_system_line(t, msg);
+#endif
+}
+
 static const slash_cmd_t SLASH[] = {
     {"help", "?", "", "list commands and keys", 1, cmd_help},
     {"new", "clear", "", "start a new session", 0, cmd_new},
@@ -5107,6 +5491,8 @@ static const slash_cmd_t SLASH[] = {
      cmd_mouse},
     {"max-steps", "", "[N]", "tool steps allowed per turn", 1, cmd_max_steps},
     {"status", "", "", "session, model, context and settings", 1, cmd_status},
+    {"cost", "usage", "", "tokens, cache hit rate and estimated cost", 1,
+     cmd_cost},
     {"todo", "tasks", "", "show the agent's task list", 1, cmd_todo},
     {"undo", "", "", "revert file changes of the last turn", 0, cmd_undo},
     {"retry", "", "", "drop the last reply and ask again", 0, cmd_retry},
@@ -5116,6 +5502,9 @@ static const slash_cmd_t SLASH[] = {
     {"export", "", "[file]", "write the transcript as Markdown", 1,
      cmd_export},
     {"copy", "", "", "copy the last reply (OSC 52)", 1, cmd_copy},
+    {"attach", "image", "[path|paste|clear]",
+     "send image(s) with the next message",
+     1, cmd_attach},
     {"init", "", "", "have the agent write AGENTS.md", 0, cmd_init},
     {"details", "", "", "expand/collapse all tool output", 1, cmd_details},
     {"thinking", "", "[on|off]", "show Thought blocks expanded or collapsed",
@@ -5130,6 +5519,8 @@ static const slash_cmd_t SLASH[] = {
      cmd_agents},
     {"skill", "", "<name> [task]", "run a task with a skill loaded", 0,
      cmd_skill},
+    {"web", "", "", "start the WebUI in the background (127.0.0.1:8787)", 1,
+     cmd_web},
     {"quit", "q exit", "", "quit", 1, cmd_quit},
 };
 
@@ -5409,11 +5800,25 @@ static void request_cancel_ui(tui_t *t) {
 
 static int begin_turn(tui_t *t, char *prompt) {
   prompt_hist_push(t, prompt);
+  if (!cst_agent_config(t->agent)->model[0]) {
+    set_status(t, "no model selected yet — /model to pick one (↑ recalls "
+                  "your message)");
+    free(prompt);
+    return -1;
+  }
   block_t *ub = blocks_push(&t->hist);
   if (ub) {
     ub->kind = BLK_USER;
     block_set_title(ub, "You");
-    block_set_body(ub, prompt, strlen(prompt));
+    cst_buf_t body = {0};
+    cst_buf_puts(&body, prompt);
+    for (int k = 0; k < cst_agent_pending_count(t->agent); k++) {
+      char d[128];
+      if (cst_agent_pending_describe(t->agent, k, d, sizeof(d)) == 0)
+        cst_buf_printf(&body, "\n[image %s]", d);
+    }
+    block_set_body(ub, body.buf ? body.buf : "", body.len);
+    cst_buf_free(&body);
     ub->expanded = 1;
   }
   t->think_idx = -1;
@@ -5537,7 +5942,7 @@ static int submit_input(tui_t *t, int busy) {
 static size_t input_hit(const tui_t *t, int want_row, int want_col) {
   int row = 0, col = IN_COL;
   int right = (t->in_w > 0 ? t->in_w : t->cols) - 2;
-  size_t i = 0, best = t->in_len;
+  size_t i = 0, best = t->in_len, last = 0;
   while (i < t->in_len) {
     if (row == want_row && col >= want_col)
       return i;
@@ -5556,12 +5961,14 @@ static size_t input_hit(const tui_t *t, int want_row, int want_col) {
     utf8_decode(t->inbuf + i, t->in_len - i, &wc, &eaten);
     int cw = utf8_width(wc == L'\t' ? L' ' : wc);
     if (col + cw > right && col > IN_COL) {
+      /* offset i would be drawn at the start of the next row */
       if (row == want_row)
-        return i;
+        return last;
       row++;
       col = IN_COL;
     }
     best = i + eaten;
+    last = i;
     col += cw;
     i += eaten;
   }
@@ -6078,29 +6485,65 @@ static int g_k_alt_up, g_k_alt_down, g_k_ctrl_home, g_k_ctrl_end,
     g_k_ctrl_up, g_k_ctrl_down, g_k_ctrl_left, g_k_ctrl_right, g_k_alt_left,
     g_k_alt_right, g_k_ctrl_dc, g_k_alt_dc;
 
-static int ext_key(const char *cap) {
+/* The terminfo key, else the xterm sequence bound to our own code `own`. */
+static int ext_key(const char *cap, const char *xterm, int own) {
   char *s = tigetstr(cap);
-  if (!s || s == (char *)-1)
-    return 0;
-  int k = key_defined(s);
-  return k > 0 ? k : 0;
+  int k = s && s != (char *)-1 ? key_defined(s) : 0;
+  if (k > 0)
+    return k;
+#ifndef _WIN32
+  k = key_defined(xterm);
+  if (k > 0)
+    return k;
+  if (k == 0 && define_key(xterm, own) == OK)
+    return own;
+#else
+  (void)xterm, (void)own;
+#endif
+  return 0;
+}
+#endif
+
+#if defined(NCURSES_VERSION) && !defined(_WIN32)
+/* Terminfo lists one form per key, but terminals disagree: cursor keys come
+ * as CSI or SS3 whatever DECCKM says (tmux, mosh, a wrong TERM), Home/End as
+ * CSI H, SS3 H or CSI 1~/7~. Unknown forms would be read as Esc + text. */
+static void vt_keys_init(void) {
+  static const struct {
+    const char *seq;
+    int key;
+  } K[] = {
+      {"\033[A", KEY_UP},     {"\033OA", KEY_UP},     {"\033[B", KEY_DOWN},
+      {"\033OB", KEY_DOWN},   {"\033[C", KEY_RIGHT},  {"\033OC", KEY_RIGHT},
+      {"\033[D", KEY_LEFT},   {"\033OD", KEY_LEFT},   {"\033[H", KEY_HOME},
+      {"\033OH", KEY_HOME},   {"\033[1~", KEY_HOME},  {"\033[7~", KEY_HOME},
+      {"\033[F", KEY_END},    {"\033OF", KEY_END},    {"\033[4~", KEY_END},
+      {"\033[8~", KEY_END},   {"\033[2~", KEY_IC},    {"\033[3~", KEY_DC},
+      {"\033[5~", KEY_PPAGE}, {"\033[6~", KEY_NPAGE}, {"\033[Z", KEY_BTAB},
+      {"\033[1;2A", KEY_SR},  {"\033[1;2B", KEY_SF},  {"\033[1;2C", KEY_SRIGHT},
+      {"\033[1;2D", KEY_SLEFT},
+  };
+  for (size_t i = 0; i < sizeof(K) / sizeof(K[0]); i++)
+    if (key_defined(K[i].seq) == 0)
+      define_key(K[i].seq, K[i].key);
 }
 #endif
 
 static void keys_init(void) {
 #ifdef NCURSES_VERSION
-  g_k_alt_up = ext_key("kUP3");
-  g_k_alt_down = ext_key("kDN3");
-  g_k_ctrl_home = ext_key("kHOM5");
-  g_k_ctrl_end = ext_key("kEND5");
-  g_k_ctrl_up = ext_key("kUP5");
-  g_k_ctrl_down = ext_key("kDN5");
-  g_k_ctrl_left = ext_key("kLFT5");
-  g_k_ctrl_right = ext_key("kRIT5");
-  g_k_alt_left = ext_key("kLFT3");
-  g_k_alt_right = ext_key("kRIT3");
-  g_k_ctrl_dc = ext_key("kDC5");
-  g_k_alt_dc = ext_key("kDC3");
+  int own = KEY_OWN_BASE + 4; /* up to KEY_KITTY_BASE - 1 */
+  g_k_alt_up = ext_key("kUP3", "\033[1;3A", own++);
+  g_k_alt_down = ext_key("kDN3", "\033[1;3B", own++);
+  g_k_ctrl_home = ext_key("kHOM5", "\033[1;5H", own++);
+  g_k_ctrl_end = ext_key("kEND5", "\033[1;5F", own++);
+  g_k_ctrl_up = ext_key("kUP5", "\033[1;5A", own++);
+  g_k_ctrl_down = ext_key("kDN5", "\033[1;5B", own++);
+  g_k_ctrl_left = ext_key("kLFT5", "\033[1;5D", own++);
+  g_k_ctrl_right = ext_key("kRIT5", "\033[1;5C", own++);
+  g_k_alt_left = ext_key("kLFT3", "\033[1;3D", own++);
+  g_k_alt_right = ext_key("kRIT3", "\033[1;3C", own++);
+  g_k_ctrl_dc = ext_key("kDC5", "\033[3;5~", own++);
+  g_k_alt_dc = ext_key("kDC3", "\033[3;3~", own++);
 #endif
 }
 
@@ -6313,6 +6756,7 @@ static void tui_free(tui_t *t) {
   queue_free_all(t);
   for (int i = 0; i < t->prompt_hist_n; i++)
     free(t->prompt_hist[i]);
+  free(t->hist_draft);
   for (int i = 0; i < t->nfiles; i++)
     free(t->files[i]);
   free(t->files);
@@ -6403,6 +6847,7 @@ int cst_tui_run(cst_agent_t *agent) {
   /* the Windows console driver reads key events, not VT sequences */
   define_key("\033[200~", KEY_PASTE_BEGIN);
   define_key("\033[201~", KEY_PASTE_END);
+  vt_keys_init();
   printf("\033[?2004h");
   fflush(stdout);
   kitty_init();
@@ -6629,10 +7074,13 @@ int cst_tui_run(cst_agent_t *agent) {
       if (wch == KEY_PASTE_BEGIN) {
         t.in_paste = 1;
         t.paste_cr = 0;
+        t.paste_at = t.cur;
+        t.paste_len0 = t.in_len;
         continue;
       }
       if (wch == KEY_PASTE_END) {
         t.in_paste = 0;
+        paste_image_paths(&t);
         input_changed(&t);
         after_edit(&t);
         continue;
@@ -6712,15 +7160,22 @@ int cst_tui_run(cst_agent_t *agent) {
           if (t.prompt_hist_n <= 0)
             continue;
           int idx = t.hist_browse;
+          if (idx < 0) {
+            free(t.hist_draft);
+            t.hist_draft = strdup(t.inbuf);
+          }
           idx = idx < 0 ? t.prompt_hist_n - 1 : (idx > 0 ? idx - 1 : 0);
           hist_load_into_input(&t, idx);
         } else {
           if (t.hist_browse < 0)
             continue;
-          if (t.hist_browse + 1 >= t.prompt_hist_n)
-            input_clear(&t);
-          else
+          if (t.hist_browse + 1 >= t.prompt_hist_n) {
+            input_set(&t, t.hist_draft);
+            free(t.hist_draft);
+            t.hist_draft = NULL;
+          } else {
             hist_load_into_input(&t, t.hist_browse + 1);
+          }
         }
         after_edit(&t);
         continue;

src/util.c

@@ -99,6 +99,26 @@ size_t cst_utf8_floor(const char *s, size_t n) {
   return i - 1; /* sequence incomplete: cut before lead byte */
 }
 
+char *cst_utf8_hold_feed(cst_utf8_hold_t *h, const char *s, size_t n,
+                         size_t *out_len) {
+  size_t have = h->n;
+  char *all = malloc(have + n + 1);
+  if (!all)
+    return NULL;
+  memcpy(all, h->b, have);
+  if (n)
+    memcpy(all + have, s, n);
+  size_t len = have + n;
+  size_t cut = cst_utf8_floor(all, len);
+  if (len - cut > sizeof(h->b))
+    cut = len;
+  h->n = len - cut;
+  memcpy(h->b, all + cut, h->n);
+  all[cut] = 0;
+  *out_len = cut;
+  return all;
+}
+
 static size_t utf8_seq_ok(const unsigned char *p, size_t left) {
   unsigned char c = p[0];
   size_t need;

src/web_md.c

@@ -0,0 +1,329 @@
+#ifndef _DEFAULT_SOURCE
+#define _DEFAULT_SOURCE
+#endif
+
+#include "cst_web_md.h"
+
+#include "cst_util.h"
+#include "sashidown.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+struct cst_web_md {
+  sashidown_stream_t *st;
+  cst_web_md_emit_fn emit;
+  void *ud;
+  cst_buf_t in;    /* HTML from sashidown, waiting for a complete tag */
+  int failed;
+};
+
+/* --- sanitizer ------------------------------------------------------------ */
+
+static const char *ALLOWED_TAGS[] = {
+    "p",      "br",     "hr",     "h1",     "h2",      "h3",     "h4",
+    "h5",     "h6",     "strong", "em",     "b",       "i",      "u",
+    "s",      "del",    "code",   "pre",    "blockquote", "ul",  "ol",
+    "li",     "table",  "thead",  "tbody",  "tr",      "th",     "td",
+    "a",      "img",    "span",   "div",    NULL};
+
+static int tag_allowed(const char *name, size_t n) {
+  for (int i = 0; ALLOWED_TAGS[i]; i++) {
+    if (strlen(ALLOWED_TAGS[i]) == n && strncmp(name, ALLOWED_TAGS[i], n) == 0)
+      return 1;
+  }
+  return 0;
+}
+
+/* A URL we are willing to put in href: http(s), mailto, or a same-site
+ * path. Anything else (javascript:, data:, file:, //evil) is dropped. */
+static int href_ok(const char *v, size_t n) {
+  if (n == 0)
+    return 0;
+  if (!strncmp(v, "http://", 7) || !strncmp(v, "https://", 8) ||
+      !strncmp(v, "mailto:", 7))
+    return 1;
+  if (v[0] == '/' && !(n > 1 && (v[1] == '/' || v[1] == '\\')))
+    return 1;
+  if (v[0] == '#')
+    return 1;
+  return 0;
+}
+
+static int src_ok(const char *v, size_t n) {
+  if (n > 11 && !strncmp(v, "data:image/", 11))
+    return 1;
+  if (n > 12 && !strncmp(v, "/api/attach/", 12))
+    return 1;
+  return 0;
+}
+
+static void attr_append(cst_buf_t *b, const char *name, size_t nlen,
+                        const char *val, size_t vlen) {
+  cst_buf_puts(b, " ");
+  cst_buf_append(b, name, nlen);
+  cst_buf_puts(b, "=\"");
+  /* a single-quoted or bare value may hold '"': it must not end ours */
+  for (size_t i = 0; i < vlen; i++) {
+    if (val[i] == '"')
+      cst_buf_puts(b, "&quot;");
+    else if (val[i] == '<')
+      cst_buf_puts(b, "&lt;");
+    else if (val[i] == '>')
+      cst_buf_puts(b, "&gt;");
+    else
+      cst_buf_append(b, val + i, 1);
+  }
+  cst_buf_puts(b, "\"");
+}
+
+/* Rewrite one tag (open, close or self-closing) into out; may emit nothing
+ * when the tag is not allowed. Returns 0, or -1 on OOM. */
+static int sanitize_tag(const char *tag, size_t len, cst_buf_t *out) {
+  /* <name ...> or </name> or <!-- ... --> */
+  size_t i = 0;
+  int closing = 0;
+  if (len < 3 || tag[0] != '<')
+    return 0;
+  i = 1;
+  if (i < len && tag[i] == '/') {
+    closing = 1;
+    i++;
+  }
+  size_t name_start = i;
+  while (i < len && ((tag[i] >= 'a' && tag[i] <= 'z') ||
+                     (tag[i] >= 'A' && tag[i] <= 'Z') ||
+                     (tag[i] >= '0' && tag[i] <= '9')))
+    i++;
+  size_t name_len = i - name_start;
+  if (name_len == 0 || !tag_allowed(tag + name_start, name_len))
+    return 0; /* comments, <script>, <iframe>: dropped entirely */
+  int is_img = name_len == 3 && strncmp(tag + name_start, "img", 3) == 0;
+  int is_a = name_len == 1 && tag[name_start] == 'a';
+  int self_closing = len > 2 && tag[len - 2] == '/';
+  size_t start = out->len;
+  cst_buf_puts(out, "<");
+  if (closing)
+    cst_buf_puts(out, "/");
+  cst_buf_append(out, tag + name_start, name_len);
+  if (!closing) {
+    /* copy the allowed attributes */
+    int keep_target = 0; /* a link is only useful with a usable href */
+    size_t p = name_start + name_len;
+    while (p < len && tag[p] != '>' && !(tag[p] == '/' && p + 1 < len &&
+                                         tag[p + 1] == '>')) {
+      while (p < len && (tag[p] == ' ' || tag[p] == '\t' || tag[p] == '\n'))
+        p++;
+      size_t an = p;
+      while (p < len && tag[p] != '=' && tag[p] != ' ' && tag[p] != '\t' &&
+             tag[p] != '\n' && tag[p] != '>' && tag[p] != '/')
+        p++;
+      size_t an_len = p - an;
+      if (an_len == 0) {
+        p++;
+        continue;
+      }
+      const char *aval = "";
+      size_t av_len = 0;
+      if (p < len && tag[p] == '=') {
+        p++;
+        char quote = 0;
+        if (p < len && (tag[p] == '"' || tag[p] == '\''))
+          quote = tag[p++];
+        size_t as = p;
+        while (p < len &&
+               (quote ? tag[p] != quote : (tag[p] != ' ' && tag[p] != '>')))
+          p++;
+        aval = tag + as;
+        av_len = p - as;
+        if (quote && p < len)
+          p++; /* closing quote */
+      }
+      int keep = 0;
+      if (is_a && an_len == 4 && strncmp(tag + an, "href", 4) == 0) {
+        keep = href_ok(aval, av_len);
+        keep_target = keep;
+      } else if (is_img && an_len == 3 && strncmp(tag + an, "src", 3) == 0) {
+        keep = src_ok(aval, av_len);
+        keep_target = keep;
+      } else if (is_img && an_len == 3 && strncmp(tag + an, "alt", 3) == 0)
+        keep = 1;
+      else if (an_len == 5 && strncmp(tag + an, "class", 5) == 0 &&
+               av_len > 9 && !strncmp(aval, "language-", 9))
+        keep = 1;
+      if (keep)
+        attr_append(out, tag + an, an_len, aval, av_len);
+    }
+    if (is_a && keep_target) {
+      cst_buf_puts(out, " target=\"_blank\" rel=\"noopener noreferrer\"");
+    }
+    if ((is_a && !keep_target) || (is_img && !keep_target)) {
+      /* a link with an unusable href, or an image from nowhere: drop the
+       * whole tag and keep only its text */
+      out->len = start;
+      if (out->buf)
+        out->buf[start] = 0;
+      return 0;
+    }
+    cst_buf_puts(out, self_closing ? " /" : "");
+  }
+  cst_buf_puts(out, ">");
+  return 0;
+}
+
+/* Emit the text before every '<' and every tag through the sanitizer. */
+static void scan_chunk(cst_web_md_t *s, int final) {
+  if (!s->emit || s->failed)
+    return;
+  size_t i = 0, emitted = 0;
+  while (i < s->in.len) {
+    if (s->in.buf[i] != '<') {
+      i++;
+      continue;
+    }
+    size_t close = i;
+    while (close < s->in.len && s->in.buf[close] != '>')
+      close++;
+    if (close >= s->in.len && !final)
+      break; /* the tag may still be growing: keep it buffered */
+    if (i > emitted && s->emit(s->in.buf + emitted, i - emitted, s->ud) != 0)
+      s->failed = 1;
+    size_t tag_len = close >= s->in.len ? s->in.len - i : close - i + 1;
+    cst_buf_t tag = {0};
+    if (sanitize_tag(s->in.buf + i, tag_len, &tag) != 0) {
+      cst_buf_free(&tag);
+      s->failed = 1;
+      return;
+    }
+    if (tag.len && s->emit(tag.buf, tag.len, s->ud) != 0)
+      s->failed = 1;
+    cst_buf_free(&tag);
+    i = i + tag_len;
+    emitted = i;
+    if (s->failed)
+      break;
+  }
+  if (emitted > 0) {
+    memmove(s->in.buf, s->in.buf + emitted, s->in.len - emitted);
+    s->in.len -= emitted;
+    s->in.buf[s->in.len] = 0;
+  }
+}
+
+/* Collector used by the one-shot sanitizer. */
+typedef struct {
+  cst_buf_t *b;
+  int failed;
+} md_collect_t;
+
+static int collect_emit(const char *html, size_t len, void *ud) {
+  md_collect_t *c = ud;
+  if (cst_buf_append(c->b, html, len) != 0) {
+    c->failed = 1;
+    return 1;
+  }
+  return 0;
+}
+
+char *cst_web_md_sanitize(const char *html, size_t len) {
+  cst_web_md_t tmp;
+  memset(&tmp, 0, sizeof(tmp));
+  cst_buf_t out = {0};
+  md_collect_t col = {&out, 0};
+  if (cst_buf_append(&tmp.in, html ? html : "", len) != 0)
+    return NULL;
+  tmp.emit = collect_emit;
+  tmp.ud = &col;
+  scan_chunk(&tmp, 1);
+  cst_buf_free(&tmp.in);
+  if (col.failed) {
+    cst_buf_free(&out);
+    return NULL;
+  }
+  return cst_buf_steal(&out);
+}
+
+/* --- sashidown glue ------------------------------------------------------- */
+
+static int on_sashidown_html(const char *html, size_t len, void *user) {
+  cst_web_md_t *s = user;
+  if (cst_buf_append(&s->in, html, len) != 0) {
+    s->failed = 1;
+    return 1;
+  }
+  scan_chunk(s, 0);
+  return s->failed ? 1 : 0;
+}
+
+cst_web_md_t *cst_web_md_new(cst_web_md_emit_fn emit, void *ud) {
+  cst_web_md_t *s = calloc(1, sizeof(*s));
+  if (!s)
+    return NULL;
+  sashidown_stream_opts_t opts;
+  memset(&opts, 0, sizeof(opts));
+  opts.on_html = on_sashidown_html;
+  opts.user = s;
+  s->st = sashidown_stream_create(&opts);
+  if (!s->st) {
+    free(s);
+    return NULL;
+  }
+  s->emit = emit;
+  s->ud = ud;
+  return s;
+}
+
+int cst_web_md_feed(cst_web_md_t *s, const char *data, size_t len) {
+  if (!s || !s->st)
+    return -1;
+  if (len && sashidown_stream_feed(s->st, data, len) != 0) {
+    s->failed = 1;
+    return -1;
+  }
+  return s->failed ? -1 : 0;
+}
+
+int cst_web_md_finish(cst_web_md_t *s) {
+  if (!s || !s->st)
+    return -1;
+  if (sashidown_stream_finish(s->st) != 0) {
+    s->failed = 1;
+    return -1;
+  }
+  scan_chunk(s, 1);
+  return s->failed ? -1 : 0;
+}
+
+void cst_web_md_free(cst_web_md_t *s) {
+  if (!s)
+    return;
+  if (s->st)
+    sashidown_stream_destroy(s->st);
+  cst_buf_free(&s->in);
+  free(s);
+}
+
+char *cst_web_md_html(const char *md, size_t len) {
+  if (!md)
+    return NULL;
+  size_t cap = 65536;
+  char *out = NULL;
+  for (int attempt = 0; attempt < 8; attempt++) {
+    char *buf = malloc(cap);
+    if (!buf)
+      return NULL;
+    size_t out_len = 0;
+    if (sashidown_convert(md, len, buf, cap, &out_len, SASHIDOWN_FMT_HTML) ==
+        0) {
+      out = cst_web_md_sanitize(buf, out_len);
+      free(buf);
+      return out;
+    }
+    free(buf);
+    if (cap >= (size_t)8 * 1024 * 1024)
+      break;
+    cap *= 2;
+  }
+  return NULL;
+}

src/webui_stub.c

@@ -0,0 +1,15 @@
+#include "cst_agent.h"
+#include "cst_webui.h"
+
+#include <stdio.h>
+
+#ifdef CST_NO_WEBUI
+int cst_webui_run(cst_agent_t *agent, const cst_webui_opts_t *opts) {
+  (void)agent;
+  (void)opts;
+  fprintf(stderr,
+          "the WebUI was not built into this binary (CST_BUILD_WEBUI=OFF).\n"
+          "Use --headless --prompt '...' or build with make CST_WEBUI=1\n");
+  return 1;
+}
+#endif

tests/cst_test_util.h

@@ -19,6 +19,7 @@
 #include <io.h>
 #include <windows.h>
 #else
+#include <poll.h>
 #include <sys/stat.h>
 #include <unistd.h>
 #endif
@@ -177,7 +178,7 @@ static CST_TEST_UNUSED void test_sleep_ms(int ms) {
 #ifdef _WIN32
   Sleep((DWORD)ms);
 #else
-  usleep((useconds_t)ms * 1000);
+  poll(NULL, 0, ms); /* usleep is hidden by -std=c11 on musl */
 #endif
 }
 

tests/test_attach.c

@@ -0,0 +1,543 @@
+#define _POSIX_C_SOURCE 200809L
+
+#include "cJSON.h"
+#include "cst_attach.h"
+#include "cst_agent.h"
+#include "cst_clipboard.h"
+#include "cst_test_util.h"
+#include "os_compat.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+static int nfail;
+
+#define EXPECT(cond, msg)                                                      \
+  do {                                                                         \
+    if (!(cond)) {                                                             \
+      fprintf(stderr, "FAIL %s:%d: %s\n", __FILE__, __LINE__, msg);            \
+      nfail++;                                                                 \
+    }                                                                          \
+  } while (0)
+
+static void put_be32(unsigned char *p, unsigned v) {
+  p[0] = (unsigned char)(v >> 24);
+  p[1] = (unsigned char)(v >> 16);
+  p[2] = (unsigned char)(v >> 8);
+  p[3] = (unsigned char)v;
+}
+
+static void put_le16(unsigned char *p, unsigned v) {
+  p[0] = (unsigned char)(v & 0xFF);
+  p[1] = (unsigned char)((v >> 8) & 0xFF);
+}
+
+/* 8 signature + 4 length + "IHDR" + w + h (what cst_attach_dimensions reads). */
+static size_t png_hdr(unsigned char *b, unsigned w, unsigned h) {
+  static const unsigned char sig[8] = {0x89, 'P', 'N', 'G', '\r', '\n', 0x1A, '\n'};
+  memcpy(b, sig, 8);
+  b[8] = b[9] = b[10] = 0;
+  b[11] = 13;
+  memcpy(b + 12, "IHDR", 4);
+  put_be32(b + 16, w);
+  put_be32(b + 20, h);
+  return 32;
+}
+
+static size_t gif_hdr(unsigned char *b, unsigned w, unsigned h) {
+  memcpy(b, "GIF89a", 6);
+  put_le16(b + 6, w);
+  put_le16(b + 8, h);
+  return 16;
+}
+
+static void put_le32(unsigned char *p, unsigned v) {
+  p[0] = (unsigned char)(v & 0xFF);
+  p[1] = (unsigned char)((v >> 8) & 0xFF);
+  p[2] = (unsigned char)((v >> 16) & 0xFF);
+  p[3] = (unsigned char)((v >> 24) & 0xFF);
+}
+
+static size_t bmp_hdr(unsigned char *b, int w, int h) {
+  memset(b, 0, 64);
+  b[0] = 'B';
+  b[1] = 'M';
+  put_le32(b + 18, (unsigned)w);
+  put_le32(b + 22, (unsigned)h);
+  return 64;
+}
+
+/* FFD8 + a filler APP0 segment + SOF0 carrying the frame size. */
+static size_t jpeg_hdr(unsigned char *b, unsigned w, unsigned h) {
+  size_t i = 0;
+  b[i++] = 0xFF;
+  b[i++] = 0xD8;
+  b[i++] = 0xFF;
+  b[i++] = 0xE0;
+  b[i++] = 0x00;
+  b[i++] = 0x04;
+  b[i++] = 0x00;
+  b[i++] = 0x00;
+  b[i++] = 0xFF;
+  b[i++] = 0xC0;
+  b[i++] = 0x00;
+  b[i++] = 0x0B;
+  b[i++] = 0x08;
+  b[i++] = (unsigned char)(h >> 8);
+  b[i++] = (unsigned char)h;
+  b[i++] = (unsigned char)(w >> 8);
+  b[i++] = (unsigned char)w;
+  b[i++] = 0x01; /* one component */
+  b[i++] = 0x01; /* component id */
+  b[i++] = 0x11; /* sampling */
+  b[i++] = 0x00; /* quant table */
+  return i;
+}
+
+static void test_sniff(void) {
+  unsigned char b[64];
+  char mime[32];
+  size_t n;
+
+  n = png_hdr(b, 32, 24);
+  EXPECT(cst_attach_sniff(b, n, mime, sizeof(mime)) == 0 &&
+             strcmp(mime, "image/png") == 0, "PNG sniffed");
+  n = jpeg_hdr(b, 20, 10);
+  EXPECT(cst_attach_sniff(b, n, mime, sizeof(mime)) == 0 &&
+             strcmp(mime, "image/jpeg") == 0, "JPEG sniffed");
+  n = gif_hdr(b, 3, 5);
+  EXPECT(cst_attach_sniff(b, n, mime, sizeof(mime)) == 0 &&
+             strcmp(mime, "image/gif") == 0, "GIF sniffed");
+  memcpy(b, "RIFF\0\0\0\0WEBPVP8 ", 16);
+  EXPECT(cst_attach_sniff(b, 30, mime, sizeof(mime)) == 0 &&
+             strcmp(mime, "image/webp") == 0, "WebP sniffed");
+  n = bmp_hdr(b, 7, 9);
+  EXPECT(cst_attach_sniff(b, n, mime, sizeof(mime)) == 0 &&
+             strcmp(mime, "image/bmp") == 0, "BMP sniffed");
+
+  /* an extension never decides: text and a PDF are not images */
+  EXPECT(cst_attach_sniff("hello, world", 12, mime, sizeof(mime)) != 0,
+         "text rejected");
+  EXPECT(cst_attach_sniff("%PDF-1.7\n", 9, mime, sizeof(mime)) != 0,
+         "PDF rejected");
+  EXPECT(cst_attach_sniff("\x89PNG", 4, mime, sizeof(mime)) != 0,
+         "truncated PNG rejected");
+  EXPECT(cst_attach_sniff("", 0, mime, sizeof(mime)) != 0, "empty rejected");
+}
+
+static void test_dimensions(void) {
+  unsigned char b[64];
+  int w = 0, h = 0;
+  size_t n;
+
+  n = png_hdr(b, 1280, 720);
+  EXPECT(cst_attach_dimensions(b, n, &w, &h) == 0 && w == 1280 && h == 720,
+         "PNG dimensions");
+  n = gif_hdr(b, 16, 40);
+  EXPECT(cst_attach_dimensions(b, n, &w, &h) == 0 && w == 16 && h == 40,
+         "GIF dimensions");
+  n = bmp_hdr(b, 7, 9);
+  EXPECT(cst_attach_dimensions(b, n, &w, &h) == 0 && w == 7 && h == 9,
+         "BMP dimensions");
+  n = jpeg_hdr(b, 640, 480);
+  EXPECT(cst_attach_dimensions(b, n, &w, &h) == 0 && w == 640 && h == 480,
+         "JPEG dimensions");
+
+  w = h = -1;
+  EXPECT(cst_attach_dimensions("nope", 4, &w, &h) != 0 && w == 0 && h == 0,
+         "unknown format gives 0x0");
+}
+
+static void test_base64(void) {
+  char *s = cst_base64_encode("Man", 3);
+  EXPECT(s && strcmp(s, "TWFu") == 0, "base64 <Man>");
+  free(s);
+  s = cst_base64_encode("Ma", 2);
+  EXPECT(s && strcmp(s, "TWE=") == 0, "base64 padding 1");
+  free(s);
+  s = cst_base64_encode("M", 1);
+  EXPECT(s && strcmp(s, "TQ==") == 0, "base64 padding 2");
+  free(s);
+  s = cst_base64_encode("\x00\xff\xfe", 3);
+  EXPECT(s && strcmp(s, "AP/+") == 0, "base64 binary");
+  free(s);
+
+  size_t n = 0;
+  char *d = cst_base64_decode("TWFu", 4, &n);
+  EXPECT(d && n == 3 && memcmp(d, "Man", 3) == 0, "decode <Man>");
+  free(d);
+  d = cst_base64_decode("TQ==", 4, &n);
+  EXPECT(d && n == 1 && d[0] == 'M', "decode with padding");
+  free(d);
+  d = cst_base64_decode("AP/+\n", 5, &n);
+  EXPECT(d && n == 3 && memcmp(d, "\x00\xff\xfe", 3) == 0,
+         "decode binary, newline ignored");
+  free(d);
+  d = cst_base64_decode("AP_-", 4, &n);
+  EXPECT(d && n == 3 && memcmp(d, "\x00\xff\xfe", 3) == 0, "URL-safe alphabet");
+  free(d);
+  EXPECT(cst_base64_decode("A*B=", 4, &n) == NULL, "bad character refused");
+
+  unsigned char raw[200];
+  for (int i = 0; i < 200; i++)
+    raw[i] = (unsigned char)(i * 37);
+  for (size_t len = 0; len < 7; len++) {
+    char *e = cst_base64_encode(raw, 190 + len);
+    d = e ? cst_base64_decode(e, strlen(e), &n) : NULL;
+    EXPECT(d && n == 190 + len && memcmp(d, raw, n) == 0, "round trip");
+    free(e);
+    free(d);
+  }
+}
+
+static void test_rel_ok(const char *root) {
+  EXPECT(cst_attach_rel_ok("img-0a1b2c3d.png"), "normal name accepted");
+  EXPECT(!cst_attach_rel_ok("../x.png"), "parent dir refused");
+  EXPECT(!cst_attach_rel_ok("a/../../b.png"), "slash refused");
+  EXPECT(!cst_attach_rel_ok("/etc/passwd"), "absolute refused");
+  EXPECT(!cst_attach_rel_ok("a\\b.png"), "backslash refused");
+  EXPECT(!cst_attach_rel_ok(".hidden"), "dot file refused");
+  EXPECT(!cst_attach_rel_ok(""), "empty refused");
+
+  cJSON *arr = cJSON_Parse("[{\"id\":\"x\",\"rel\":\"../../secret.png\"},"
+                           "{\"id\":\"y\",\"rel\":\"img-1.png\"}]");
+  int n = 0;
+  cst_attachment_t *back = cst_attachments_from_json(arr, &n);
+  EXPECT(n == 1 && back && strcmp(back[0].id, "y") == 0,
+         "escaping rel dropped on load");
+  cst_attachments_free(back, n);
+  cJSON_Delete(arr);
+
+  /* a stored file swapped for non-image bytes is not sent */
+  char session[1024], full[1024], err[256];
+  snprintf(session, sizeof(session), "%.900s/sessions/r.jsonl", root);
+  unsigned char b[64];
+  size_t bn = png_hdr(b, 4, 4);
+  cst_attachment_t *a =
+      cst_attach_import_bytes(session, "x.png", (const char *)b, bn, err,
+                              sizeof(err));
+  EXPECT(a != NULL, "stored");
+  if (!a)
+    return;
+  EXPECT(cst_attach_full_path(session, a, full, sizeof(full)) == 0, "path");
+  FILE *f = fopen(full, "wb");
+  if (f) {
+    fputs("plain text now", f);
+    fclose(f);
+  }
+  size_t rn = 0;
+  EXPECT(cst_attach_read(session, a, &rn, err, sizeof(err)) == NULL &&
+             strstr(err, "no longer an image"),
+         "read re-checks the bytes");
+  EXPECT(cst_attach_data_url(session, a) == NULL, "no data url for it");
+  snprintf(a->rel, sizeof(a->rel), "../r.jsonl");
+  EXPECT(cst_attach_full_path(session, a, full, sizeof(full)) != 0,
+         "full path refuses an escaping rel");
+  cst_attach_free(a);
+}
+
+static void test_store(const char *root) {
+  char session[1024], dir[1024];
+  snprintf(session, sizeof(session), "%.900s/sessions/a.jsonl", root);
+  unsigned char b[64];
+  size_t n = png_hdr(b, 32, 24);
+  char err[256];
+
+  cst_attachment_t *a = cst_attach_import_bytes(session, "shot.png",
+                                                (const char *)b, n, err,
+                                                sizeof(err));
+  EXPECT(a != NULL, "import stored");
+  if (!a) {
+    fprintf(stderr, "  err: %s\n", err);
+    return;
+  }
+  EXPECT(strcmp(a->mime, "image/png") == 0, "stored mime");
+  EXPECT(a->width == 32 && a->height == 24, "stored dimensions");
+  EXPECT(a->bytes == (long long)n, "stored size");
+  EXPECT(strcmp(a->name, "shot.png") == 0, "stored name");
+  EXPECT(strcmp(a->origin, "user") == 0, "origin=user");
+  EXPECT(strcmp(a->rel, "img-") != 0 && strstr(a->rel, ".png") != NULL,
+         "rel has a .png extension");
+
+  EXPECT(cst_attach_dir(session, dir, sizeof(dir)) == 0, "attach dir");
+  char full[1024];
+  EXPECT(cst_attach_full_path(session, a, full, sizeof(full)) == 0 &&
+             strstr(full, "attachments/") != NULL,
+         "full path inside attachments/");
+  FILE *f = fopen(full, "rb");
+  EXPECT(f != NULL, "stored file exists");
+  if (f)
+    fclose(f);
+
+  char desc[128];
+  cst_attach_describe(a, desc, sizeof(desc));
+  EXPECT(strstr(desc, "32x24") && strstr(desc, "png"), "describe has size");
+
+  size_t rn = 0;
+  char *data = cst_attach_read(session, a, &rn, err, sizeof(err));
+  EXPECT(data && rn == n && memcmp(data, b, n) == 0, "read back exact bytes");
+  free(data);
+
+  char *url = cst_attach_data_url(session, a);
+  EXPECT(url && strncmp(url, "data:image/png;base64,", 22) == 0,
+         "data url prefix");
+  if (url)
+    EXPECT(strlen(url) == 22 + ((n + 2) / 3) * 4, "data url length");
+  free(url);
+
+  cst_attach_free(a);
+
+  /* a text file named .png is still refused */
+  EXPECT(cst_attach_import_bytes(session, "fake.png", "not an image", 12, err,
+                                 sizeof(err)) == NULL,
+         "content decides, not the name");
+  EXPECT(strstr(err, "not a supported image") != NULL, "err explains why");
+  EXPECT(cst_attach_import_bytes(session, "empty.png", "", 0, err,
+                                 sizeof(err)) == NULL,
+         "empty data refused");
+}
+
+static void test_import_file(const char *root) {
+  char session[1024], src[1024];
+  snprintf(session, sizeof(session), "%.900s/sessions/b.jsonl", root);
+  snprintf(src, sizeof(src), "%.900s/logo.gif", root);
+  unsigned char b[64];
+  size_t n = gif_hdr(b, 8, 6);
+  FILE *f = fopen(src, "wb");
+  EXPECT(f != NULL, "write source image");
+  if (f) {
+    fwrite(b, 1, n, f);
+    fclose(f);
+  }
+  char err[256];
+  cst_attachment_t *a =
+      cst_attach_import_file(session, src, err, sizeof(err));
+  EXPECT(a != NULL, "file imported");
+  if (a) {
+    EXPECT(strcmp(a->mime, "image/gif") == 0, "imported mime");
+    EXPECT(strcmp(a->name, "logo.gif") == 0, "imported keeps the leaf name");
+    EXPECT(a->width == 8 && a->height == 6, "imported dimensions");
+    cst_attach_free(a);
+  }
+  EXPECT(cst_attach_import_file(session, "/nonexistent/x.png", err,
+                                sizeof(err)) == NULL,
+         "missing file refused");
+}
+
+static void test_json_roundtrip(void) {
+  cst_attachment_t list[3];
+  memset(list, 0, sizeof(list));
+  snprintf(list[0].id, sizeof(list[0].id), "img-1");
+  snprintf(list[0].name, sizeof(list[0].name), "a.png");
+  snprintf(list[0].mime, sizeof(list[0].mime), "image/png");
+  snprintf(list[0].rel, sizeof(list[0].rel), "img-1.png");
+  list[0].bytes = 12345;
+  list[0].width = 640;
+  list[0].height = 480;
+  snprintf(list[0].origin, sizeof(list[0].origin), "user");
+
+  snprintf(list[1].id, sizeof(list[1].id), "img-2");
+  snprintf(list[1].name, sizeof(list[1].name), "b.jpg");
+  snprintf(list[1].mime, sizeof(list[1].mime), "image/jpeg");
+  snprintf(list[1].rel, sizeof(list[1].rel), "img-2.jpg");
+  list[1].bytes = 4096;
+  snprintf(list[1].detail, sizeof(list[1].detail), "high");
+  snprintf(list[1].origin, sizeof(list[1].origin), "view_image");
+
+  snprintf(list[2].id, sizeof(list[2].id), "img-3");
+  snprintf(list[2].name, sizeof(list[2].name), "c.webp");
+  snprintf(list[2].mime, sizeof(list[2].mime), "image/webp");
+  snprintf(list[2].rel, sizeof(list[2].rel), "img-3.webp");
+  list[2].bytes = 7;
+
+  char *json = cst_attachments_to_json(list, 3);
+  EXPECT(json != NULL, "to_json");
+  int n = 0;
+  cJSON *parsed = cJSON_Parse(json);
+  cst_attachment_t *back = cst_attachments_from_json(parsed, &n);
+  cJSON_Delete(parsed);
+  EXPECT(back != NULL && n == 3, "from_json count");
+  if (back && n == 3) {
+    EXPECT(strcmp(back[0].id, "img-1") == 0 && back[0].bytes == 12345 &&
+               back[0].width == 640 && back[0].height == 480,
+           "first entry survives");
+    EXPECT(strcmp(back[1].detail, "high") == 0 &&
+               strcmp(back[1].origin, "view_image") == 0,
+           "detail and origin survive");
+    EXPECT(strcmp(back[2].mime, "image/webp") == 0 && back[2].width == 0,
+           "entry without dimensions");
+    EXPECT(strcmp(back[0].detail, "auto") == 0, "missing detail defaults");
+    cst_attachments_free(back, n);
+  }
+  free(json);
+
+  /* entries without rel/id are dropped; a non-array is NULL */
+  cJSON *arr = cJSON_Parse("[{\"id\":\"x\"},{\"id\":\"y\",\"rel\":\"y.png\"}]");
+  back = cst_attachments_from_json(arr, &n);
+  EXPECT(back != NULL && n == 1 && strcmp(back[0].id, "y") == 0,
+         "incomplete entries skipped");
+  cst_attachments_free(back, n);
+  cJSON_Delete(arr);
+  cJSON *obj = cJSON_Parse("{}");
+  n = 7;
+  EXPECT(cst_attachments_from_json(obj, &n) == NULL && n == 0,
+         "object is not an attachment array");
+  cJSON_Delete(obj);
+  EXPECT(cst_attachments_to_json(NULL, 0) == NULL, "empty list is NULL");
+}
+
+static void test_lists(void) {
+  cst_attachment_t src;
+  memset(&src, 0, sizeof(src));
+  snprintf(src.id, sizeof(src.id), "img-x");
+  snprintf(src.mime, sizeof(src.mime), "image/png");
+
+  cst_attachment_t *list = NULL;
+  int n = 0, cap = 0;
+  for (int i = 0; i < 10; i++)
+    EXPECT(cst_attachments_push(&list, &n, &cap, &src) == 0, "push");
+  EXPECT(n == 10 && cap >= 10, "list grew");
+  EXPECT(strcmp(list[9].id, "img-x") == 0, "last entry copied");
+
+  cst_attachment_t *dup = cst_attachments_dup(list, n);
+  EXPECT(dup && strcmp(dup[3].mime, "image/png") == 0, "dup copies fields");
+  dup[3].id[0] = 'Z';
+  EXPECT(list[3].id[0] == 'i', "dup is a deep copy");
+  cst_attachments_free(dup, n);
+  EXPECT(cst_attachments_dup(NULL, 0) == NULL, "dup of nothing is NULL");
+  cst_attachments_free(list, n);
+}
+
+static void test_agent_pending(const char *root) {
+  cst_agent_config_t cfg;
+  memset(&cfg, 0, sizeof(cfg));
+  snprintf(cfg.workspace_root, sizeof(cfg.workspace_root), "%s", root);
+  snprintf(cfg.session_path, sizeof(cfg.session_path), "%s/sessions/c.jsonl",
+           root);
+  cst_agent_t *a = cst_agent_create(&cfg);
+  EXPECT(a != NULL, "agent created");
+  if (!a)
+    return;
+
+  char err[256], line[128];
+  EXPECT(cst_agent_pending_count(a) == 0, "no pending at start");
+  EXPECT(cst_agent_pending_describe(a, 0, line, sizeof(line)) == -1,
+         "describe out of range");
+
+  unsigned char b[32];
+  size_t n = png_hdr(b, 4, 2);
+  char src[1024];
+  snprintf(src, sizeof(src), "%.900s/pic.png", root);
+  FILE *f = fopen(src, "wb");
+  EXPECT(f != NULL, "write the source png");
+  if (f) {
+    fwrite(b, 1, n, f);
+    fclose(f);
+  }
+  EXPECT(cst_agent_attach_file(a, src, err, sizeof(err)) == 0,
+         "attach through the agent");
+  EXPECT(cst_agent_pending_count(a) == 1, "one pending");
+  EXPECT(cst_agent_pending_describe(a, 0, line, sizeof(line)) == 0 &&
+             strstr(line, "4x2") != NULL,
+         "pending describe shows the size");
+
+  EXPECT(cst_agent_attach_file(a, "/nonexistent/x.png", err, sizeof(err)) == -1,
+         "missing file refused");
+  EXPECT(cst_agent_pending_count(a) == 1, "a failure keeps the queue");
+
+  for (int i = 1; i < CST_ATTACH_MAX_COUNT; i++)
+    EXPECT(cst_agent_attach_file(a, src, err, sizeof(err)) == 0, "attach more");
+  EXPECT(cst_agent_pending_count(a) == CST_ATTACH_MAX_COUNT, "queue full");
+  EXPECT(cst_agent_attach_file(a, src, err, sizeof(err)) == -1 &&
+             strstr(err, "at most") != NULL,
+         "one over the limit is refused");
+
+  cst_agent_pending_clear(a);
+  EXPECT(cst_agent_pending_count(a) == 0, "cleared");
+  cst_agent_destroy(a);
+}
+
+static void test_paste_paths(void) {
+  static char p[CST_PASTE_MAX_PATHS][CST_PASTE_PATH_MAX];
+  const char *s = "/tmp/a.png";
+  EXPECT(cst_paste_paths(s, strlen(s), p, 8) == 1 &&
+             strcmp(p[0], "/tmp/a.png") == 0,
+         "single path");
+  s = "  '/home/u/my shot.png' \"/x/y z.jpg\"\n/plain.gif\r\n";
+  EXPECT(cst_paste_paths(s, strlen(s), p, 8) == 3, "quoted paths count");
+  EXPECT(strcmp(p[0], "/home/u/my shot.png") == 0, "single quotes");
+  EXPECT(strcmp(p[1], "/x/y z.jpg") == 0, "double quotes");
+  EXPECT(strcmp(p[2], "/plain.gif") == 0, "newline separated");
+  s = "file:///home/u/a%20b.png file://localhost/c.png";
+  EXPECT(cst_paste_paths(s, strlen(s), p, 8) == 2, "file uris");
+  EXPECT(strcmp(p[0], "/home/u/a b.png") == 0, "percent decoded");
+  EXPECT(strcmp(p[1], "/c.png") == 0, "localhost host");
+  s = "file://evil.example/c.png";
+  EXPECT(cst_paste_paths(s, strlen(s), p, 8) == -1, "remote host refused");
+#ifndef _WIN32
+  s = "/home/u/my\\ shot.png";
+  EXPECT(cst_paste_paths(s, strlen(s), p, 8) == 1 &&
+             strcmp(p[0], "/home/u/my shot.png") == 0,
+         "backslash escape");
+#endif
+  s = "'/unterminated.png";
+  EXPECT(cst_paste_paths(s, strlen(s), p, 8) == -1, "unbalanced quote");
+  s = "   \n ";
+  EXPECT(cst_paste_paths(s, strlen(s), p, 8) == -1, "blank");
+  s = "a b c";
+  EXPECT(cst_paste_paths(s, strlen(s), p, 2) == -1, "too many");
+}
+
+static void test_dib(void) {
+  /* 3x2, 24-bit, bottom-up: stride 12 (9 bytes + pad). */
+  unsigned char dib[40 + 24];
+  memset(dib, 0, sizeof(dib));
+  put_le32(dib, 40);
+  put_le32(dib + 4, 3);
+  put_le32(dib + 8, 2);
+  put_le16(dib + 12, 1);
+  put_le16(dib + 14, 24);
+  dib[40] = 0xff; /* bottom-left pixel blue (BGR) */
+  size_t n = 0;
+  char *img = cst_dib_to_image(dib, sizeof(dib), &n);
+  char mime[32];
+  int w = 0, h = 0;
+  EXPECT(img && cst_attach_sniff(img, n, mime, sizeof(mime)) == 0 &&
+             strcmp(mime, "image/png") == 0,
+         "24-bit DIB becomes a PNG");
+  EXPECT(img && cst_attach_dimensions(img, n, &w, &h) == 0 && w == 3 && h == 2,
+         "PNG keeps the size");
+  free(img);
+
+  put_le16(dib + 14, 8); /* palette needs 256 entries: past the end */
+  EXPECT(cst_dib_to_image(dib, sizeof(dib), &n) == NULL, "short DIB refused");
+  put_le32(dib, 4);
+  EXPECT(cst_dib_to_image(dib, sizeof(dib), &n) == NULL, "bad header size");
+}
+
+int main(void) {
+  char root[1024];
+  if (test_tmpdir(root, sizeof(root), "cst-attach") != 0) {
+    fprintf(stderr, "cannot create a scratch dir\n");
+    return 1;
+  }
+  test_sniff();
+  test_dimensions();
+  test_base64();
+  test_rel_ok(root);
+  test_paste_paths();
+  test_dib();
+  test_store(root);
+  test_import_file(root);
+  test_json_roundtrip();
+  test_lists();
+  test_agent_pending(root);
+  test_rmrf(root);
+  if (nfail) {
+    fprintf(stderr, "test_attach: %d failed\n", nfail);
+    return 1;
+  }
+  printf("test_attach: OK\n");
+  return 0;
+}

tests/test_llm_body.c

@@ -1,5 +1,7 @@
 #include "cJSON.h"
 #include "cst_agent.h"
+#include "cst_attach.h"
+#include "cst_test_util.h"
 
 #include <stdio.h>
 #include <stdlib.h>
@@ -159,7 +161,257 @@ static void test_tool_cap_head_tail(void) {
   free(big);
 }
 
+static cJSON *build_req(const cst_llm_request_t *r) {
+  char *body = cst_llm_build_body(r);
+  EXPECT(body != NULL, "body built");
+  cJSON *j = body ? cJSON_Parse(body) : NULL;
+  EXPECT(j != NULL, "body is valid JSON");
+  free(body);
+  return j;
+}
+
+static const cJSON *msg_at(const cJSON *root, int i) {
+  return cJSON_GetArrayItem(cJSON_GetObjectItemCaseSensitive(root, "messages"),
+                            i);
+}
+
+static const cJSON *cache_mark(const cJSON *m) {
+  const cJSON *c = cJSON_GetObjectItemCaseSensitive(m, "content");
+  if (!cJSON_IsArray(c))
+    return NULL;
+  const cJSON *last = cJSON_GetArrayItem(c, cJSON_GetArraySize(c) - 1);
+  return cJSON_GetObjectItemCaseSensitive(last, "cache_control");
+}
+
+static void test_reasoning_and_prefix(void) {
+  cst_message_t m[4];
+  m[0] = msg(CST_ROLE_SYSTEM, "sys");
+  m[1] = msg(CST_ROLE_USER, "go");
+  m[2] = msg(CST_ROLE_ASSISTANT, "partial answer");
+  m[2].reasoning = "thinking it over";
+  m[3] = msg(CST_ROLE_ASSISTANT, "cut off here");
+  m[3].prefix = 1;
+  cst_llm_request_t r;
+  memset(&r, 0, sizeof(r));
+  r.model = "deepseek-flash";
+  r.msgs = m;
+  r.nmsgs = 4;
+  cJSON *j = build_req(&r);
+  EXPECT(!cJSON_GetObjectItemCaseSensitive(msg_at(j, 2), "reasoning_content"),
+         "reasoning only when asked for");
+  const cJSON *p = cJSON_GetObjectItemCaseSensitive(msg_at(j, 3), "prefix");
+  EXPECT(cJSON_IsTrue(p), "prefix:true on the continued message");
+  EXPECT(!cJSON_GetObjectItemCaseSensitive(msg_at(j, 2), "prefix"),
+         "no prefix on history");
+  cJSON_Delete(j);
+
+  r.send_reasoning = 1;
+  j = build_req(&r);
+  const cJSON *rc =
+      cJSON_GetObjectItemCaseSensitive(msg_at(j, 2), "reasoning_content");
+  EXPECT(cJSON_IsString(rc) && strcmp(rc->valuestring, "thinking it over") == 0,
+         "reasoning_content passed back");
+  EXPECT(!cJSON_GetObjectItemCaseSensitive(j, "prompt_cache_key"),
+         "no cache key without a cache style");
+  cJSON_Delete(j);
+}
+
+static void test_cache_hints(void) {
+  cst_message_t m[4];
+  m[0] = msg(CST_ROLE_SYSTEM, "sys");
+  m[1] = msg(CST_ROLE_USER, "first");
+  m[2] = msg(CST_ROLE_ASSISTANT, "reply");
+  m[3] = msg(CST_ROLE_USER, "second");
+  cst_llm_request_t r;
+  memset(&r, 0, sizeof(r));
+  r.model = "gpt-4.1";
+  r.msgs = m;
+  r.nmsgs = 4;
+  r.cache_style = CST_CACHE_OPENAI;
+  r.cache_key = "sess-1";
+  cJSON *j = build_req(&r);
+  const cJSON *k = cJSON_GetObjectItemCaseSensitive(j, "prompt_cache_key");
+  EXPECT(cJSON_IsString(k) && strcmp(k->valuestring, "sess-1") == 0,
+         "prompt_cache_key");
+  EXPECT(content_at(j, 3) && !cache_mark(msg_at(j, 3)),
+         "OpenAI style leaves content as strings");
+  cJSON_Delete(j);
+
+  r.model = "anthropic/claude-sonnet-4";
+  r.cache_style = CST_CACHE_ANTHROPIC;
+  r.cache_ttl = "1h";
+  j = build_req(&r);
+  EXPECT(!cJSON_GetObjectItemCaseSensitive(j, "prompt_cache_key"),
+         "no prompt_cache_key for Anthropic");
+  const cJSON *cs = cache_mark(msg_at(j, 0));
+  const cJSON *cl = cache_mark(msg_at(j, 3));
+  const cJSON *cu = cache_mark(msg_at(j, 1));
+  EXPECT(cs && cl && cu, "breakpoints on system, newest, previous user");
+  EXPECT(!cache_mark(msg_at(j, 2)), "no breakpoint on the assistant reply");
+  const cJSON *ttl = cJSON_GetObjectItemCaseSensitive(cl, "ttl");
+  EXPECT(cJSON_IsString(ttl) && strcmp(ttl->valuestring, "1h") == 0, "ttl");
+  const cJSON *parts =
+      cJSON_GetObjectItemCaseSensitive(msg_at(j, 3), "content");
+  const cJSON *txt =
+      cJSON_GetObjectItemCaseSensitive(cJSON_GetArrayItem(parts, 0), "text");
+  EXPECT(cJSON_IsString(txt) && strcmp(txt->valuestring, "second") == 0,
+         "marked content keeps its text");
+  cJSON_Delete(j);
+}
+
+static void test_tools_snapshot(void) {
+  cst_message_t m[1] = {msg(CST_ROLE_USER, "go")};
+  cst_llm_request_t r;
+  memset(&r, 0, sizeof(r));
+  r.model = "test-model";
+  r.msgs = m;
+  r.nmsgs = 1;
+  r.enable_tools = 1;
+  r.tools_json = "[{\"type\":\"function\",\"function\":{\"name\":\"only_me\","
+                 "\"parameters\":{\"type\":\"object\"}}}]";
+  cJSON *j = build_req(&r);
+  const cJSON *tools = cJSON_GetObjectItemCaseSensitive(j, "tools");
+  EXPECT(cJSON_IsArray(tools) && cJSON_GetArraySize(tools) == 1,
+         "tools[] taken from the snapshot");
+  const cJSON *nm = cJSON_GetObjectItemCaseSensitive(
+      cJSON_GetObjectItemCaseSensitive(cJSON_GetArrayItem(tools, 0),
+                                       "function"),
+      "name");
+  EXPECT(cJSON_IsString(nm) && strcmp(nm->valuestring, "only_me") == 0,
+         "snapshot tool name");
+  cJSON_Delete(j);
+}
+
+static void test_images_off(void) {
+  cst_attachment_t img;
+  memset(&img, 0, sizeof(img));
+  snprintf(img.id, sizeof(img.id), "img-1");
+  snprintf(img.rel, sizeof(img.rel), "img-1.png");
+  snprintf(img.name, sizeof(img.name), "shot.png");
+  snprintf(img.mime, sizeof(img.mime), "image/png");
+  img.width = 640;
+  img.height = 480;
+  img.bytes = 2048;
+  cst_message_t m[4];
+  m[0] = msg(CST_ROLE_USER, "what is this");
+  m[0].attach = &img;
+  m[0].nattach = 1;
+  m[1] = msg(CST_ROLE_ASSISTANT, "");
+  m[1].tool_calls_json = "[{\"id\":\"c1\",\"type\":\"function\",\"function\":"
+                         "{\"name\":\"view_image\",\"arguments\":\"{}\"}}]";
+  m[2] = msg(CST_ROLE_TOOL, "view_image shot.png");
+  snprintf(m[2].tool_call_id, sizeof(m[2].tool_call_id), "c1");
+  m[2].attach = &img;
+  m[2].nattach = 1;
+  m[3] = msg(CST_ROLE_USER, "and now?");
+  cst_llm_request_t r;
+  memset(&r, 0, sizeof(r));
+  r.model = "deepseek-flash";
+  r.msgs = m;
+  r.nmsgs = 4;
+  r.images_off = 1;
+  r.session_path = "/nonexistent/s.jsonl";
+  cJSON *j = build_req(&r);
+  char *s = cJSON_PrintUnformatted(j);
+  EXPECT(s && !strstr(s, "image_url"), "no image parts when images are off");
+  free(s);
+  const char *c0 = content_at(j, 0);
+  EXPECT(c0 && strstr(c0, "what is this") &&
+             strstr(c0, "[image \"shot.png\" (640x480") &&
+             strstr(c0, "not sent: this model does not take images"),
+         "user image becomes a plain-text note");
+  const char *c2 = content_at(j, 2);
+  EXPECT(c2 && strstr(c2, "view_image shot.png") && strstr(c2, "not sent"),
+         "tool image noted inside the tool result");
+  EXPECT(nmsgs(j) == 4, "no extra user message for deferred tool images");
+  cJSON_Delete(j);
+}
+
+/* Every element of every content array must be a typed part object. */
+static int parts_typed(const cJSON *root) {
+  const cJSON *m;
+  cJSON_ArrayForEach(m, cJSON_GetObjectItemCaseSensitive(root, "messages")) {
+    const cJSON *c = cJSON_GetObjectItemCaseSensitive(m, "content");
+    if (!cJSON_IsArray(c))
+      continue;
+    const cJSON *p;
+    cJSON_ArrayForEach(p, c) {
+      const cJSON *t = cJSON_GetObjectItemCaseSensitive(p, "type");
+      if (!cJSON_IsObject(p) || !cJSON_IsString(t))
+        return 0;
+    }
+  }
+  return 1;
+}
+
+static void test_images_on(void) {
+  char dir[1024], sess[1100], err[256];
+  if (test_tmpdir(dir, sizeof(dir), "cst-body") != 0) {
+    EXPECT(0, "scratch dir");
+    return;
+  }
+  snprintf(sess, sizeof(sess), "%s/s.jsonl", dir);
+  static const unsigned char png[32] = {0x89, 'P', 'N', 'G', '\r', '\n', 0x1A,
+                                        '\n', 0, 0, 0, 13, 'I', 'H', 'D', 'R',
+                                        0, 0, 0, 2, 0, 0, 0, 2};
+  cst_attachment_t *img = cst_attach_import_bytes(sess, "shot.png",
+                                                  (const char *)png,
+                                                  sizeof(png), err, sizeof(err));
+  EXPECT(img != NULL, "image stored");
+  if (!img)
+    return;
+  cst_attachment_t gone = *img;
+  snprintf(gone.rel, sizeof(gone.rel), "missing.png");
+  cst_message_t m[5];
+  m[0] = msg(CST_ROLE_USER, "what is this");
+  m[0].attach = img;
+  m[0].nattach = 1;
+  m[1] = msg(CST_ROLE_ASSISTANT, "");
+  m[1].tool_calls_json = "[{\"id\":\"c1\",\"type\":\"function\",\"function\":"
+                         "{\"name\":\"view_image\",\"arguments\":\"{}\"}}]";
+  m[2] = msg(CST_ROLE_TOOL, "view_image shot.png");
+  snprintf(m[2].tool_call_id, sizeof(m[2].tool_call_id), "c1");
+  m[2].attach = img;
+  m[2].nattach = 1;
+  m[3] = msg(CST_ROLE_USER, "and now?");
+  m[4] = msg(CST_ROLE_USER, "");
+  m[4].attach = &gone;
+  m[4].nattach = 1;
+  cst_llm_request_t r;
+  memset(&r, 0, sizeof(r));
+  r.model = "deepseek-flash";
+  r.msgs = m;
+  r.nmsgs = 5;
+  r.session_path = sess;
+  cJSON *j = build_req(&r);
+  EXPECT(parts_typed(j), "content arrays hold only typed parts");
+  const cJSON *p0 = cJSON_GetObjectItemCaseSensitive(
+      cJSON_GetArrayItem(cJSON_GetObjectItemCaseSensitive(j, "messages"), 0),
+      "content");
+  const cJSON *t0 = cJSON_GetObjectItemCaseSensitive(
+      cJSON_GetArrayItem(p0, 0), "text");
+  const cJSON *u1 = cJSON_GetObjectItemCaseSensitive(
+      cJSON_GetObjectItemCaseSensitive(cJSON_GetArrayItem(p0, 1), "image_url"),
+      "url");
+  EXPECT(cJSON_IsString(t0) && strcmp(t0->valuestring, "what is this") == 0,
+         "user text is a text part");
+  EXPECT(cJSON_IsString(u1) &&
+             strncmp(u1->valuestring, "data:image/png;base64,", 22) == 0,
+         "image is a data URL part");
+  char *s = cJSON_PrintUnformatted(j);
+  EXPECT(s && strstr(s, "and now?") && strstr(s, "not sent"),
+         "follow-up text and the missing-image note are parts too");
+  free(s);
+  cJSON_Delete(j);
+  cst_attach_free(img);
+}
+
 int main(void) {
+  test_images_off();
+  test_images_on();
+  test_reasoning_and_prefix();
+  test_cache_hints();
+  test_tools_snapshot();
   test_escaping();
   test_invalid_utf8();
   test_tool_calls_and_null_content();

tests/test_mcp.c

@@ -5,6 +5,8 @@
 #define _POSIX_C_SOURCE 200809L
 
 #include "cJSON.h"
+#include "cst_agent.h"
+#include "cst_attach.h"
 #include "cst_mcp.h"
 #include "cst_tools.h"
 #include "os_compat.h"
@@ -18,6 +20,7 @@
 
 static int nfail;
 static char g_tmp[OS_PATH_MAX];
+static cst_agent_t *g_agent;
 
 #define CHECK(cond, msg)                                                       \
   do {                                                                         \
@@ -99,6 +102,7 @@ static int server(void) {
         cJSON_AddItemToArray(tools, tool("mixed", "Mixed content."));
         cJSON_AddItemToArray(tools, tool("hang", "Never answers."));
         cJSON_AddItemToArray(tools, tool("crash", "Exits."));
+        cJSON_AddItemToArray(tools, tool("pic", "Returns images."));
       }
       reply(id, r);
     } else if (strcmp(mt, "tools/call") == 0) {
@@ -136,6 +140,21 @@ static int server(void) {
         cJSON_AddStringToObject(rr, "text", "resource text");
         cJSON_AddItemToArray(c, res);
         reply(id, r);
+      } else if (strcmp(name, "pic") == 0) {
+        cJSON *r = text_result("a chart", 0);
+        cJSON *c = cJSON_GetObjectItemCaseSensitive(r, "content");
+        const char *datas[] = {
+            "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAC"
+            "hwGA60e6kgAAAABJRU5ErkJggg==",
+            "AAAA"};
+        for (int i = 0; i < 2; i++) {
+          cJSON *img = cJSON_CreateObject();
+          cJSON_AddStringToObject(img, "type", "image");
+          cJSON_AddStringToObject(img, "mimeType", "image/png");
+          cJSON_AddStringToObject(img, "data", datas[i]);
+          cJSON_AddItemToArray(c, img);
+        }
+        reply(id, r);
       } else if (strcmp(name, "crash") == 0) {
         fprintf(stderr, "fatal: fake crash\n");
         exit(3);
@@ -163,6 +182,7 @@ static int call(const char *tool, const char *k, const char *v,
   cst_tool_ctx_t ctx;
   memset(&ctx, 0, sizeof(ctx));
   ctx.workspace_root = g_tmp;
+  ctx.agent = g_agent;
   memset(r, 0, sizeof(*r));
   return cst_tool_run(&ctx, &c, r);
 }
@@ -217,8 +237,8 @@ int main(int argc, char **argv) {
   cst_mcp_info_t mi[CST_MCP_MAX];
   int n = cst_mcp_info(mi, CST_MCP_MAX);
   const cst_mcp_info_t *f = info_of("fake", mi, n);
-  CHECK(f && f->state == CST_MCP_READY && f->ntools == 6,
-        "fake ready with 6 tools over two pages");
+  CHECK(f && f->state == CST_MCP_READY && f->ntools == 7,
+        "fake ready with 7 tools over two pages");
   const cst_mcp_info_t *rm = info_of("remote", mi, n);
   CHECK(rm && rm->state == CST_MCP_FAILED && strstr(rm->error, "stdio"),
         "url servers unsupported");
@@ -255,8 +275,40 @@ int main(int argc, char **argv) {
   CHECK(r.exit_code == 0 && r.out && strstr(r.out, "first\n[image image/png") &&
             strstr(r.out, "resource text"),
         "content items mapped to text");
+  CHECK(r.nattach == 0, "no session: images stay text");
   cst_tool_result_free(&r);
 
+  cst_agent_config_t acfg;
+  memset(&acfg, 0, sizeof(acfg));
+  snprintf(acfg.workspace_root, sizeof(acfg.workspace_root), "%s", g_tmp);
+  char sdir[1024];
+  snprintf(sdir, sizeof(sdir), "%.900s/cst-mcp-test-%d", g_tmp, (int)getpid());
+  os_mkdir_p(sdir, 0755);
+  snprintf(acfg.session_path, sizeof(acfg.session_path), "%s/s.jsonl", sdir);
+  g_agent = cst_agent_create(&acfg);
+  CHECK(g_agent != NULL, "agent for the session store");
+  call("mcp__fake__pic", NULL, NULL, &r);
+  CHECK(r.exit_code == 0 && r.nattach == 1 && r.attach &&
+            strcmp(r.attach[0].mime, "image/png") == 0 &&
+            strcmp(r.attach[0].origin, "mcp") == 0 &&
+            r.attach[0].width == 1 && r.attach[0].height == 1,
+        "image content stored and attached");
+  CHECK(r.out && strstr(r.out, "a chart\n[image ") &&
+            strstr(r.out, "shown to you as an image") &&
+            strstr(r.out, "not shown:"),
+        "one line per image, bad data falls back to text");
+  if (r.nattach == 1) {
+    char full[OS_PATH_MAX];
+    CHECK(cst_attach_full_path(acfg.session_path, &r.attach[0], full,
+                               sizeof(full)) == 0 &&
+              access(full, R_OK) == 0,
+          "stored file exists");
+  }
+  cst_tool_result_free(&r);
+  cst_agent_destroy(g_agent);
+  g_agent = NULL;
+  test_rmrf(sdir);
+
   volatile int cancel = 1;
   os_set_cancel_flag(&cancel);
   double t0 = os_now_ms();

tests/test_model_registry.c

@@ -0,0 +1,227 @@
+/* Model registry: built-in data, longest/most specific match, the user file,
+ * the fetched cache and the env overrides. */
+#define _POSIX_C_SOURCE 200809L
+
+#include "cJSON.h"
+#include "cst_agent.h"
+#include "cst_models.h"
+#include "cst_test_util.h"
+#include "os_compat.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+static int nfail;
+
+#define EXPECT(cond, msg)                                                      \
+  do {                                                                         \
+    if (!(cond)) {                                                             \
+      fprintf(stderr, "FAIL %s:%d: %s\n", __FILE__, __LINE__, msg);            \
+      nfail++;                                                                 \
+    }                                                                          \
+  } while (0)
+
+static void test_builtin(void) {
+  cJSON *doc = cJSON_Parse(cst_models_builtin_json());
+  EXPECT(cJSON_IsObject(doc), "embedded built-in JSON parses");
+  cJSON_Delete(doc);
+  EXPECT(cst_models_load_error()[0] == 0, "no load error");
+  EXPECT(cst_provider_count() >= 4, "built-in providers");
+  const cst_provider_t *p = cst_provider_at(0);
+  EXPECT(p && strcmp(p->name, "minimax") == 0, "file order kept");
+  p = cst_provider_find("deepseek");
+  EXPECT(p && strcmp(p->model, "deepseek-flash") == 0 &&
+             strcmp(p->key_env, "DEEPSEEK_API_KEY") == 0 &&
+             strcmp(cst_provider_source(p), "built-in") == 0,
+         "deepseek preset");
+
+  cst_model_info_t mi;
+  /* most specific rule per field: price from deepseek-v4-pro, context from
+   * deepseek */
+  cst_model_info("deepseek", "deepseek-v4-pro", &mi);
+  EXPECT(mi.context == 1000000 && mi.vision == 0, "context inherited");
+  EXPECT(mi.has_price && mi.price.miss == 9.0 && mi.price.offpeak_half,
+         "longer match wins the price");
+  EXPECT(strcmp(mi.source, "built-in") == 0, "source built-in");
+  cst_model_info("deepseek", "deepseek-flash", &mi);
+  EXPECT(mi.context == 1000000 && mi.vision == 1, "deepseek-flash takes images");
+  cst_model_info("deepseek", "deepseek-chat", &mi);
+  EXPECT(mi.vision == 1, "deepseek-chat is deepseek-flash");
+  cst_model_info(NULL, "gpt-4o-mini-2024", &mi);
+  EXPECT(mi.price.miss == 0.15 && mi.context == 128000 && mi.vision == 1,
+         "gpt-4o-mini over gpt-4o");
+  cst_model_info(NULL, "Qwen/Qwen2.5-VL-72B-Instruct", &mi);
+  EXPECT(mi.vision == 1 && mi.context == 131072, "glob *-vl* + qwen prefix");
+  cst_model_info(NULL, "zhipu/glm-4.5v", &mi);
+  EXPECT(mi.vision == 1 && mi.context == 128000, "glm-*v*");
+  cst_model_info(NULL, "glm-4-plus", &mi);
+  EXPECT(mi.vision == -1, "glm without v: unknown");
+  cst_model_info(NULL, "anthropic/some-new-model", &mi);
+  EXPECT(mi.cache_style == CST_CACHE_ANTHROPIC, "vendor rule on the full id");
+  cst_model_info(NULL, "totally-unknown", &mi);
+  EXPECT(mi.context == 128000 && mi.vision == -1 && !mi.has_price &&
+             strcmp(mi.source, "default") == 0,
+         "defaults");
+  char tag[48];
+  cst_model_info(NULL, "gpt-4.1", &mi);
+  cst_model_info_label(&mi, tag, sizeof(tag));
+  EXPECT(strcmp(tag, "1M · vision") == 0, "label");
+}
+
+static const char *USER_JSON =
+    "{\"providers\": {"
+    "  \"deepseek\": {\"api_base\": \"https://proxy.example/v1\"},"
+    "  \"local\": {\"api_base\": \"http://127.0.0.1:8000/v1\","
+    "             \"key_env\": \"LOCAL_KEY\", \"default_model\": \"qwen3-32b\","
+    "             \"models\": [\"qwen3-32b\", \"my-vl\"]}"
+    "},"
+    "\"models\": ["
+    "  {\"match\": \"qwen3\", \"context\": 32768},"
+    "  {\"match\": \"my-vl\", \"vision\": true, \"price\": {\"miss\": 1,"
+    "   \"out\": 2, \"currency\": \"¥\"}}"
+    "]}";
+
+static void test_user(void) {
+  char err[256];
+  EXPECT(cst_models_load_json(cst_models_builtin_json(), USER_JSON, err,
+                              sizeof(err)) == 0,
+         "load with user file");
+  const cst_provider_t *ds = cst_provider_find("deepseek");
+  EXPECT(ds && strcmp(ds->api_base, "https://proxy.example/v1") == 0 &&
+             strcmp(ds->model, "deepseek-flash") == 0 &&
+             strcmp(cst_provider_source(ds), "user") == 0,
+         "user overrides one field, keeps the rest");
+  const cst_provider_t *lp = cst_provider_find("local");
+  EXPECT(lp && strcmp(lp->model, "qwen3-32b") == 0 &&
+             strcmp(lp->key_env, "LOCAL_KEY") == 0,
+         "user adds a provider");
+  EXPECT(cst_provider_at(cst_provider_count() - 1) == lp, "appended last");
+
+  cst_model_info_t mi;
+  cst_model_info("local", "qwen3-32b", &mi);
+  EXPECT(mi.context == 32768 && strcmp(mi.source, "user") == 0,
+         "user rule beats built-in qwen");
+  cst_model_info("local", "my-vl", &mi);
+  EXPECT(mi.vision == 1 && mi.has_price && mi.price.hit == 1 &&
+             mi.price.write == 1 && strcmp(mi.price.currency, "¥") == 0,
+         "user price, hit/write default to miss");
+
+  /* passback follows the provider name even behind a proxy base */
+  cst_model_caps_t caps;
+  cst_model_caps("deepseek", "https://proxy.example/v1", "deepseek-flash",
+                 &caps);
+  EXPECT(caps.reasoning_passback && caps.prefix_completion, "caps by name");
+
+  char names[32][128];
+  int n = cst_models_list(NULL, names, 32);
+  int seen = 0;
+  for (int i = 0; i < n; i++)
+    seen += strcmp(names[i], "my-vl") == 0;
+  EXPECT(seen == 1, "picker list includes user models");
+
+  EXPECT(cst_models_load_json(cst_models_builtin_json(), "{not json", err,
+                              sizeof(err)) != 0 &&
+             err[0],
+         "bad user file reported");
+}
+
+static void test_cache(void) {
+  cst_models_load_json(cst_models_builtin_json(), NULL, NULL, 0);
+  cst_model_meta_t m[3];
+  memset(m, 0, sizeof(m));
+  snprintf(m[0].id, sizeof(m[0].id), "anthropic/claude-sonnet-4");
+  m[0].context = 1000000;
+  m[0].vision = -1;
+  snprintf(m[1].id, sizeof(m[1].id), "deepseek-flash");
+  m[1].vision = 1; /* API claims vision */
+  m[1].has_price = 1;
+  m[1].miss = 0.5;
+  m[1].hit = 0.1;
+  m[1].write = 0.5;
+  m[1].out = 1;
+  snprintf(m[2].id, sizeof(m[2].id), "brand-new");
+  m[2].vision = -1;
+  EXPECT(cst_models_cache_save("teamorouter", "https://x/v1", m, 3) == 0,
+         "cache saved");
+
+  cst_model_info_t mi;
+  cst_model_info("teamorouter", "anthropic/claude-sonnet-4", &mi);
+  EXPECT(mi.context == 1000000, "API context beats built-in");
+  EXPECT(mi.vision == 1 && mi.cache_style == CST_CACHE_ANTHROPIC,
+         "missing API fields fall through to built-in");
+  EXPECT(strcmp(mi.source, "api+built-in") == 0, "source lists both");
+  cst_model_info("teamorouter", "deepseek-flash", &mi);
+  EXPECT(mi.vision == 1 && mi.price.miss == 0.5 &&
+             strcmp(mi.price.currency, "$") == 0,
+         "API vision and USD price");
+  cst_model_info("deepseek", "deepseek-flash", &mi);
+  EXPECT(mi.price.miss == 2.0 && strcmp(mi.price.currency, "¥") == 0,
+         "another provider's cache is not used");
+  EXPECT(cst_model_context_tokens("anthropic/claude-sonnet-4") == 1000000,
+         "no provider: any cache, exact id");
+
+  cst_model_meta_t back[8];
+  long age = -1;
+  int n = cst_models_cache_load("teamorouter", back, 8, &age);
+  EXPECT(n == 3 && age >= 0 && age < 60 &&
+             strcmp(back[2].id, "brand-new") == 0,
+         "cache reads back");
+  EXPECT(cst_models_cache_load("openai", back, 8, &age) == -1, "no cache");
+  EXPECT(cst_models_cache_save("../evil", NULL, m, 1) != 0,
+         "provider name cannot leave the cache dir");
+
+  /* a fresh process (reload) sees the file */
+  cst_models_reload();
+  cst_model_info("teamorouter", "anthropic/claude-sonnet-4", &mi);
+  EXPECT(mi.context == 1000000, "cache survives a reload");
+}
+
+static void test_env(void) {
+  cst_models_load_json(cst_models_builtin_json(), NULL, NULL, 0);
+  setenv("CST_CTX_TOKENS", "4242", 1);
+  setenv("CST_PRICE", "1,0.5,3", 1);
+  cst_model_info_t mi;
+  cst_model_info(NULL, "deepseek-flash", &mi);
+  EXPECT(mi.context == 4242 && mi.price.miss == 1 && mi.price.write == 1 &&
+             strstr(mi.source, "env"),
+         "env overrides");
+  unsetenv("CST_CTX_TOKENS");
+  unsetenv("CST_PRICE");
+  setenv("CST_NO_CACHE_HINTS", "1", 1);
+  cst_model_caps_t caps;
+  cst_model_caps("openai", NULL, "gpt-4.1", &caps);
+  EXPECT(caps.cache_style == CST_CACHE_AUTO && caps.vision == 1,
+         "no cache hints, vision kept");
+  unsetenv("CST_NO_CACHE_HINTS");
+  setenv("CST_MODELS", "a, b:c", 1);
+  char names[8][128];
+  int n = cst_models_list("cur", names, 8);
+  EXPECT(n == 4 && strcmp(names[1], "b") == 0 && strcmp(names[3], "cur") == 0,
+         "CST_MODELS list");
+  unsetenv("CST_MODELS");
+}
+
+int main(void) {
+  char root[1024];
+  if (test_tmpdir(root, sizeof(root), "cst-models") != 0) {
+    fprintf(stderr, "cannot create a scratch dir\n");
+    return 1;
+  }
+  setenv("XDG_CONFIG_HOME", root, 1); /* no real models.json or caches */
+  unsetenv("CST_CTX_TOKENS");
+  unsetenv("CST_PRICE");
+  unsetenv("CST_MODELS");
+  unsetenv("CST_NO_CACHE_HINTS");
+  test_builtin();
+  test_user();
+  test_cache();
+  test_env();
+  test_rmrf(root);
+  if (nfail) {
+    fprintf(stderr, "test_model_registry: %d failed\n", nfail);
+    return 1;
+  }
+  printf("test_model_registry: OK\n");
+  return 0;
+}

tests/test_models.c

@@ -3,6 +3,8 @@
 #endif
 
 #include "cst_agent.h"
+#include "cst_models.h"
+#include "os_compat.h"
 
 #include <stdio.h>
 #include <stdlib.h>
@@ -72,6 +74,52 @@ static int start_server(void) {
   "Connection: close\r\n\r\n" body
 
 int main(void) {
+  char cfgdir[1024];
+  CHECK(test_tmpdir(cfgdir, sizeof(cfgdir), "cst-models-cfg") == 0);
+  setenv("XDG_CONFIG_HOME", cfgdir, 1); /* ignore a real models-cache */
+  const cst_provider_t *tr = cst_provider_find("teamorouter");
+  CHECK(tr && strcmp(tr->api_base, "https://api.teamorouter.com/v1") == 0);
+  CHECK(tr->model[0] == 0); /* picked from GET /models */
+  CHECK(cst_model_context_tokens("anthropic/claude-sonnet-4") == 200000);
+  CHECK(cst_model_context_tokens("deepseek-flash") == 1000000);
+  CHECK(cst_model_context_tokens("deepseek/deepseek-v4-pro") == 1000000);
+  CHECK(cst_model_context_tokens("google/gemini-2.5-pro") == 1048576);
+  CHECK(cst_model_context_tokens("unknown-model") == 128000);
+
+  cst_model_caps_t caps;
+  cst_model_caps("deepseek", "https://api.deepseek.com/v1", "deepseek-flash",
+                 &caps);
+  CHECK(caps.reasoning_passback && caps.prefix_completion);
+  CHECK(caps.cache_style == CST_CACHE_AUTO);
+  cst_model_caps("teamorouter", "https://api.teamorouter.com/v1",
+                 "deepseek-flash", &caps);
+  CHECK(!caps.reasoning_passback && !caps.prefix_completion);
+  cst_model_caps("teamorouter", NULL, "anthropic/claude-sonnet-4", &caps);
+  CHECK(caps.cache_style == CST_CACHE_ANTHROPIC);
+  cst_model_caps("openai", NULL, "gpt-4.1", &caps);
+  CHECK(caps.cache_style == CST_CACHE_OPENAI);
+  cst_model_caps("openai", NULL, "o3-mini", &caps);
+  CHECK(caps.cache_style == CST_CACHE_OPENAI);
+  cst_model_caps("minimax", NULL, "MiniMax-M2", &caps);
+  CHECK(caps.cache_style == CST_CACHE_AUTO);
+
+  /* Beijing time: Thu 10:00 peak, Thu 13:00 and Sat 10:00 off-peak */
+  CHECK(cst_price_is_peak((time_t)1791424800));
+  CHECK(!cst_price_is_peak((time_t)1791435600));
+  CHECK(!cst_price_is_peak((time_t)1791597600));
+  cst_price_t pr;
+  CHECK(cst_model_price("deepseek-flash", &pr) == 0);
+  CHECK(pr.offpeak_half && pr.hit < pr.miss);
+  double peak = cst_price_cost(&pr, 1000000, 1000000, 0, 1000000,
+                               (time_t)1791424800);
+  CHECK(peak > 9.99 && peak < 10.05); /* 2 + 0.04 + 8 */
+  double off = cst_price_cost(&pr, 1000000, 1000000, 0, 1000000,
+                              (time_t)1791435600);
+  CHECK(off > peak / 2 - 0.001 && off < peak / 2 + 0.001);
+  CHECK(cst_model_price("anthropic/claude-sonnet-4", &pr) == 0);
+  CHECK(pr.write > pr.miss && strcmp(pr.currency, "$") == 0);
+  CHECK(cst_model_price("MiniMax-M2", &pr) != 0);
+
   g_responses[0] = RESP("200 OK", "{\"object\":\"list\",\"data\":["
                                   "{\"id\":\"deepseek-flash\"},"
                                   "{\"id\":\"deepseek-v4-pro\"},"
@@ -81,7 +129,21 @@ int main(void) {
   g_responses[3] = RESP("200 OK", "{\"models\":[{\"name\":\"m1\"},"
                                   "{\"name\":\"m2\"}]}");
   g_responses[4] = RESP("500 Internal Server Error", "{}");
-  g_nresp = 5;
+  /* OpenRouter-style metadata; prices are USD per token, as strings */
+  g_responses[5] = RESP(
+      "200 OK",
+      "{\"data\":[{\"id\":\"anthropic/claude-sonnet-4\","
+      "\"context_length\":1000000,"
+      "\"architecture\":{\"input_modalities\":[\"text\",\"image\"]},"
+      "\"pricing\":{\"prompt\":\"0.000003\",\"completion\":\"0.000015\","
+      "\"input_cache_read\":\"0.0000003\"}},"
+      "{\"id\":\"old/text-model\","
+      "\"architecture\":{\"modality\":\"text->text\"},"
+      "\"pricing\":{\"prompt\":\"-1\",\"completion\":\"-1\"}},"
+      "{\"id\":\"vllm-model\",\"max_model_len\":32768,"
+      "\"modalities\":{\"input\":[\"text\"]}},"
+      "{\"id\":\"plain\"}]}");
+  g_nresp = 6;
   int port = start_server();
   pthread_t th;
   CHECK(pthread_create(&th, NULL, serve, NULL) == 0);
@@ -112,6 +174,17 @@ int main(void) {
   n = cst_llm_list_models(base, "sk-test", ids, 8, err, sizeof(err));
   CHECK(n == -1 && strstr(err, "500") != NULL);
 
+  cst_model_meta_t meta[8];
+  n = cst_llm_list_models_meta(base, "sk-test", meta, 8, err, sizeof(err));
+  CHECK(n == 4);
+  CHECK(meta[0].context == 1000000 && meta[0].vision == 1);
+  CHECK(meta[0].has_price && meta[0].miss > 2.99 && meta[0].miss < 3.01 &&
+        meta[0].out > 14.99 && meta[0].out < 15.01 && meta[0].hit < 0.31 &&
+        meta[0].write == meta[0].miss);
+  CHECK(meta[1].vision == 0 && !meta[1].has_price && meta[1].context == 0);
+  CHECK(meta[2].context == 32768 && meta[2].vision == 0);
+  CHECK(meta[3].vision == -1 && meta[3].context == 0 && !meta[3].has_price);
+
   pthread_join(th, NULL);
   test_sock_close(g_listen);
 
@@ -119,6 +192,7 @@ int main(void) {
   n = cst_llm_list_models(base, "sk-test", ids, 8, err, sizeof(err));
   CHECK(n == -1);
 
+  test_rmrf(cfgdir);
   puts("test_models: ok");
   return 0;
 }

tests/test_prefix_stable.c

@@ -0,0 +1,392 @@
+#define _POSIX_C_SOURCE 200809L
+
+#include "cJSON.h"
+#include "cst_agent.h"
+#include "cst_util.h"
+#include "os_compat.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+#include "cst_test_util.h"
+
+/* Runs a few replayed turns (tool call, Plan mode on, approval change, a
+ * reply cut off by max tokens) and checks the recorded request bodies: every
+ * request must extend the previous one byte for byte, so the provider's
+ * prefix cache keeps hitting. */
+
+static int nfail;
+
+#define EXPECT(cond, msg)                                                      \
+  do {                                                                         \
+    if (!(cond)) {                                                             \
+      fprintf(stderr, "FAIL %s:%d: %s\n", __FILE__, __LINE__, msg);            \
+      nfail++;                                                                 \
+    }                                                                          \
+  } while (0)
+
+#define USAGE                                                                  \
+  "data: {\"choices\":[],\"usage\":{\"prompt_tokens\":1000,"                   \
+  "\"completion_tokens\":20,\"prompt_cache_hit_tokens\":900,"                  \
+  "\"prompt_cache_miss_tokens\":100}}\n\n"                                     \
+  "data: [DONE]\n\n"
+
+#define TOOL(id, name, args)                                                   \
+  "data: {\"choices\":[{\"index\":0,\"delta\":{\"tool_calls\":[{\"index\":0,"  \
+  "\"id\":\"" id "\",\"type\":\"function\",\"function\":{\"name\":\"" name     \
+  "\",\"arguments\":\"" args "\"}}]},\"finish_reason\":null}]}\n\n"            \
+  "data: {\"choices\":[{\"index\":0,\"delta\":{},\"finish_reason\":"           \
+  "\"tool_calls\"}]}\n\n" USAGE
+
+#undef TEXT /* <windows.h> has one */
+#define TEXT(s, finish)                                                        \
+  "data: {\"choices\":[{\"index\":0,\"delta\":{\"content\":\"" s "\"},"        \
+  "\"finish_reason\":null}]}\n\n"                                              \
+  "data: {\"choices\":[{\"index\":0,\"delta\":{},\"finish_reason\":\"" finish  \
+  "\"}]}\n\n" USAGE
+
+#define THINK(s)                                                               \
+  "data: {\"choices\":[{\"index\":0,\"delta\":{\"reasoning_content\":\"" s     \
+  "\"},\"finish_reason\":null}]}\n\n"
+
+static const char *FIXTURES[] = {
+    /* turn 1 */
+    THINK("look at the file") TOOL("c1", "read_file", "{\\\"path\\\":\\\"a.txt\\\"}"),
+    TEXT("done one", "stop"),
+    /* turn 2, Plan mode */
+    TOOL("c2", "write_file",
+         "{\\\"path\\\":\\\"b.txt\\\",\\\"content\\\":\\\"x\\\"}"),
+    TEXT("plan reply", "stop"),
+    /* turn 3, Build mode + yolo; cut off, then continued */
+    TEXT("part one", "length"),
+    TEXT(" part two", "stop"),
+    /* turn 4 */
+    TEXT("bye", "stop"),
+};
+#define NFIX ((int)(sizeof(FIXTURES) / sizeof(FIXTURES[0])))
+
+static void write_file(const char *dir, const char *name, const char *body) {
+  char p[2048];
+  snprintf(p, sizeof(p), "%s/%s", dir, name);
+  FILE *fp = fopen(p, "wb");
+  EXPECT(fp != NULL, "write fixture");
+  if (fp) {
+    fputs(body, fp);
+    fclose(fp);
+  }
+}
+
+static cJSON *load_req(const char *dir, int seq) {
+  char p[2048];
+  snprintf(p, sizeof(p), "%s/%04d.req.json", dir, seq);
+  FILE *fp = fopen(p, "rb");
+  if (!fp)
+    return NULL;
+  cst_buf_t b = {0};
+  char buf[4096];
+  size_t n;
+  while ((n = fread(buf, 1, sizeof(buf), fp)) > 0)
+    cst_buf_append(&b, buf, n);
+  fclose(fp);
+  cJSON *j = b.buf ? cJSON_Parse(b.buf) : NULL;
+  cst_buf_free(&b);
+  return j;
+}
+
+static const cJSON *msgs_of(const cJSON *req) {
+  return cJSON_GetObjectItemCaseSensitive(req, "messages");
+}
+
+static int is_prefix_msg(const cJSON *m) {
+  return cJSON_IsTrue(cJSON_GetObjectItemCaseSensitive(m, "prefix"));
+}
+
+static const char *str_of(const cJSON *o, const char *key) {
+  const cJSON *v = cJSON_GetObjectItemCaseSensitive(o, key);
+  return cJSON_IsString(v) ? v->valuestring : NULL;
+}
+
+static char *print(const cJSON *j) { return j ? cJSON_PrintUnformatted(j) : NULL; }
+
+/* messages of `a` (minus a request-only prefix message) start `b` */
+static int extends(const cJSON *a, const cJSON *b) {
+  const cJSON *ma = msgs_of(a), *mb = msgs_of(b);
+  int na = cJSON_GetArraySize(ma), nb = cJSON_GetArraySize(mb);
+  if (na > 0 && is_prefix_msg(cJSON_GetArrayItem(ma, na - 1)))
+    na--;
+  if (na > nb)
+    return 0;
+  for (int i = 0; i < na; i++) {
+    char *x = print(cJSON_GetArrayItem(ma, i));
+    char *y = print(cJSON_GetArrayItem(mb, i));
+    int same = x && y && strcmp(x, y) == 0;
+    if (!same)
+      fprintf(stderr, "  message %d differs:\n    %.300s\n    %.300s\n", i,
+              x ? x : "(null)", y ? y : "(null)");
+    free(x);
+    free(y);
+    if (!same)
+      return 0;
+  }
+  return 1;
+}
+
+static const cJSON *last_msg(const cJSON *req) {
+  const cJSON *m = msgs_of(req);
+  return cJSON_GetArrayItem(m, cJSON_GetArraySize(m) - 1);
+}
+
+static int any_msg_has(const cJSON *req, const char *key, const char *needle) {
+  const cJSON *m;
+  cJSON_ArrayForEach(m, msgs_of(req)) {
+    const char *s = str_of(m, key);
+    if (s && strstr(s, needle))
+      return 1;
+  }
+  return 0;
+}
+
+static int run(cst_agent_t *a, const char *text) {
+  char err[512];
+  int rc = cst_agent_run_turn(a, text, err, sizeof(err));
+  if (rc != 0)
+    fprintf(stderr, "  turn \"%s\": %s\n", text, err);
+  return rc;
+}
+
+/* 8-byte PNG signature + IHDR header: enough for the attachment sniffer. */
+static size_t tiny_png(unsigned char *b) {
+  static const unsigned char sig[8] = {0x89, 'P', 'N', 'G', '\r', '\n', 0x1A,
+                                       '\n'};
+  memset(b, 0, 32);
+  memcpy(b, sig, 8);
+  b[11] = 13;
+  memcpy(b + 12, "IHDR", 4);
+  b[19] = 2; /* 2 x 2 */
+  b[23] = 2;
+  return 32;
+}
+
+static int tools_have(const cJSON *req, const char *name) {
+  char *t = print(cJSON_GetObjectItemCaseSensitive(req, "tools"));
+  int has = t && strstr(t, name) != NULL;
+  free(t);
+  return has;
+}
+
+static int has_image_url(const cJSON *req) {
+  char *t = print(msgs_of(req));
+  int has = t && strstr(t, "image_url") != NULL;
+  free(t);
+  return has;
+}
+
+/* A text-only model never sees images or view_image; a model of unknown
+ * vision that answers 400 to an image is retried with notes, and stays
+ * that way so later requests extend the retried one. */
+static void test_vision(const char *root) {
+  char dir[1100], sse[1200], rec[1200];
+  snprintf(dir, sizeof(dir), "%s/vision", root);
+  snprintf(sse, sizeof(sse), "%s/sse", dir);
+  snprintf(rec, sizeof(rec), "%s/rec", dir);
+  os_mkdir_p(sse, 0755);
+  write_file(sse, "0000.sse", TEXT("blind reply", "stop"));
+  write_file(sse, "0001.sse", "{\"error\":{\"message\":\"image input is not "
+                              "supported\"}}");
+  write_file(sse, "0001.status", "400\n");
+  write_file(sse, "0002.sse", TEXT("noted reply", "stop"));
+  write_file(sse, "0003.sse", TEXT("later reply", "stop"));
+  setenv("CST_REPLAY_SSE", sse, 1);
+  setenv("CST_RECORD_SSE", rec, 1);
+  cst_llm_trace_reset();
+
+  unsigned char png[32];
+  size_t pn = tiny_png(png);
+  char err[256];
+
+  cst_agent_config_t cfg;
+  memset(&cfg, 0, sizeof(cfg));
+  snprintf(cfg.workspace_root, sizeof(cfg.workspace_root), "%s", root);
+  snprintf(cfg.session_path, sizeof(cfg.session_path), "%s/blind.jsonl", dir);
+  snprintf(cfg.api_base, sizeof(cfg.api_base), "http://replay/v1");
+  snprintf(cfg.model, sizeof(cfg.model), "deepseek-v4-pro");
+  snprintf(cfg.provider, sizeof(cfg.provider), "deepseek");
+  cfg.protocol = CST_PROTO_NATIVE_EOS;
+  cfg.max_steps = 4;
+  cfg.headless = 1;
+  cfg.approval = CST_APPROVAL_AUTO;
+  cst_agent_t *a = cst_agent_create(&cfg);
+  EXPECT(a != NULL, "blind agent");
+  if (!a)
+    return;
+  EXPECT(cst_agent_sees_images(a) == 0, "deepseek-v4-pro is text only");
+  EXPECT(cst_agent_attach_bytes(a, "shot.png", (const char *)png, pn, err,
+                                sizeof(err)) == 0,
+         "attach to a blind model");
+  EXPECT(run(a, "what is in the picture?") == 0, "blind turn");
+  cst_agent_destroy(a);
+
+  snprintf(cfg.session_path, sizeof(cfg.session_path), "%s/unknown.jsonl",
+           dir);
+  snprintf(cfg.model, sizeof(cfg.model), "mystery-model-9");
+  snprintf(cfg.provider, sizeof(cfg.provider), "teamorouter");
+  a = cst_agent_create(&cfg);
+  EXPECT(a != NULL, "unknown-vision agent");
+  if (!a)
+    return;
+  EXPECT(cst_agent_sees_images(a) != 0, "unknown vision: images are tried");
+  EXPECT(cst_agent_attach_bytes(a, "shot.png", (const char *)png, pn, err,
+                                sizeof(err)) == 0,
+         "attach to an unknown model");
+  EXPECT(run(a, "describe it") == 0, "400 retried without images");
+  EXPECT(run(a, "and now?") == 0, "next turn");
+  cst_agent_destroy(a);
+
+  cJSON *r[4];
+  for (int i = 0; i < 4; i++) {
+    r[i] = load_req(rec, i);
+    EXPECT(r[i] != NULL, "vision request recorded");
+  }
+  if (r[0] && r[1] && r[2] && r[3]) {
+    EXPECT(!tools_have(r[0], "view_image"), "blind: no view_image tool");
+    EXPECT(!has_image_url(r[0]), "blind: no image part");
+    const char *c = str_of(last_msg(r[0]), "content");
+    EXPECT(c && strstr(c, "what is in the picture?") &&
+               strstr(c, "not sent: this model does not take images"),
+           "blind: the image becomes a note");
+
+    EXPECT(tools_have(r[1], "view_image") && has_image_url(r[1]),
+           "unknown: first try sends the image");
+    EXPECT(!tools_have(r[2], "view_image") && !has_image_url(r[2]),
+           "retry: no image, no view_image");
+    c = str_of(last_msg(r[2]), "content");
+    EXPECT(c && strstr(c, "not sent"), "retry: note instead");
+    EXPECT(!has_image_url(r[3]) && extends(r[2], r[3]),
+           "images stay off; the next request extends the retry");
+  }
+  for (int i = 0; i < 4; i++)
+    cJSON_Delete(r[i]);
+}
+
+int main(void) {
+  char root[1024], sse[1100], rec[1100];
+  if (test_tmpdir(root, sizeof(root), "cst-prefix") != 0) {
+    fprintf(stderr, "cannot create a scratch dir\n");
+    return 1;
+  }
+  snprintf(sse, sizeof(sse), "%s/sse", root);
+  snprintf(rec, sizeof(rec), "%s/rec", root);
+  os_mkdir_p(sse, 0755);
+  for (int i = 0; i < NFIX; i++) {
+    char name[32];
+    snprintf(name, sizeof(name), "%04d.sse", i);
+    write_file(sse, name, FIXTURES[i]);
+  }
+  write_file(root, "a.txt", "hello\n");
+  setenv("CST_REPLAY_SSE", sse, 1);
+  setenv("CST_RECORD_SSE", rec, 1);
+  setenv("CST_MCP_WAIT_MS", "0", 1);
+  setenv("XDG_CONFIG_HOME", root, 1); /* no real models.json or caches */
+  unsetenv("CST_CTX_WINDOW");
+  unsetenv("CST_NO_CACHE_HINTS");
+  unsetenv("CST_PRICE");
+  cst_llm_trace_reset();
+
+  cst_agent_config_t cfg;
+  memset(&cfg, 0, sizeof(cfg));
+  snprintf(cfg.workspace_root, sizeof(cfg.workspace_root), "%s", root);
+  snprintf(cfg.session_path, sizeof(cfg.session_path), "%s/s.jsonl", root);
+  snprintf(cfg.api_base, sizeof(cfg.api_base), "http://replay/v1");
+  snprintf(cfg.model, sizeof(cfg.model), "deepseek-flash");
+  snprintf(cfg.provider, sizeof(cfg.provider), "deepseek");
+  cfg.protocol = CST_PROTO_NATIVE_EOS;
+  cfg.max_steps = 8;
+  cfg.headless = 1;
+  cfg.approval = CST_APPROVAL_AUTO;
+  cst_agent_t *a = cst_agent_create(&cfg);
+  EXPECT(a != NULL, "agent created");
+  if (!a)
+    return 1;
+
+  EXPECT(run(a, "read a.txt") == 0, "turn 1");
+  cst_agent_config_mut(a)->plan_mode = 1;
+  EXPECT(run(a, "now write b.txt") == 0, "turn 2 (plan)");
+  cst_agent_config_mut(a)->plan_mode = 0;
+  cst_agent_config_mut(a)->approval = CST_APPROVAL_YOLO;
+  EXPECT(run(a, "a long answer please") == 0, "turn 3 (continued)");
+  EXPECT(run(a, "bye") == 0, "turn 4");
+
+  char bpath[1100];
+  snprintf(bpath, sizeof(bpath), "%s/b.txt", root);
+  EXPECT(access(bpath, F_OK) != 0, "Plan mode refused write_file");
+
+  cJSON *req[NFIX];
+  for (int i = 0; i < NFIX; i++) {
+    req[i] = load_req(rec, i);
+    EXPECT(req[i] != NULL, "request recorded");
+  }
+  if (req[NFIX - 1]) {
+    char *tools0 = print(cJSON_GetObjectItemCaseSensitive(req[0], "tools"));
+    char *sys0 = print(cJSON_GetArrayItem(msgs_of(req[0]), 0));
+    EXPECT(tools0 && strstr(tools0, "write_file"),
+           "write tools stay in the schema");
+    for (int i = 0; i < NFIX; i++) {
+      char *tools = print(cJSON_GetObjectItemCaseSensitive(req[i], "tools"));
+      char *sys = print(cJSON_GetArrayItem(msgs_of(req[i]), 0));
+      EXPECT(tools && tools0 && strcmp(tools, tools0) == 0,
+             "tools[] identical in every request");
+      EXPECT(sys && sys0 && strcmp(sys, sys0) == 0,
+             "system prompt identical in every request");
+      const char *tc = str_of(req[i], "tool_choice");
+      EXPECT(tc && strcmp(tc, "auto") == 0, "tool_choice stays auto");
+      free(tools);
+      free(sys);
+      if (i + 1 < NFIX && !extends(req[i], req[i + 1])) {
+        fprintf(stderr, "  request %d does not extend request %d\n", i + 1, i);
+        nfail++;
+      }
+    }
+    free(tools0);
+    free(sys0);
+
+    EXPECT(any_msg_has(req[1], "reasoning_content", "look at the file"),
+           "DeepSeek reasoning passed back");
+    EXPECT(strstr(str_of(last_msg(req[2]), "content"), "Plan mode is now ON"),
+           "Plan mode announced by a note");
+    EXPECT(any_msg_has(req[3], "content", "Plan mode is on"),
+           "write_file denied with a Plan mode error");
+    const char *t3 = str_of(last_msg(req[4]), "content");
+    EXPECT(t3 && strstr(t3, "Plan mode is now OFF") &&
+               strstr(t3, "Approval mode is now yolo"),
+           "Build mode and approval change announced");
+    const cJSON *pm = last_msg(req[5]);
+    EXPECT(is_prefix_msg(pm) && strcmp(str_of(pm, "role"), "assistant") == 0 &&
+               strcmp(str_of(pm, "content"), "part one") == 0,
+           "cut-off reply continued through an assistant prefix");
+    EXPECT(any_msg_has(req[6], "content", "part one part two"),
+           "continued reply stored as one message");
+  }
+  for (int i = 0; i < NFIX; i++)
+    cJSON_Delete(req[i]);
+
+  cst_usage_t s, turn;
+  cst_agent_usage(a, &s, &turn);
+  EXPECT(s.requests == NFIX, "every response counted");
+  EXPECT(s.prompt == 1000L * NFIX && s.cached == 900L * NFIX &&
+             s.miss == 100L * NFIX,
+         "hit and miss tokens summed");
+  EXPECT(s.priced && s.cost > 0 && strcmp(s.currency, "¥") == 0,
+         "DeepSeek cost estimated");
+  EXPECT(turn.requests == 1, "last turn usage");
+
+  cst_agent_destroy(a);
+  test_vision(root);
+  test_rmrf(root);
+  if (nfail) {
+    fprintf(stderr, "test_prefix_stable: %d failed\n", nfail);
+    return 1;
+  }
+  printf("test_prefix_stable: OK\n");
+  return 0;
+}

tests/test_sandbox.c

@@ -72,7 +72,7 @@ static void test_blocked(void) {
   CHECK(cst_sandbox_blocked(c, strlen(c), 1));
   const char *d = "curl: (7) Failed to connect to example.com port 443 after 9 "
                   "ms: Could not connect to server\n";
-  CHECK(cst_sandbox_blocked(d, strlen(d), 7));
+  CHECK(!cst_sandbox_blocked(d, strlen(d), 7)); /* network is not sandboxed */
   const char *e = "Access is denied.\r\n";
   CHECK(cst_sandbox_blocked(e, strlen(e), 1));
   const char *f = "拒绝访问。\r\n";
@@ -132,7 +132,7 @@ static int run(const char *ws, const char *cmd, os_run_result_t *r) {
   return r->exit_code;
 }
 
-/* Child: enter the sandbox, then try a TCP connect to a local listener. */
+/* Child: enter the sandbox, then a TCP connect to a local listener works. */
 static void test_network(const char *ws) {
   int ls = socket(AF_INET, SOCK_STREAM, 0);
   CHECK(ls >= 0);
@@ -152,12 +152,11 @@ static void test_network(const char *ws) {
   if (pid == 0) {
     if (cst_sandbox_enter(&plan) != 0)
       _exit(3);
-    /* Landlock refuses the connect, seccomp already the socket */
     int s = socket(AF_INET, SOCK_STREAM, 0);
     if (s < 0)
-      _exit(errno == EACCES ? 0 : 2);
+      _exit(errno == EACCES ? 1 : 2);
     int rc = connect(s, (struct sockaddr *)&a, sizeof(a));
-    _exit(rc == 0 ? 1 : errno == EACCES ? 0 : 2);
+    _exit(rc == 0 ? 0 : errno == EACCES ? 1 : 2);
   }
   int st = 0;
   waitpid(pid, &st, 0);
@@ -337,11 +336,7 @@ static void test_confined(int kind) {
   CHECK(fp);
   fclose(fp);
 
-  if (kind == CST_SANDBOX_SECCOMP || cst_sandbox_landlock_abi() >= 4)
-    test_network(ws);
-  else
-    printf("test_sandbox: landlock ABI %d < 4, network rule not tested\n",
-           cst_sandbox_landlock_abi());
+  test_network(ws);
 
   snprintf(cmd, sizeof(cmd), "rm -rf '%s' '%s'", ws, out);
   CHECK(system(cmd) == 0);

tests/test_webui.c

@@ -0,0 +1,320 @@
+/* WebUI: the socket/HTTP layer, the SSE framing, auth and the HTML
+ * sanitizer. The full turn path is covered by scripts/e2e_webui.sh, which
+ * runs a recorded stream through a real server. */
+#ifndef _DEFAULT_SOURCE
+#define _DEFAULT_SOURCE
+#endif
+
+#include "cst_http.h"
+#include "cst_net.h"
+#include "cst_util.h"
+#include "cst_web_md.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "cst_test_util.h"
+
+#define CHECK(c)                                                               \
+  do {                                                                         \
+    if (!(c)) {                                                                \
+      fprintf(stderr, "%s:%d: CHECK(%s) failed\n", __FILE__, __LINE__, #c);   \
+      exit(1);                                                                 \
+    }                                                                          \
+  } while (0)
+
+/* --- a tiny HTTP client --------------------------------------------------- */
+
+static os_socket_t connect_to(int port) {
+  char host[32];
+  snprintf(host, sizeof(host), "127.0.0.1");
+  os_socket_t s = os_net_connect(host, port, 3000);
+  CHECK(s != OS_SOCKET_BAD);
+  return s;
+}
+
+/* Sends data, reads until the peer closes (or 5 s pass). malloc'd. */
+static char *roundtrip(int port, const char *req, size_t *out_len) {
+  os_socket_t s = connect_to(port);
+  CHECK(os_net_send_all(s, req, strlen(req), 3000) == 0);
+  cst_buf_t b = {0};
+  char buf[4096];
+  for (;;) {
+    long n = os_net_recv(s, buf, sizeof(buf), 5000);
+    if (n <= 0)
+      break;
+    CHECK(cst_buf_append(&b, buf, (size_t)n) == 0);
+  }
+  os_net_close(s);
+  *out_len = b.len;
+  return cst_buf_steal(&b);
+}
+
+/* Same, but stops as soon as `needle` shows up. */
+
+/* --- handlers ------------------------------------------------------------- */
+
+static int h_hello(cst_http_conn_t *c, void *ud) {
+  (void)ud;
+  return cst_http_send_str(c, 200, "text/plain", "world");
+}
+
+static int h_secret(cst_http_conn_t *c, void *ud) {
+  (void)ud;
+  return cst_http_send_str(c, 200, "text/plain", "secret");
+}
+
+static int h_echo(cst_http_conn_t *c, void *ud) {
+  (void)ud;
+  const cst_http_req_t *r = cst_http_request(c);
+  char head[64];
+  snprintf(head, sizeof(head), "%zu:", r->body_len);
+  cst_buf_t b = {0};
+  cst_buf_puts(&b, head);
+  cst_buf_append(&b, r->body ? r->body : "", r->body_len);
+  int rc = cst_http_send(c, 200, "text/plain", b.buf, b.len);
+  cst_buf_free(&b);
+  return rc;
+}
+
+static int h_events(cst_http_conn_t *c, void *ud) {
+  (void)ud;
+  CHECK(cst_http_stream_begin(c, "text/event-stream") == 0);
+  CHECK(cst_http_stream_write(c, "event: one\ndata: {\"n\":1}\n\n", 26) == 0);
+  CHECK(cst_http_stream_write(c, "event: two\ndata: {\"n\":2}\n\n", 26) == 0);
+  CHECK(cst_http_stream_end(c) == 0);
+  return 0;
+}
+
+static int auth_bearer(const cst_http_req_t *req, void *ud) {
+  const char *want = ud;
+  if (!req->authorization)
+    return -1;
+  if (strncmp(req->authorization, "Bearer ", 7) != 0)
+    return -1;
+  return strcmp(req->authorization + 7, want) == 0 ? 0 : -1;
+}
+
+static void test_http(void) {
+  static const cst_http_route_t routes[] = {
+      {"GET", "/hello", h_hello, NULL, 0, 0},
+      {"GET", "/secret", h_secret, NULL, 1, 0},
+      {"GET", "/events", h_events, NULL, 0, 0},
+      {"POST", "/echo", h_echo, NULL, 0, 4096},
+  };
+  cst_http_opts_t o;
+  memset(&o, 0, sizeof(o));
+  o.host = "127.0.0.1";
+  o.port = 0;
+  o.max_body = 1024 * 1024;
+  o.routes = routes;
+  o.nroutes = (int)(sizeof(routes) / sizeof(routes[0]));
+  o.auth = auth_bearer;
+  o.auth_ud = (void *)"s3cret";
+  char err[256] = "";
+  cst_http_server_t *s = cst_http_start(&o, err, sizeof(err));
+  CHECK(s != NULL);
+  int port = cst_http_port(s);
+  CHECK(port > 0);
+
+  size_t n = 0;
+  char *resp = roundtrip(port, "GET /hello HTTP/1.1\r\nHost: x\r\n"
+                               "Connection: close\r\n\r\n", &n);
+  CHECK(strstr(resp, "200 OK") && strstr(resp, "world"));
+  free(resp);
+
+  /* keep-alive: two requests, one connection */
+  resp = roundtrip(port, "GET /hello HTTP/1.1\r\nHost: x\r\n\r\n"
+                         "GET /hello HTTP/1.1\r\nHost: x\r\n"
+                         "Connection: close\r\n\r\n", &n);
+  CHECK(strstr(resp, "200 OK"));
+  CHECK(strstr(resp, "200 OK") != strrchr(resp, '2')); /* twice */
+  {
+    int hits = 0;
+    for (const char *p = resp; (p = strstr(p, "200 OK")); p++)
+      hits++;
+    CHECK(hits == 2);
+  }
+  free(resp);
+
+  /* auth: without, then with the token */
+  resp = roundtrip(port, "GET /secret HTTP/1.1\r\nHost: x\r\n"
+                         "Connection: close\r\n\r\n", &n);
+  CHECK(strstr(resp, "401"));
+  free(resp);
+  resp = roundtrip(port, "GET /secret HTTP/1.1\r\nHost: x\r\n"
+                         "Authorization: Bearer s3cret\r\n"
+                         "Connection: close\r\n\r\n", &n);
+  CHECK(strstr(resp, "200") && strstr(resp, "secret"));
+  free(resp);
+
+  /* unknown route */
+  resp = roundtrip(port, "GET /nope HTTP/1.1\r\nHost: x\r\n"
+                         "Connection: close\r\n\r\n", &n);
+  CHECK(strstr(resp, "404"));
+  free(resp);
+  /* traversal is rejected before any handler runs */
+  resp = roundtrip(port, "GET /../etc/passwd HTTP/1.1\r\nHost: x\r\n"
+                         "Connection: close\r\n\r\n", &n);
+  CHECK(strstr(resp, "400") || strstr(resp, "404"));
+  free(resp);
+
+  /* a body round trip, and the per-route cap */
+  resp = roundtrip(port, "POST /echo HTTP/1.1\r\nHost: x\r\n"
+                         "Content-Length: 3\r\nConnection: close\r\n\r\nabc", &n);
+  CHECK(strstr(resp, "200") && strstr(resp, "3:abc"));
+  free(resp);
+  {
+    cst_buf_t b = {0};
+    cst_buf_puts(&b, "POST /echo HTTP/1.1\r\nHost: x\r\nContent-Length: 9999\r\n"
+                     "Connection: close\r\n\r\n");
+    for (int i = 0; i < 9999; i++)
+      cst_buf_puts(&b, "a");
+    resp = roundtrip(port, b.buf, &n);
+    CHECK(strstr(resp, "413"));
+    free(resp);
+    cst_buf_free(&b);
+  }
+
+  /* chunked streaming: the client must see the decoded frames */
+  resp = roundtrip(port, "GET /events HTTP/1.1\r\nHost: x\r\n"
+                         "Connection: close\r\n\r\n", &n);
+  CHECK(strstr(resp, "Transfer-Encoding: chunked"));
+  CHECK(strstr(resp, "event: one") && strstr(resp, "event: two"));
+  CHECK(strstr(resp, "\r\n0\r\n\r\n")); /* terminator */
+  free(resp);
+
+  cst_http_stop(s);
+  cst_http_free(s);
+}
+
+/* --- query parsing -------------------------------------------------------- */
+
+static void test_query(void) {
+  cst_http_req_t r;
+  memset(&r, 0, sizeof(r));
+  snprintf(r.query, sizeof(r.query), "token=a%%20b&since=17&x=");
+  char buf[64];
+  CHECK(cst_http_query(&r, "token", buf, sizeof(buf)) == 0);
+  CHECK(strcmp(buf, "a b") == 0);
+  CHECK(cst_http_query(&r, "since", buf, sizeof(buf)) == 0);
+  CHECK(strcmp(buf, "17") == 0);
+  CHECK(cst_http_query(&r, "nope", buf, sizeof(buf)) != 0);
+}
+
+/* --- markdown + sanitizer ------------------------------------------------- */
+
+static cst_buf_t g_md_out;
+
+static int collect_md(const char *html, size_t len, void *ud) {
+  (void)ud;
+  return cst_buf_append(&g_md_out, html, len) == 0 ? 0 : 1;
+}
+
+static void test_sanitize(void) {
+  char *html = cst_web_md_html("**hi** [x](javascript:alert(1)) "
+                               "![i](/api/attach/img-1.png)",
+                               strlen("**hi** [x](javascript:alert(1)) "
+                                      "![i](/api/attach/img-1.png)"));
+  CHECK(html != NULL);
+  CHECK(strstr(html, "<strong>hi</strong>"));
+  CHECK(strstr(html, "javascript:") == NULL);
+  CHECK(strstr(html, "/api/attach/img-1.png"));
+  free(html);
+
+  /* raw markup that sashidown would pass through gets stripped */
+  const char *evil = "<p>ok</p><script>alert(1)</script>"
+                     "<img src=\"http://evil.example/x.png\" alt=\"a\">"
+                     "<a href=\"//evil.example\">l</a>";
+  html = cst_web_md_sanitize(evil, strlen(evil));
+  CHECK(html != NULL);
+  CHECK(strstr(html, "ok"));
+  CHECK(strstr(html, "<script") == NULL);
+  CHECK(strstr(html, "evil.example/x.png") == NULL);
+  CHECK(strstr(html, "//evil.example") == NULL);
+  CHECK(strstr(html, "<a") == NULL); /* an unusable href drops the tag */
+  free(html);
+
+  /* a quote inside a single-quoted or bare value cannot open a new attribute */
+  const char *quoted = "<a href='http://x\" onmouseover=\"alert(1)'>q</a>"
+                       "<a href=http://y\"onmouseover=alert(2)//>r</a>";
+  html = cst_web_md_sanitize(quoted, strlen(quoted));
+  CHECK(html != NULL);
+  CHECK(strstr(html, "\" onmouseover") == NULL);
+  CHECK(strstr(html, "\"onmouseover") == NULL);
+  CHECK(strstr(html, "&quot;") != NULL);
+  free(html);
+
+  /* streaming: a javascript: link is dropped, a split tag never leaks */
+  {
+    cst_buf_free(&g_md_out);
+    const char *src = "see [x](javascript:alert(1)) and **ok**";
+    cst_web_md_t *md = cst_web_md_new(collect_md, NULL);
+    CHECK(md != NULL);
+    CHECK(cst_web_md_feed(md, src, 4) == 0); /* a deliberately split tag */
+    CHECK(cst_web_md_feed(md, src + 4, strlen(src) - 4) == 0);
+    CHECK(cst_web_md_finish(md) == 0);
+    cst_web_md_free(md);
+    const char *out = g_md_out.buf ? g_md_out.buf : "";
+    CHECK(strstr(out, "javascript:") == NULL);
+    CHECK(strstr(out, "href") == NULL);
+    CHECK(strstr(out, "see"));
+    CHECK(strstr(out, "<strong>ok</strong>") != NULL);
+    cst_buf_free(&g_md_out);
+  }
+  {
+    /* and the same text fed one byte at a time still comes out whole */
+    cst_buf_free(&g_md_out);
+    const char *md_src = "**bold** and [ok](https://example.com)";
+    cst_web_md_t *md = cst_web_md_new(collect_md, NULL);
+    CHECK(md != NULL);
+    for (size_t i = 0; i < strlen(md_src); i++)
+      CHECK(cst_web_md_feed(md, md_src + i, 1) == 0);
+    CHECK(cst_web_md_finish(md) == 0);
+    cst_web_md_free(md);
+    CHECK(strstr(g_md_out.buf, "<strong>bold</strong>"));
+    CHECK(strstr(g_md_out.buf, "https://example.com"));
+    CHECK(strstr(g_md_out.buf, "noopener") != NULL);
+    cst_buf_free(&g_md_out);
+  }
+}
+
+/* Streamed deltas cut anywhere must reach the browser as whole characters. */
+static void test_utf8_hold(void) {
+  const char *src = "思考：先读 main.c，再改 😀 emoji。";
+  size_t len = strlen(src);
+  for (size_t step = 1; step <= 5; step++) {
+    cst_utf8_hold_t h = {0};
+    cst_buf_t out = {0};
+    for (size_t i = 0; i < len; i += step) {
+      size_t n = len - i < step ? len - i : step;
+      size_t got = 0;
+      char *piece = cst_utf8_hold_feed(&h, src + i, n, &got);
+      CHECK(piece != NULL);
+      CHECK(h.n < 4);
+      CHECK(cst_utf8_valid(piece, got));
+      CHECK(cst_buf_append(&out, piece, got) == 0);
+      free(piece);
+    }
+    CHECK(h.n == 0);
+    CHECK(out.len == len && memcmp(out.buf, src, len) == 0);
+    cst_buf_free(&out);
+  }
+  /* a stray continuation byte is not held forever */
+  cst_utf8_hold_t h = {0};
+  size_t got = 0;
+  char *piece = cst_utf8_hold_feed(&h, "\x80\x80\x80\x80", 4, &got);
+  CHECK(piece && got == 4 && h.n == 0);
+  free(piece);
+}
+
+int main(void) {
+  CHECK(os_net_init() == 0);
+  test_utf8_hold();
+  test_query();
+  test_sanitize();
+  test_http();
+  printf("test_webui: OK\n");
+  return 0;
+}

web/index.html

@@ -0,0 +1,231 @@
+<!DOCTYPE html>
+<html lang="zh-CN" data-theme="dark">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+<meta name="color-scheme" content="dark light">
+<title>CST-Agent</title>
+<link rel="stylesheet" href="style.css">
+</head>
+<body>
+<!-- one icon set, drawn as a sprite so every glyph shares the same 24px grid,
+     stroke weight and round caps: mixed emoji/unicode never looks like a family -->
+<svg id="atlas" aria-hidden="true" hidden>
+  <symbol id="i-menu" viewBox="0 0 24 24"><path d="M4 7h16M4 12h16M4 17h16"/></symbol>
+  <symbol id="i-panel-left" viewBox="0 0 24 24"><rect x="3.5" y="5" width="17" height="14" rx="3"/><path d="M9.5 5v14"/></symbol>
+  <symbol id="i-panel-right" viewBox="0 0 24 24"><rect x="3.5" y="5" width="17" height="14" rx="3"/><path d="M14.5 5v14"/></symbol>
+  <symbol id="i-chevron" viewBox="0 0 24 24"><path d="M6 9.5l6 5 6-5"/></symbol>
+  <symbol id="i-plus" viewBox="0 0 24 24"><path d="M12 5v14M5 12h14"/></symbol>
+  <symbol id="i-refresh" viewBox="0 0 24 24"><path d="M20 12a8 8 0 1 1-2.6-5.9M20 4.5V9h-4.5"/></symbol>
+  <symbol id="i-settings" viewBox="0 0 24 24"><path d="M4 6.5h5M15 6.5h5M4 12h7M17 12h3M4 17.5h5M15 17.5h5"/><circle cx="11.5" cy="6.5" r="2"/><circle cx="15" cy="12" r="2"/><circle cx="11.5" cy="17.5" r="2"/></symbol>
+  <symbol id="i-moon" viewBox="0 0 24 24"><path d="M20 14.6A8.6 8.6 0 0 1 9.4 4 8.6 8.6 0 1 0 20 14.6z"/></symbol>
+  <symbol id="i-sun" viewBox="0 0 24 24"><circle cx="12" cy="12" r="4.2"/><path d="M12 2.5v2.2M12 19.3v2.2M2.5 12h2.2M19.3 12h2.2M5.2 5.2l1.6 1.6M17.2 17.2l1.6 1.6M18.8 5.2l-1.6 1.6M6.8 17.2l-1.6 1.6"/></symbol>
+  <symbol id="i-more" viewBox="0 0 24 24"><circle cx="5.5" cy="12" r="1.6" class="f"/><circle cx="12" cy="12" r="1.6" class="f"/><circle cx="18.5" cy="12" r="1.6" class="f"/></symbol>
+  <symbol id="i-send" viewBox="0 0 24 24"><path d="M12 19.5V5M5.8 11.2 12 5l6.2 6.2"/></symbol>
+  <symbol id="i-stop" viewBox="0 0 24 24"><rect x="7" y="7" width="10" height="10" rx="2.5" class="f"/></symbol>
+  <symbol id="i-image" viewBox="0 0 24 24"><rect x="3.5" y="5" width="17" height="14" rx="3"/><path d="M4 15.5 8.6 11l4 4 2.8-2.8L20.5 16"/><circle cx="9" cy="9.4" r="1.5"/></symbol>
+  <symbol id="i-clipboard" viewBox="0 0 24 24"><rect x="8.5" y="3.5" width="7" height="4" rx="1.6"/><path d="M15.5 5.5h3v15h-13v-15h3M9 12h6M9 15.5h4"/></symbol>
+  <symbol id="i-list" viewBox="0 0 24 24"><path d="M4 6.8h2M4 12h2M4 17.2h2M9 6.8h11M9 12h11M9 17.2h11"/></symbol>
+  <symbol id="i-copy" viewBox="0 0 24 24"><rect x="8.5" y="8.5" width="11" height="11" rx="2.6"/><path d="M15.5 8.5V7a2.5 2.5 0 0 0-2.5-2.5H6.5A2.5 2.5 0 0 0 4 7v6.5A2.5 2.5 0 0 0 6.5 16h1.5"/></symbol>
+  <symbol id="i-compress" viewBox="0 0 24 24"><path d="M8 3.5V9H3M16 20.5V15h5M3 9h4M16 15h5"/></symbol>
+  <symbol id="i-undo" viewBox="0 0 24 24"><path d="M9.5 5.5 4 11l5.5 5.5"/><path d="M4 11h10.2a5.2 5.2 0 0 1 0 10.4H8.5"/></symbol>
+  <symbol id="i-close" viewBox="0 0 24 24"><path d="M6.5 6.5l11 11M17.5 6.5l-11 11"/></symbol>
+  <symbol id="i-check" viewBox="0 0 24 24"><path d="M5 12.6l4.6 4.6L19 7.6"/></symbol>
+  <symbol id="i-shield" viewBox="0 0 24 24"><path d="M12 3.5 5 6.2v5.4c0 4.2 2.9 7.5 7 8.9 4.1-1.4 7-4.7 7-8.9V6.2z"/></symbol>
+  <symbol id="i-bolt" viewBox="0 0 24 24"><path d="M13.4 3 5.5 13.6H11l-.9 7.4L18.5 10H13z"/></symbol>
+  <symbol id="i-alert" viewBox="0 0 24 24"><path d="M12 4 2.8 20h18.4z"/><path d="M12 10v4.4M12 17.2v.2"/></symbol>
+  <symbol id="i-cpu" viewBox="0 0 24 24"><rect x="7" y="7" width="10" height="10" rx="2.6"/><path d="M10 3v4M14 3v4M10 17v4M14 17v4M3 10h4M3 14h4M17 10h4M17 14h4"/></symbol>
+  <symbol id="i-lv1" viewBox="0 0 24 24"><path d="M5 18.5V13h3.4v5.5z" class="f"/></symbol>
+  <symbol id="i-lv2" viewBox="0 0 24 24"><path d="M5 18.5V13h3.4v5.5zM10.3 18.5V9.6h3.4v8.9z" class="f"/></symbol>
+  <symbol id="i-lv3" viewBox="0 0 24 24"><path d="M5 18.5V13h3.4v5.5zM10.3 18.5V9.6h3.4v8.9zM15.6 18.5V6.4h3.4v12.1z" class="f"/></symbol>
+  <symbol id="i-lv4" viewBox="0 0 24 24"><path d="M4 18.5V13h2.6v5.5zM8.7 18.5V10h2.6v8.5zM13.4 18.5V6.8h2.6v11.7zM18.1 18.5V4h2.6v14.5z" class="f"/></symbol>
+  <symbol id="i-file" viewBox="0 0 24 24"><path d="M13.5 3.5H7A2.5 2.5 0 0 0 4.5 6v12A2.5 2.5 0 0 0 7 20.5h10A2.5 2.5 0 0 0 19.5 18V9.5z"/><path d="M13.5 3.5v6h6"/></symbol>
+  <symbol id="i-clock" viewBox="0 0 24 24"><circle cx="12" cy="12" r="8.5"/><path d="M12 7.2V12l3.2 2"/></symbol>
+  <symbol id="i-folder" viewBox="0 0 24 24"><path d="M3.5 6.5A1.5 1.5 0 0 1 5 5h4l2 2.5h8A1.5 1.5 0 0 1 20.5 9v9A1.5 1.5 0 0 1 19 19.5H5A1.5 1.5 0 0 1 3.5 18z"/></symbol>
+</svg>
+
+<div id="app">
+
+  <!-- rail: identity, one primary action, sessions, identity again.
+       Everything else is a popover anchored where it belongs. -->
+  <aside id="side">
+   <div class="side-inner">
+    <div class="side-head">
+      <div class="brand">
+        <span class="brand-name">CST-Agent</span>
+      </div>
+      <button id="btn-collapse" class="icon" title="收起侧栏 (Ctrl+B)">
+        <svg class="i"><use href="#i-panel-left"/></svg>
+      </button>
+    </div>
+
+    <button id="btn-new" class="new-task">
+      <svg class="i"><use href="#i-plus"/></svg><span>新建任务</span>
+    </button>
+
+    <div class="side-sec">
+      <span>最近</span>
+      <button id="btn-refresh-sessions" class="icon tiny" title="刷新">
+        <svg class="i"><use href="#i-refresh"/></svg>
+      </button>
+    </div>
+    <div id="sessions-list" class="sessions"></div>
+
+    <div class="side-foot">
+      <div class="who">
+        <span class="avatar">C</span>
+        <span class="who-text">
+          <b id="foot-ws">workspace</b>
+          <i id="foot-session">-</i>
+        </span>
+      </div>
+      <button id="btn-settings" class="icon" title="设置">
+        <svg class="i"><use href="#i-settings"/></svg>
+      </button>
+    </div>
+   </div>
+  </aside>
+
+  <!-- main column -->
+  <main id="main">
+    <header id="topbar">
+      <button id="btn-side" class="icon" title="展开侧栏 (Ctrl+B)">
+        <svg class="i"><use href="#i-panel-left"/></svg>
+      </button>
+      <button id="btn-drawer" class="icon only-narrow" title="侧栏">
+        <svg class="i"><use href="#i-menu"/></svg>
+      </button>
+      <button id="chip-model" class="chip model" title="模型与推理强度">
+        <svg class="i"><use href="#i-cpu"/></svg><span class="lbl">-</span>
+        <svg class="i chev"><use href="#i-chevron"/></svg>
+      </button>
+      <span class="grow"></span>
+      <div class="seg" id="seg-mode" title="计划模式只读，不改文件">
+        <button data-mode="build">构建</button>
+        <button data-mode="plan">计划</button>
+      </div>
+      <button id="chip-approval" class="chip quiet" title="审批权限">
+        <svg class="i"><use href="#i-shield"/></svg><span class="lbl">auto</span>
+        <svg class="i chev"><use href="#i-chevron"/></svg>
+      </button>
+      <button id="btn-theme" class="icon" title="明暗切换">
+        <svg class="i only-dark"><use href="#i-moon"/></svg>
+        <svg class="i only-light"><use href="#i-sun"/></svg>
+      </button>
+      <button id="btn-panel" class="icon" title="运行详情 (Ctrl+J)">
+        <svg class="i"><use href="#i-panel-right"/></svg>
+      </button>
+      <button id="btn-menu" class="icon" title="更多">
+        <svg class="i"><use href="#i-more"/></svg>
+      </button>
+    </header>
+
+    <div id="scroll">
+      <section id="empty">
+        <p class="ready">准备好开始构建了吗</p>
+      </section>
+      <div id="log"></div>
+    </div>
+
+    <button id="to-bottom" class="round" hidden title="回到最新">
+      <svg class="i"><use href="#i-chevron"/></svg>
+    </button>
+
+    <footer id="composer">
+      <div id="pending" class="pending" hidden></div>
+
+      <!-- permission gate: inline, the turn really is waiting on it -->
+      <div id="gate" class="gate" hidden>
+        <div class="gate-head">
+          <span class="gate-title" id="gate-title">需要确认</span>
+          <span class="grow"></span>
+          <span class="gate-timer" id="gate-timer"></span>
+        </div>
+        <pre id="gate-detail"></pre>
+        <div class="gate-keys" id="gate-keys"></div>
+        <div class="gate-row" id="gate-buttons"></div>
+      </div>
+
+      <div class="box">
+        <textarea id="input" rows="1" placeholder="给 CST-Agent 派个任务…"></textarea>
+        <div class="box-row">
+          <button id="btn-plus" class="icon att" title="添加图片或计划模式">
+            <svg class="i"><use href="#i-plus"/></svg>
+          </button>
+          <button id="btn-undo" class="chip quiet" title="撤销上一次文件写入">
+            <svg class="i"><use href="#i-undo"/></svg><span>撤销</span>
+          </button>
+          <span class="grow"></span>
+          <button id="cost" class="cost" title="用量详情"></button>
+          <button id="btn-stop" class="icon stop" hidden title="停止">
+            <svg class="i"><use href="#i-stop"/></svg>
+          </button>
+          <button id="btn-send" class="round send" title="发送 (Enter)">
+            <svg class="i"><use href="#i-send"/></svg>
+          </button>
+        </div>
+      </div>
+      <div class="hint-line">
+        <span id="status">就绪</span>
+        <span class="grow"></span>
+        <span id="usage" class="quiet"></span>
+      </div>
+      <input type="file" id="file" accept="image/*" multiple hidden>
+    </footer>
+  </main>
+
+  <!-- right panel: the run, not the chat -->
+  <aside id="panel">
+   <div class="panel-inner">
+    <div class="panel-head">
+      <span>运行详情</span>
+      <span class="grow"></span>
+      <button id="btn-panel-close" class="icon tiny" title="关闭">
+        <svg class="i"><use href="#i-close"/></svg>
+      </button>
+    </div>
+
+    <section class="card" id="card-todo">
+      <h4>任务清单</h4>
+      <div id="todo-body" class="muted">模型还没有给出任务清单。</div>
+    </section>
+
+    <section class="card" id="card-files">
+      <h4>文件改动 <span class="badge" id="files-count">0</span></h4>
+      <div id="files-body" class="muted">本轮还没有改动文件。</div>
+    </section>
+
+    <section class="card">
+      <h4>上下文</h4>
+      <div class="kv"><span>占用</span><b id="kv-ctx">0</b></div>
+      <div class="kv"><span>缓存命中</span><b id="kv-cache">-</b></div>
+    </section>
+   </div>
+  </aside>
+
+</div>
+
+<div id="backdrop"></div>
+<div id="pop" class="pop" hidden></div>
+<div id="modal" hidden><div id="modal-box"></div></div>
+<div id="toast" class="toast" role="status" aria-live="polite" hidden></div>
+<script>
+/* Layout is decided here, before app.js runs and before the first paint: the
+ * rail must not flash open and then fold, and a broken script further down can
+ * no longer take the layout down with it. */
+(() => {
+  const q = new URLSearchParams(location.search);
+  const pick = (key) => {
+    const v = q.get(key);
+    if (v === '0' || v === '1') return v === '0';
+    return localStorage.getItem('cst.' + key) === '0';
+  };
+  if (pick('side')) document.body.classList.add('no-side');
+  if (pick('panel')) document.body.classList.add('no-panel');
+  const t = q.get('theme') || localStorage.getItem('cst.theme');
+  if (t) document.documentElement.dataset.theme = t;
+})();
+</script>
+<script src="app.js"></script>
+</body>
+</html>

web/style.css

@@ -0,0 +1,694 @@
+/* CST-Agent WebUI - one stylesheet, no build step.
+ *
+ * Design rules
+ *   - one fact, one home: sessions in the rail, model/approval/plan in the
+ *     top bar, the run in the right panel, attachments in the composer;
+ *   - settings open as popovers anchored to the control that owns them,
+ *     with icon + label + one line of explanation + a check on the current
+ *     value (the pattern all three reference apps use);
+ *   - motion is short and eased: 120ms for feedback, 180ms for entrances,
+ *     nothing bounces, and prefers-reduced-motion turns it all off. */
+
+/* Tokens are named the way the reference desktop app names them: four text
+ * levels, three surfaces per zone (main / sidebar / composer), and borders
+ * mixed out of the foreground rather than hard-coded greys - which is what
+ * keeps the dark and the light sheet on the same visual rhythm. */
+:root {
+  color-scheme: dark;
+
+  --text-primary: #f2f2f5;
+  --text-secondary: #a9a9b4;
+  --text-tertiary: #7d7d89;
+  --text-quaternary: #5e5e69;
+  --text-error: #f0616d;
+  --text-success: #3ecf95;
+
+  --main-surface-primary: #0d0d0f;
+  --main-surface-secondary: #141417;
+  --main-surface-tertiary: #1d1d22;
+
+  --sidebar-surface-primary: #111114;
+  --sidebar-surface-secondary: #18181c;
+  --sidebar-surface-tertiary: #202026;
+
+  --composer-surface-primary: #16161a;
+  --composer-surface-secondary: #202026;
+
+  --bg-code: #08080a;
+
+  /* every hover/active tint is alpha, so it lands correctly on any surface */
+  --hover: color-mix(in srgb, var(--text-primary) 7%, transparent);
+  --hover-strong: color-mix(in srgb, var(--text-primary) 13%, transparent);
+
+  --accent-primary: #3ecf95;
+  --accent-fg: #04241a;
+  --accent-weak: color-mix(in srgb, var(--accent-primary) 14%, transparent);
+  --accent-line: color-mix(in srgb, var(--accent-primary) 55%, transparent);
+  --link: var(--accent-primary);
+  --violet: #8b7bff;
+  --warn: #e0b341;
+  --selection-bg: color-mix(in srgb, var(--accent-primary) 30%, transparent);
+  --selection-fg: var(--text-primary);
+
+  --border-light: color-mix(in srgb, var(--text-primary) 14%, transparent);
+  --border-medium: color-mix(in srgb, var(--text-primary) 24%, transparent);
+  --border-heavy: color-mix(in srgb, var(--text-primary) 34%, transparent);
+
+  /* short aliases: the rest of the sheet keeps reading the same way */
+  --bg: var(--main-surface-primary);
+  --bg-soft: var(--main-surface-secondary);
+  --bg-lift: var(--main-surface-tertiary);
+  --bg-hover: var(--hover);
+  --fg: var(--text-primary);
+  --fg-dim: var(--text-secondary);
+  --fg-faint: var(--text-tertiary);
+  --fg-quat: var(--text-quaternary);
+  --line: var(--border-light);
+  --line-strong: var(--border-medium);
+  --accent: var(--accent-primary);
+  --danger: var(--text-error);
+
+  --rail: 252px;
+  --panel: 296px;
+  --radius: 12px;
+  --radius-lg: 22px;
+  --shadow: 0 16px 40px rgba(0, 0, 0, .45);
+  --shadow-sm: 0 6px 18px rgba(0, 0, 0, .3);
+  --mono: ui-monospace, SFMono-Regular, "JetBrains Mono", Menlo, Consolas, monospace;
+  --sans: system-ui, -apple-system, "Segoe UI", Roboto, "Noto Sans CJK SC", sans-serif;
+  --ease: cubic-bezier(.22, .61, .36, 1);
+  --ease-pop: cubic-bezier(.2, .9, .3, 1.06);   /* enters with a hint of overshoot */
+  --t-fast: 120ms;
+  --t: 180ms;
+}
+[data-theme="light"] {
+  color-scheme: light;
+
+  --text-primary: #14141a;
+  --text-secondary: #55555f;
+  --text-tertiary: #7c7c86;
+  --text-quaternary: #9c9ca6;
+  --text-error: #c8303f;
+  --text-success: #0f8f66;
+
+  --main-surface-primary: #ffffff;
+  --main-surface-secondary: #f7f7f9;
+  --main-surface-tertiary: #ffffff;
+
+  --sidebar-surface-primary: #fafafb;
+  --sidebar-surface-secondary: #f1f1f4;
+  --sidebar-surface-tertiary: #ffffff;
+
+  --composer-surface-primary: #ffffff;
+  --composer-surface-secondary: #f4f4f6;
+
+  --bg-code: #f5f5f7;
+
+  --accent-primary: #0f9d70;
+  --accent-fg: #ffffff;
+
+  --border-light: color-mix(in srgb, var(--text-primary) 12%, transparent);
+  --border-medium: color-mix(in srgb, var(--text-primary) 20%, transparent);
+  --border-heavy: color-mix(in srgb, var(--text-primary) 30%, transparent);
+
+  --warn: #a9761a;
+  --shadow: 0 16px 40px rgba(20, 20, 35, .14);
+  --shadow-sm: 0 6px 18px rgba(20, 20, 35, .1);
+}
+
+* { box-sizing: border-box; }
+html, body { height: 100%; margin: 0; }
+body {
+  background: var(--bg); color: var(--fg);
+  font: 15px/1.62 var(--sans);
+  -webkit-font-smoothing: antialiased;
+  -webkit-text-size-adjust: 100%;
+  overflow: hidden; /* columns scroll, never the page */
+}
+button, textarea, input { font: inherit; color: inherit; }
+button { cursor: pointer; background: none; border: 0; }
+button:disabled { cursor: default; }
+.grow { flex: 1 1 auto; }
+.quiet, .muted { color: var(--fg-dim); }
+.tiny { font-size: 12px; }
+[hidden] { display: none !important; }
+::selection { background: var(--selection-bg); color: var(--selection-fg); }
+
+/* one icon system: everything is drawn on the same 24px grid, stroked with
+ * the current text colour, so header, rail, popovers and composer match */
+svg.i {
+  width: 18px; height: 18px; flex: 0 0 auto; display: block;
+  fill: none; stroke: currentColor; stroke-width: 1.7;
+  stroke-linecap: round; stroke-linejoin: round;
+}
+svg.i .f { fill: currentColor; stroke: none; }
+.icon svg.i { width: 18px; height: 18px; }
+.icon.tiny svg.i { width: 15px; height: 15px; }
+.chip svg.i { width: 15px; height: 15px; }
+.chip .chev { width: 13px; height: 13px; opacity: .6; }
+.new-task svg.i { width: 17px; height: 17px; }
+.send svg.i { width: 19px; height: 19px; stroke-width: 2; }
+svg.i.only-light { display: none; }
+[data-theme="light"] svg.i.only-dark { display: none; }
+[data-theme="light"] svg.i.only-light { display: block; }
+
+/* the changed-file rows in the run panel: path, then +added / -removed */
+.fstat { display: flex; align-items: center; gap: 8px; padding: 5px 0; font-size: 13px; animation: fade-in var(--t) var(--ease) both; }
+.fstat .fimg { width: 15px; height: 15px; color: var(--text-quaternary); }
+.fstat .p {
+  flex: 1 1 auto; min-width: 0; overflow: hidden; text-overflow: ellipsis;
+  white-space: nowrap; font-family: var(--mono); font-size: 12px;
+}
+.fstat .a, .fstat .d { font-variant-numeric: tabular-nums; font-size: 12px; }
+.fstat .a { color: var(--text-success); }
+.fstat .d { color: var(--text-error); }
+
+::-webkit-scrollbar { width: 10px; height: 10px; }
+::-webkit-scrollbar-thumb {
+  background: var(--line-strong); border-radius: 99px;
+  border: 3px solid transparent; background-clip: content-box;
+}
+::-webkit-scrollbar-thumb:hover { background: var(--fg-faint); background-clip: content-box; }
+
+/* --- frame ---------------------------------------------------------------- */
+#app {
+  display: grid;
+  grid-template-columns: var(--rail) minmax(0, 1fr) var(--panel);
+  grid-template-rows: minmax(0, 1fr);
+  height: 100dvh;
+  /* the rail keeps its track and collapses to 0px, so the two states have the
+   * same track count and the column width can actually be interpolated */
+  transition: grid-template-columns 300ms var(--ease);
+}
+/* a zeroed track plus display:none used to slide #main into column one and
+ * crush it to nothing; the rail now stays in flow and is clipped instead */
+body.no-side #app { grid-template-columns: 0px minmax(0, 1fr) var(--panel); }
+body.no-panel #app { grid-template-columns: var(--rail) minmax(0, 1fr) 0px; }
+body.no-side.no-panel #app { grid-template-columns: 0px minmax(0, 1fr) 0px; }
+/* the expand control only exists while the rail is folded away, so exactly one
+ * toggle is ever on screen */
+#btn-side { display: none; }
+body.no-side #btn-side { display: inline-flex; }
+
+.icon {
+  width: 32px; height: 32px; border-radius: 9px; flex: 0 0 auto;
+  display: inline-flex; align-items: center; justify-content: center;
+  color: var(--fg-dim); font-size: 15px;
+  transition: background var(--t-fast), color var(--t-fast), transform 90ms var(--ease);
+}
+.icon:hover { background: var(--bg-hover); color: var(--fg); }
+.icon:active { transform: scale(.94); }
+.icon.tiny { width: 26px; height: 26px; font-size: 13px; }
+.round { border-radius: 50%; }
+.chip {
+  display: inline-flex; align-items: center; gap: 5px; height: 30px;
+  padding: 0 11px; border-radius: 99px; border: 1px solid transparent;
+  background: none; color: var(--fg-dim); font-size: 13px;
+  max-width: 280px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+  transition: background var(--t-fast), color var(--t-fast), border-color var(--t-fast), transform 90ms var(--ease);
+}
+.chip:hover { background: var(--bg-hover); color: var(--fg); }
+.chip:active { transform: scale(.97); }
+.chip.model { color: var(--fg); font-weight: 600; background: var(--bg-lift); border-color: var(--line); }
+.chip.model:hover { border-color: var(--line-strong); }
+.chip.warn { color: var(--warn); }
+.chip .chev { font-size: 11px; opacity: .65; }
+.badge {
+  min-width: 18px; height: 18px; padding: 0 5px; border-radius: 99px;
+  background: var(--accent-weak); color: var(--accent);
+  font-size: 11px; font-weight: 700;
+  display: inline-flex; align-items: center; justify-content: center;
+}
+
+/* --- rail ----------------------------------------------------------------- */
+#side {
+  background: var(--sidebar-surface-primary); border-right: 1px solid var(--border-light);
+  min-width: 0; overflow: hidden;      /* clips the rail while its track collapses */
+}
+/* the contents keep their own width and slide out, so nothing reflows mid-flight
+ * and the exit reads as one movement instead of a squeeze */
+.side-inner {
+  width: var(--rail); height: 100%; min-width: 0;
+  display: flex; flex-direction: column; padding: 12px 10px 10px;
+  transition: transform 300ms var(--ease-pop), opacity 200ms var(--ease);
+}
+body.no-side .side-inner { transform: translateX(-18px); opacity: 0; }
+body.no-side #side { pointer-events: none; }
+.side-head { display: flex; align-items: center; gap: 2px; margin-bottom: 14px; }
+/* the wordmark is a label, not a control: no logo tile, nothing to click */
+.brand { flex: 1 1 auto; display: flex; align-items: center; min-width: 0; padding: 6px 8px; }
+.brand-name {
+  font-weight: 700; letter-spacing: .2px; font-size: 15px;
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+}
+
+.new-task {
+  display: flex; align-items: center; gap: 9px; height: 40px; padding: 0 12px;
+  margin-bottom: 18px; border-radius: 12px; font-weight: 600;
+  background: var(--bg-lift); border: 1px solid var(--line);
+  transition: border-color var(--t-fast), background var(--t-fast), transform 90ms var(--ease);
+}
+.new-task:hover { border-color: var(--line-strong); background: var(--bg-hover); }
+.new-task:active { transform: scale(.985); }
+.new-task .plus { color: var(--accent); font-size: 16px; line-height: 1; }
+
+.side-sec {
+  display: flex; align-items: center; gap: 6px; padding: 0 8px 6px;
+  color: var(--fg-faint); font-size: 11px; font-weight: 600;
+  letter-spacing: .7px; text-transform: uppercase;
+}
+.sessions { flex: 1 1 auto; overflow-y: auto; min-height: 40px; scrollbar-gutter: stable; }
+.sess-item {
+  display: flex; align-items: baseline; gap: 8px; width: 100%;
+  padding: 7px 9px; border-radius: 9px; text-align: left;
+  color: var(--text-secondary); font-size: 13.5px;
+  animation: fade-in var(--t) var(--ease) both;
+  transition: background var(--t-fast), color var(--t-fast);
+}
+.sess-item:hover { background: var(--hover); color: var(--text-primary); }
+.sess-item.on { background: var(--sidebar-surface-tertiary); color: var(--text-primary); font-weight: 600; }
+.sess-item.on::before {
+  content: ""; width: 5px; height: 5px; border-radius: 50%;
+  background: var(--accent); flex: 0 0 auto; align-self: center;
+}
+.sess-item .t { flex: 1 1 auto; min-width: 0; overflow: hidden; }
+.sess-item .ts { display: block; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+/* a title that does not fit fades at the edge and scrolls itself on hover, the
+ * way the reference sidebar handles long names (its data-marquee-text pattern) */
+.sess-item .t.mq { mask-image: linear-gradient(90deg, #000 calc(100% - 18px), transparent); }
+.sess-item:hover .t.mq { mask-image: none; }
+.sess-item:hover .t.mq .ts {
+  width: max-content; text-overflow: clip;
+  animation: marquee 2.6s var(--ease) 160ms infinite alternate;
+}
+@keyframes marquee { from { transform: none; } to { transform: translateX(calc(-1 * var(--mq, 0px))); } }
+.sess-item .n { font-size: 11px; color: var(--text-quaternary); font-weight: 400; white-space: nowrap; }
+.side-foot {
+  display: flex; align-items: center; gap: 6px; padding-top: 10px;
+  margin-top: 6px; border-top: 1px solid var(--line);
+}
+.who { display: flex; align-items: center; gap: 9px; min-width: 0; flex: 1 1 auto; }
+.avatar {
+  width: 28px; height: 28px; border-radius: 50%; flex: 0 0 auto;
+  background: linear-gradient(135deg, var(--violet), var(--accent));
+  color: #fff; font-weight: 800; font-size: 13px;
+  display: flex; align-items: center; justify-content: center;
+}
+.who-text { min-width: 0; display: flex; flex-direction: column; line-height: 1.3; }
+.who-text b { font-size: 12.5px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.who-text i { font-size: 11px; color: var(--fg-faint); font-style: normal; }
+
+/* --- top bar -------------------------------------------------------------- */
+#main { display: flex; flex-direction: column; min-width: 0; position: relative; }
+#topbar { display: flex; align-items: center; gap: 4px; padding: 9px 12px; border-bottom: 1px solid var(--line); }
+.seg {
+  display: flex; background: var(--bg-soft); border: 1px solid var(--line);
+  border-radius: 99px; padding: 2px; position: relative;
+}
+.seg button {
+  height: 25px; padding: 0 12px; border-radius: 99px; color: var(--fg-dim); font-size: 12.5px;
+  transition: color var(--t-fast), background var(--t);
+}
+.seg button.on { background: var(--bg-lift); color: var(--fg); font-weight: 600; }
+.only-narrow { display: none; }
+
+#scroll {
+  flex: 1 1 auto; overflow-y: auto; padding: 22px 0 10px;
+  scroll-behavior: smooth; scrollbar-gutter: stable;
+}
+#log { max-width: 760px; margin: 0 auto; padding: 0 20px; }
+#log:empty { display: none; }
+
+/* --- empty state ---------------------------------------------------------- */
+/* the first screen is one line: no logo, no suggestion wall. It goes away the
+ * moment the first message lands (see showEmpty). */
+#empty { margin: 22vh auto 0; padding: 0 20px; text-align: center; }
+#empty.gone { display: none; }
+#empty .ready {
+  margin: 0; color: var(--text-tertiary); font-size: 15px; letter-spacing: .3px;
+  animation: fade-in 320ms var(--ease) both;
+}
+
+/* --- transcript ----------------------------------------------------------- */
+.msg { display: flex; gap: 12px; padding: 13px 0 0; animation: fade-up var(--t) var(--ease) both; }
+.msg .gutter { flex: 0 0 24px; padding-top: 2px; color: var(--fg-faint); font-size: 11px; text-align: center; user-select: none; }
+.msg .body { min-width: 0; flex: 1 1 auto; }
+.msg.user { justify-content: flex-end; }
+.msg.user .gutter { display: none; }
+.msg.user .body {
+  background: var(--bg-lift); border-radius: 18px 18px 6px 18px;
+  padding: 9px 15px; max-width: 76%; white-space: pre-wrap; word-break: break-word;
+}
+.msg.error .body { color: var(--danger); }
+.body > :first-child, .live-html > :first-child { margin-top: 0; }
+.body > :last-child, .live-html > :last-child { margin-bottom: 0; }
+.body h1, .body h2, .body h3, .body h4 { line-height: 1.35; margin: 1.1em 0 .5em; }
+.body h1 { font-size: 1.45em; } .body h2 { font-size: 1.25em; } .body h3 { font-size: 1.1em; }
+.body p, .body ul, .body ol { margin: .55em 0; }
+.body ul, .body ol { padding-left: 1.4em; }
+.body li { margin: .22em 0; }
+.body a { color: var(--link); }
+.body code {
+  font-family: var(--mono); font-size: .88em; background: var(--bg-code);
+  border: 1px solid var(--line); border-radius: 6px; padding: .1em .35em;
+}
+.body pre {
+  background: var(--bg-code); border: 1px solid var(--line);
+  border-radius: 12px; padding: 12px 14px; overflow-x: auto; margin: .75em 0;
+}
+.body pre code { background: none; border: 0; padding: 0; font-size: 13px; }
+.body blockquote { margin: .75em 0; padding: .1em 0 .1em 12px; border-left: 3px solid var(--line-strong); color: var(--fg-dim); }
+.body table { border-collapse: collapse; margin: .75em 0; font-size: 13.5px; display: block; overflow-x: auto; }
+.body th, .body td { border: 1px solid var(--line); padding: 5px 9px; text-align: left; }
+.body th { background: var(--bg-soft); }
+.body img { max-width: 100%; border-radius: 10px; }
+.body hr { border: 0; border-top: 1px solid var(--line); margin: 1.2em 0; }
+/* a caret while tokens are still arriving */
+.body.live > .live-html > :last-child::after {
+  content: ""; display: inline-block; width: 7px; height: 14px;
+  margin-left: 3px; vertical-align: -2px; border-radius: 2px;
+  background: var(--accent); animation: blink 1.1s steps(2, start) infinite;
+}
+
+.attach-strip { display: flex; flex-wrap: wrap; gap: 8px; margin: 2px 0 8px; justify-content: flex-end; }
+.attach-strip img {
+  width: 108px; height: 108px; object-fit: cover; border-radius: 12px;
+  border: 1px solid var(--line); animation: rise var(--t) var(--ease) both;
+}
+
+.turn-meta { display: flex; align-items: center; gap: 10px; padding: 10px 0 2px 36px; }
+.turn-meta details > summary { cursor: pointer; list-style: none; color: var(--fg-faint); font-size: 12px; transition: color var(--t-fast); }
+.turn-meta details > summary::-webkit-details-marker { display: none; }
+.turn-meta details > summary:hover { color: var(--fg-dim); }
+.msg-actions { display: flex; gap: 2px; padding: 4px 0 0 36px; opacity: 0; transition: opacity var(--t) var(--ease); }
+.msg:hover .msg-actions, .msg-actions:focus-within { opacity: 1; }
+.msg-actions button {
+  height: 26px; padding: 0 9px; border-radius: 8px; color: var(--fg-faint); font-size: 12px;
+  transition: background var(--t-fast), color var(--t-fast);
+}
+.msg-actions button:hover { background: var(--bg-hover); color: var(--fg); }
+
+.think { margin: .1em 0 .5em; }
+.think summary { cursor: pointer; list-style: none; color: var(--fg-faint); font-size: 12.5px; transition: color var(--t-fast); }
+.think summary::-webkit-details-marker { display: none; }
+.think summary::before { content: "▸ "; }
+.think[open] summary::before { content: "▾ "; }
+.think summary:hover { color: var(--fg-dim); }
+.think > div {
+  color: var(--fg-dim); font-size: 13.5px; white-space: pre-wrap;
+  padding: 6px 0 2px 14px; border-left: 2px solid var(--line);
+  animation: fade-in var(--t) var(--ease) both;
+}
+
+/* tool calls: one line, opens on demand (like "已执行 python · <<PY>") */
+.turn-steps { padding: 6px 0 0 36px; }
+.turn-steps > summary { cursor: pointer; list-style: none; color: var(--fg-faint); font-size: 12.5px; transition: color var(--t-fast); }
+.turn-steps > summary::-webkit-details-marker { display: none; }
+.turn-steps > summary::before { content: "⌘ "; }
+.turn-steps > summary:hover { color: var(--fg-dim); }
+.steps-box { padding: 2px 0 0 12px; margin-top: 4px; border-left: 2px solid var(--line); }
+.step-line { animation: fade-up var(--t) var(--ease) both; }
+.step-line > summary {
+  display: flex; align-items: baseline; gap: 8px; cursor: pointer; list-style: none;
+  padding: 5px 0; font-size: 13px; color: var(--fg-dim);
+  transition: color var(--t-fast);
+}
+.step-line > summary::-webkit-details-marker { display: none; }
+.step-line > summary:hover { color: var(--fg); }
+.step-line .name { font-family: var(--mono); font-size: 12.5px; color: var(--fg); }
+.step-line .args { flex: 1 1 auto; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-family: var(--mono); font-size: 12px; }
+.step-line .phase { font-size: 11.5px; color: var(--fg-faint); white-space: nowrap; display: inline-flex; align-items: center; gap: 6px; }
+.step-line.run .phase { color: var(--warn); }
+.step-line.run .phase::before {
+  content: ""; width: 6px; height: 6px; border-radius: 50%;
+  background: var(--warn); animation: pulse 1.1s var(--ease) infinite;
+}
+.step-line.bad .phase, .step-line.bad .name { color: var(--danger); }
+.step-line.done .phase::before { content: "✓"; }
+.step-body { padding: 0 0 6px; animation: fade-in var(--t) var(--ease) both; }
+.step-out, .step-args-full {
+  font-family: var(--mono); font-size: 12px; background: var(--bg-code);
+  border: 1px solid var(--line); border-radius: 10px; padding: 9px 11px;
+  margin: 4px 0 0; max-height: 300px; overflow: auto; white-space: pre-wrap; word-break: break-word;
+}
+
+#to-bottom {
+  position: absolute; right: 26px; bottom: 172px; z-index: 5;
+  width: 38px; height: 38px; display: flex; align-items: center; justify-content: center;
+  background: var(--bg-lift); border: 1px solid var(--line-strong); color: var(--fg-dim);
+  box-shadow: var(--shadow-sm); font-size: 16px;
+  animation: fade-in var(--t) var(--ease) both;
+  transition: color var(--t-fast), transform 90ms var(--ease), background var(--t-fast);
+}
+#to-bottom:hover { color: var(--fg); background: var(--bg-hover); }
+#to-bottom:active { transform: scale(.94); }
+
+/* --- composer ------------------------------------------------------------- */
+#composer { padding: 8px 20px 12px; }
+#composer > * { max-width: 760px; margin: 0 auto; }
+.pending { display: flex; flex-wrap: wrap; gap: 8px; padding: 0 0 8px; }
+.pending .chip { background: var(--bg-soft); border-color: var(--line); }
+
+.box {
+  border: 1px solid var(--border-medium); border-radius: var(--radius-lg);
+  background: var(--composer-surface-primary); padding: 11px 13px 9px;
+  transition: border-color var(--t), box-shadow var(--t), background var(--t);
+}
+.box:hover { border-color: var(--border-heavy); }
+.box:focus-within {
+  border-color: var(--accent-line);
+  box-shadow: 0 0 0 3px var(--accent-weak);
+}
+.box textarea {
+  width: 100%; border: 0; background: none; resize: none; outline: none;
+  max-height: 240px; min-height: 26px; padding: 2px 2px 8px;
+  caret-color: var(--accent);
+}
+.box textarea::placeholder { color: var(--fg-faint); }
+.box-row { display: flex; align-items: center; gap: 6px; }
+.att { border: 1px solid var(--line); font-size: 17px; line-height: 1; }
+.cost { color: var(--fg-faint); font-size: 12px; padding: 0 4px; white-space: nowrap; }
+.cost:hover { color: var(--fg-dim); }
+.send {
+  width: 36px; height: 36px; flex: 0 0 auto; font-size: 17px; font-weight: 800;
+  background: var(--accent); color: var(--accent-fg);
+  transition: filter var(--t-fast), transform 90ms var(--ease), opacity var(--t-fast);
+}
+.send:hover { filter: brightness(1.08); }
+.send:active { transform: scale(.94); }
+.send:disabled { opacity: .38; }
+.icon.stop { border: 1px solid var(--line); font-size: 12px; }
+.hint-line { display: flex; align-items: center; gap: 10px; padding: 7px 6px 0; font-size: 12px; color: var(--fg-faint); }
+
+/* permission gate: inline, the turn really is waiting on it */
+.gate {
+  border: 1px solid color-mix(in srgb, var(--warn) 45%, transparent);
+  border-radius: var(--radius); padding: 11px 13px; margin-bottom: 10px;
+  background: color-mix(in srgb, var(--warn) 7%, var(--bg-soft));
+  animation: rise var(--t) var(--ease) both;
+}
+.gate-head { display: flex; align-items: center; gap: 8px; font-weight: 650; font-size: 14px; }
+.gate-timer { color: var(--warn); font-size: 12.5px; font-variant-numeric: tabular-nums; }
+.gate pre {
+  margin: 8px 0 0; background: var(--bg-code); border: 1px solid var(--line);
+  border-radius: 10px; padding: 9px 11px; max-height: 180px; overflow: auto;
+  font-family: var(--mono); font-size: 12.5px; white-space: pre-wrap; word-break: break-word;
+}
+.gate-keys { padding: 8px 0 2px; color: var(--fg-dim); font-size: 12.5px; }
+.gate-row { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 6px; }
+.gate-row button {
+  height: 34px; padding: 0 14px; border-radius: 10px; font-weight: 600;
+  border: 1px solid var(--line-strong); background: var(--bg-lift);
+  transition: filter var(--t-fast), transform 90ms var(--ease), background var(--t-fast);
+}
+.gate-row button.ok { background: var(--accent); color: var(--accent-fg); border-color: transparent; }
+.gate-row button.danger { color: var(--danger); }
+.gate-row button:hover { filter: brightness(1.12); }
+.gate-row button:active { transform: scale(.97); }
+
+/* --- popovers: anchored, animated, and the only place settings live ------- */
+.pop {
+  position: fixed; z-index: 45; min-width: 236px; max-width: 320px;
+  background: var(--main-surface-tertiary); border: 1px solid var(--border-medium);
+  border-radius: 14px; padding: 6px; box-shadow: var(--shadow);
+  animation: pop-in 160ms var(--ease) both;
+}
+.pop-item {
+  display: flex; align-items: flex-start; gap: 10px; width: 100%;
+  padding: 9px 10px; border-radius: 10px; text-align: left;
+  transition: background var(--t-fast);
+}
+.pop-item:hover { background: var(--bg-hover); }
+.pop-item .pi { width: 18px; flex: 0 0 auto; text-align: center; color: var(--fg-dim); font-size: 14px; line-height: 1.4; }
+/* title over description: two lines, never one run-on line */
+.pop-item .pm { min-width: 0; flex: 1 1 auto; display: flex; flex-direction: column; gap: 2px; }
+.pop-item .pt { font-size: 13.5px; font-weight: 600; line-height: 1.35; }
+.pop-item .pd { font-size: 11.5px; color: var(--fg-faint); line-height: 1.4; }
+.pop-item .pk { flex: 0 0 auto; color: var(--accent); font-size: 13px; }
+.pop-item.on { background: var(--accent-weak); }
+.pop-item.on .pi, .pop-item.on .pt { color: var(--accent); }
+.pop-item.danger .pi, .pop-item.danger .pt { color: var(--danger); }
+.pop-sep { height: 1px; background: var(--line); margin: 5px 4px; }
+.pop-title { padding: 8px 10px 4px; color: var(--fg-faint); font-size: 11.5px; font-weight: 600; letter-spacing: .4px; }
+.pop-input { display: flex; gap: 6px; padding: 4px 6px 6px; }
+.pop-input input {
+  flex: 1 1 auto; min-width: 0; background: var(--bg-soft); border: 1px solid var(--line);
+  border-radius: 9px; padding: 7px 9px; outline: none; font-size: 13px;
+  caret-color: var(--accent);
+  transition: border-color var(--t-fast);
+}
+.pop-input input:focus { border-color: var(--accent-line); }
+.pop-input button {
+  height: 32px; padding: 0 12px; border-radius: 9px; font-weight: 600; font-size: 13px;
+  background: var(--accent); color: var(--accent-fg);
+  transition: filter var(--t-fast), transform 90ms var(--ease);
+}
+.pop-input button:active { transform: scale(.96); }
+.kv { display: flex; align-items: center; justify-content: space-between; gap: 10px; padding: 5px 10px; font-size: 13px; }
+.kv span { color: var(--fg-dim); }
+.kv b { font-variant-numeric: tabular-nums; font-weight: 600; min-width: 0; overflow-wrap: anywhere; text-align: right; }
+.pop { max-height: calc(100vh - 16px); overflow-y: auto; }
+.pop:has(.pop-list) { min-width: min(360px, 94vw); max-width: min(440px, 94vw); }
+.pop-head { display: flex; align-items: center; justify-content: space-between; gap: 8px; }
+.pop-list { max-height: min(46vh, 420px); overflow-y: auto; }
+.pop-list .pop-item .pt { overflow-wrap: anywhere; font-family: var(--mono); font-size: 12.5px; }
+.pop-empty { padding: 10px; color: var(--fg-faint); font-size: 12.5px; }
+.pop-note { padding: 2px 10px 6px; color: var(--fg-faint); font-size: 11.5px; line-height: 1.45; }
+.pop-note:empty { display: none; }
+.pop-note.bad { color: var(--danger); }
+.pop-note.warn { color: var(--warn); }
+.pop-item.dim { opacity: .55; }
+button.link { color: var(--link); padding: 0 4px; font-size: inherit; text-decoration: underline; }
+.ok-text { color: var(--text-success); }
+.warn-text { color: var(--warn); }
+
+/* providers and the key dialog */
+#modal-box .prov {
+  display: flex; align-items: center; gap: 10px; padding: 9px 8px;
+  border-bottom: 1px solid var(--line); border-radius: 8px;
+}
+#modal-box .prov.on { background: var(--accent-weak); }
+#modal-box .prov .pm { flex: 1 1 auto; min-width: 0; display: flex; flex-direction: column; gap: 2px; }
+#modal-box .prov .pm span { overflow-wrap: anywhere; }
+#modal-box .prov-acts button {
+  height: 30px; padding: 0 12px; border-radius: 9px; font-weight: 600; font-size: 13px;
+  border: 1px solid var(--line-strong); background: var(--bg-lift); white-space: nowrap;
+}
+#modal-box .prov-acts button.ok { background: var(--accent); color: var(--accent-fg); border-color: transparent; }
+#modal-box .key-input {
+  width: 100%; margin-top: 12px; background: var(--bg-lift); border: 1px solid var(--line);
+  border-radius: 10px; padding: 9px 11px; outline: none; font-family: var(--mono);
+}
+#modal-box .key-input:focus { border-color: var(--accent-line); }
+#modal-box .key-err { min-height: 18px; margin-top: 6px; color: var(--danger); font-size: 12.5px; }
+
+/* one line of feedback for anything that failed or needs a look */
+.toast {
+  position: fixed; left: 50%; bottom: 24px; transform: translateX(-50%); z-index: 60;
+  max-width: min(560px, 92vw); padding: 10px 14px; border-radius: 12px;
+  background: var(--main-surface-tertiary); border: 1px solid var(--border-medium);
+  box-shadow: var(--shadow); font-size: 13px; line-height: 1.45; overflow-wrap: anywhere;
+  animation: fade-up 160ms var(--ease) both;
+}
+.toast.err { border-color: color-mix(in srgb, var(--danger) 55%, transparent); color: var(--danger); }
+.toast.warn { border-color: color-mix(in srgb, var(--warn) 55%, transparent); color: var(--warn); }
+.toast.ok { border-color: var(--accent-line); color: var(--accent); }
+.toast[hidden] { display: none; }
+
+/* --- right panel ---------------------------------------------------------- */
+/* the right panel mirrors the rail: fixed-width contents, clipped by the track,
+ * so folding it in and out is one eased movement on each side */
+#panel { background: var(--main-surface-secondary); border-left: 1px solid var(--border-light); min-width: 0; overflow: hidden; }
+.panel-inner {
+  width: var(--panel); height: 100%; overflow-y: auto; padding: 12px;
+  transition: transform 300ms var(--ease-pop), opacity 200ms var(--ease);
+}
+body.no-panel .panel-inner { transform: translateX(18px); opacity: 0; }
+body.no-panel #panel { pointer-events: none; }
+.panel-head {
+  display: flex; align-items: center; gap: 6px; padding: 2px 4px 10px;
+  color: var(--fg-faint); font-size: 11px; font-weight: 600;
+  letter-spacing: .7px; text-transform: uppercase;
+}
+.card { border-top: 1px solid var(--line); padding: 12px 2px; }
+.card:first-of-type { border-top: 0; }
+.card h4 { margin: 0 0 8px; font-size: 12.5px; font-weight: 650; display: flex; align-items: center; gap: 6px; }
+.card .kv { padding: 3px 0; }
+.todo-list { margin: 0; padding: 0; list-style: none; font-size: 13.5px; }
+.todo-list li { display: flex; gap: 8px; padding: 3px 0; animation: fade-in var(--t) var(--ease) both; transition: color var(--t-fast); }
+.todo-list .boxmark { color: var(--fg-faint); }
+.todo-list li.done { color: var(--fg-faint); text-decoration: line-through; }
+.todo-list li.doing { color: var(--fg); font-weight: 600; }
+#steps-body .step-line > summary { font-size: 12.5px; }
+#steps-body .step-line .phase { font-size: 11px; }
+
+/* --- modal sheet (session list) ------------------------------------------- */
+#modal {
+  position: fixed; inset: 0; background: rgba(0, 0, 0, .5); z-index: 40;
+  display: flex; align-items: center; justify-content: center; padding: 16px;
+  animation: fade-in var(--t) var(--ease) both;
+}
+#modal-box {
+  width: min(560px, 100%); max-height: 82vh; overflow-y: auto;
+  background: var(--main-surface-tertiary); border: 1px solid var(--border-medium);
+  border-radius: 18px; padding: 16px 18px; box-shadow: var(--shadow);
+  animation: pop-in 180ms var(--ease) both;
+}
+#modal-box h3 { margin: 0 0 12px; font-size: 17px; }
+#modal-box .field { display: flex; align-items: center; gap: 8px; margin: 9px 0; flex-wrap: wrap; }
+#modal-box .field > span { width: 70px; color: var(--fg-dim); font-size: 13px; }
+#modal-box .field input {
+  flex: 1 1 auto; min-width: 150px; background: var(--bg-lift);
+  border: 1px solid var(--line); border-radius: 10px; padding: 8px 10px; outline: none;
+}
+#modal-box .buttons { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; margin-top: 12px; }
+#modal-box .buttons button {
+  height: 34px; padding: 0 14px; border-radius: 10px; font-weight: 600;
+  border: 1px solid var(--line-strong); background: var(--bg-lift);
+  transition: filter var(--t-fast), transform 90ms var(--ease);
+}
+#modal-box .buttons button:active { transform: scale(.97); }
+#modal-box .buttons button.ok { background: var(--accent); color: var(--accent-fg); border-color: transparent; }
+#modal-box .buttons button.danger { color: var(--danger); }
+#modal-box .sess {
+  display: flex; align-items: center; gap: 8px; padding: 8px 6px;
+  border-bottom: 1px solid var(--line); border-radius: 8px;
+  transition: background var(--t-fast);
+}
+#modal-box .sess:hover { background: var(--bg-hover); }
+#modal-box .sess .id { font-family: var(--mono); font-size: 11.5px; color: var(--fg-faint); }
+#modal-box .sess .t { flex: 1 1 auto; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: 13.5px; }
+
+/* --- narrow screens: rail and panel become drawers ------------------------ */
+#backdrop { position: fixed; inset: 0; background: rgba(0, 0, 0, .45); z-index: 30; display: none; animation: fade-in var(--t) var(--ease) both; }
+body.drawer-open #backdrop { display: block; }
+@media (max-width: 900px) {
+  #app { grid-template-columns: minmax(0, 1fr) !important; transition: none; }
+  #side, #panel {
+    position: fixed; top: 0; bottom: 0; width: min(310px, 86vw); z-index: 31;
+    display: block; transition: transform 260ms var(--ease-pop);
+  }
+  .side-inner { width: auto; transform: none !important; opacity: 1 !important; }
+  #side { overflow: visible; pointer-events: auto; }
+  #side { left: 0; transform: translateX(-102%); }
+  #panel { right: 0; transform: translateX(102%); }
+  body.side-open #side, body.panel-open #panel { transform: none; }
+  .only-narrow { display: inline-flex; }
+  #to-bottom { bottom: 150px; right: 16px; }
+  .hero h1 { font-size: 21px; }
+  .msg.user .body { max-width: 88%; }
+  .turn-meta, .msg-actions, .turn-steps { padding-left: 0; }
+}
+@media (min-width: 901px) { #backdrop { display: none !important; } }
+
+/* --- motion --------------------------------------------------------------- */
+@keyframes fade-in { from { opacity: 0; } to { opacity: 1; } }
+@keyframes fade-up { from { opacity: 0; transform: translateY(6px); } to { opacity: 1; transform: none; } }
+@keyframes rise { from { opacity: 0; transform: translateY(10px) scale(.99); } to { opacity: 1; transform: none; } }
+@keyframes pop-in { from { opacity: 0; transform: translateY(-4px) scale(.97); } to { opacity: 1; transform: none; } }
+@keyframes pulse { 0%, 100% { opacity: .3; transform: scale(.85); } 50% { opacity: 1; transform: scale(1); } }
+@keyframes blink { 0%, 100% { opacity: 1; } 50% { opacity: 0; } }
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after { animation-duration: 1ms !important; transition-duration: 1ms !important; }
+  #scroll { scroll-behavior: auto; }
+}