Initial CST-Agent: portable Linux/Termux/Windows coding agent.

Vendored sashidown, OpenAI-compatible env (OPENAI_*), and bootstrap scripts.

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/theory_tool_cst.md

@@ -0,0 +1,60 @@
+# Tool-loop CST：确认前沿推广到工具调用
+
+## 命题
+
+在 agent 工具环中，对模型输出做**确认流式转导**：只在 \(O_{\mathrm{conf}}\) 内不可逆地发射「可执行工具调用 / 可应用补丁 / 可提交会话状态」。相对「拼到合法 JSON 再执行」的缓冲基线，这能降低注意力饥渴导致的残缺工具帧（未闭合括号、半截 arguments）被过早执行或整轮失败的问题。
+
+## 与论文 CST 的对应
+
+| 论文（Markdown→HTML） | 工具环推广 |
+|---|---|
+| 输入字母表 \(\Sigma\) | 模型文本 / CTL 字节流 |
+| 指称 \(f,g\) → HTML | \(f_{\mathrm{tool}}\) → 已确认 `ToolCall` / `PatchHunk` |
+| \(O_{\mathrm{conf}}\) 不可撤回 HTML | 不可撤回：开始执行工具、应用 hunk、写入 transcript |
+| \(\mathcal{L}_0\) 排除引用式链接 | \(\mathcal{L}_0^{\mathrm{tool}}\) **排除裸 JSON 对象** |
+| \(K=2L_{\mathrm{line}}\) | 工具帧同样要求有界 pending |
+
+## 为何排除裸 JSON
+
+JSON 对象依赖括号匹配与字符串转义。在未闭合 `"` / `{` 时，任意后缀都可能改变已见结构的指称，故 \(O_{\mathrm{conf}}\) 往往停在空前缀，pending 随流长增长——这与论文中引用式链接的**无界后向绑定**同构。「等整个 JSON `Parse` 成功」只是 EOF 缓冲，不是有界 CST。
+
+## \(\mathcal{L}_0^{\mathrm{tool}}\)：CTL（CST Tool Language）
+
+行界 \(L_{\mathrm{line}}\)；参数体用长度前缀，避免转义歧义。
+
+```text
+call <id> <name>\n
+arg <key> <nbytes>\n
+<raw bytes exactly nbytes>
+end\n
+```
+
+### 确认规则
+
+1. **`call` 行以 `\n` 结束**：确认 `(id, name)`（此后不可撤回工具身份）。
+2. **`arg` 头以 `\n` 结束**：确认 `(key, nbytes)`；随后精确消费 `nbytes` 字节，每字节到达即可确认（无 JSON 转义）。
+3. **`end\n`**：确认整次调用可执行；转导器发射一个 `ToolCall` 事件。
+4. 行长 \(> L_{\mathrm{line}}\)、非法 token、`nbytes` 超上限、非 CTL 噪声 → 离开契约，标记 `tool_parse_error`。
+
+### 有界 pending \(K\)
+
+- 解析行头时 pending \(\le L_{\mathrm{line}}\)。
+- 读参数体时 pending \(\le\) 剩余未读字节数，但**已读体字节已确认**，工作区只需当前行缓冲 + 当前 arg 剩余计数（\(O(L_{\mathrm{line}})\) 寄存器），不随会话总长增长。
+
+取 \(K = L_{\mathrm{line}}\)（行头）与实现常量 `CTL_MAX_ARG`（单参上限，契约拒绝更大值）。
+
+## 不可逆发射
+
+实现是确认忠实的，当且仅当：
+
+- 拼接发射的工具事件序列是 \(O_{\mathrm{conf}}(u)\) 的前缀；
+- 一旦 `ToolCall` 被发射，runtime **必须**执行（或显式记录拒绝），不得因后续字节撤回；
+- session transcript 只追加：用户消息、已确认助手文本、工具调用与结果。
+
+## 对照基线
+
+**JSON-buffer**：将模型输出拼接到可 `cJSON_Parse` 的 `{"name","arguments"}`（或 OpenAI `tool_calls` 形）才执行；流中途截断则失败。与 CTL 使用同一截断点集合，只换帧语法。
+
+## 补丁确认
+
+`apply_patch` 的 patch 文本作为 CTL 的一个 `arg`；应用侧再要求 unified diff 的每个 hunk 完整（`@@` 到下一块或 EOF）才写盘——整 hunk 确认，禁止半截应用。