synapse-cli-agent 0.1.37__tar.gz → 0.1.39__tar.gz

{synapse_cli_agent-0.1.37 → synapse_cli_agent-0.1.39}/.github/workflows/release.yml

@@ -102,6 +102,7 @@ jobs:
             --collect-all termaid `
             --collect-all texicode `
             --collect-all synapse_tool_compress_core `
+            --collect-data synapse `
             src/synapse/entry.py
 
       - name: Rename executable for artifact

{synapse_cli_agent-0.1.37 → synapse_cli_agent-0.1.39}/AGENTS.md

@@ -4,7 +4,8 @@
 
 | Path | Responsibility |
 | --- | --- |
-| `src/synapse/app/` | Agent assembly and `AGENTS.md` injection |
+| `src/synapse/app/` | Agent assembly (composition root in `agent.py`, contracts in `agent_assembly.py`) and `AGENTS.md` injection |
+| `src/synapse/acp/` | Official Agent Client Protocol (ACP) adapter: run Synapse as an ACP agent over stdio; session registry, permission coordinator, event bridge |
 | `src/synapse/commands/` | Slash command parsing, completion, and results |
 | `src/synapse/content/` | Prompts, skills, input history, multimodal content |
 | `src/synapse/goals/` | Goal accounting, steering, and persistence |
@@ -29,7 +30,7 @@
 
 ## Architecture & compatibility
 
-- `src/synapse/app/agent.py` is the assembly layer; keep domain algorithms in their own packages.
+- `src/synapse/app/agent.py` is the assembly composition root; the reusable assembly contracts (middleware build, typed resource wiring) live in `src/synapse/app/agent_assembly.py`. Keep domain algorithms in their own packages.
 - New features belong in the matching domain package; cross-domain wiring goes in `app/` or an explicit runtime middleware.
 - `src/synapse/config.py` is a compatibility re-export layer. Import from `synapse.settings` in new code; keep legacy import paths working.
 - `__init__.py` exports are public API. Keep necessary re-exports when moving implementations.
@@ -83,11 +84,21 @@ uv build                        # after packaging/entry-point changes
 
 ## Rust/PyO3 native crates
 
-One optional crate; the Python app must work without its wheel and must keep `ImportError`/`OSError` fallbacks.
+The Python app must work without the optional wheels and must keep `ImportError`/`OSError` fallbacks.
 
-- `rust/synapse-core-tool` (`synapse-core-tool` on PyPI): native filesystem tools (read/edit/patch/search) and math rendering. Release with tag `synapse-core-tool-v*`; `native-core-tool-wheels.yml` builds wheels and publishes to GitHub Release + PyPI. Keep the `pyproject.toml` version in sync with `Cargo.toml` — maturin names wheels from `pyproject.toml`.
+- `rust/synapse-core-tool` (`synapse-core-tool` on PyPI): native filesystem tools (read/edit/patch/search), math rendering, and the native OpenAI-compatible chat client (`RustOpenAIClient`, backed by `async-openai` byot). Release with tag `synapse-core-tool-v*`; `native-core-tool-wheels.yml` builds wheels and publishes to GitHub Release + PyPI. Keep the `pyproject.toml` version in sync with `Cargo.toml` — maturin names wheels from `pyproject.toml`.
 - `rust/synapse-tool-compress-core` (`synapse-tool-compress-core` on PyPI): native tool-output compression core. **Required dependency** of `synapse-cli-agent`. Release with tag `synapse-tool-compress-core-v*`; `native-compression-wheels.yml` builds wheels and publishes to GitHub Release + PyPI. Keep the `pyproject.toml` version in sync with `Cargo.toml`. Because the main package hard-depends on it, publish the compress-core wheels to PyPI before tagging the main `v*` release.
 
+### Building and installing a native crate locally
+
+`uv` builds the path dependencies declared in `[tool.uv.sources]` (`rust/synapse-core-tool` and `rust/synapse-tool-compress-core`). After changing Rust code, rebuild + reinstall the affected crate with:
+
+```powershell
+uv sync --reinstall-package synapse-core-tool
+```
+
+This runs maturin under the hood and installs the freshly built wheel into the venv. Do **not** rely on `maturin develop` — a plain `uv sync` afterwards re-copies the cached (stale) wheel over the develop install. To avoid that surprise, either always rebuild via `uv sync --reinstall-package ...`, or run every command with `uv run --no-sync` after a manual `maturin develop`.
+
 When changing either crate, at least run:
 
 ```powershell
@@ -95,7 +106,7 @@ cargo test --manifest-path rust/<crate>/Cargo.toml
 cargo fmt --manifest-path rust/<crate>/Cargo.toml --check
 ```
 
-If Python bindings/APIs change, build or install the local extension and run the related Python tests.
+If Python bindings/APIs change, rebuild via `uv sync --reinstall-package <crate>` and run the related Python tests.
 
 Keep the Apache-2.0 SPDX headers, attribution, `LICENSE`, and `NOTICE` under `rust/synapse-tool-compress-core/src/headroom_port/`; do not introduce excluded network calls or model downloads.
 

{synapse_cli_agent-0.1.37 → synapse_cli_agent-0.1.39}/CHANGELOG.md

@@ -8,6 +8,50 @@ All entries are written in English.
 
 ---
 
+## v0.1.39
+
+### New Features
+
+- Stamped session-affinity headers on model requests in both the Python runtime and the native Rust OpenAI client, for consistent session binding at upstream gateways.
+- Added a `session-cache-analysis` skill for computing per-session prompt cache hit rates and diagnosing cache eviction.
+
+### Bug Fixes
+
+- Hashed tools by their OpenAI wire form instead of the raw `StructuredTool` dump, keeping `tools_hash`/`schema_hash` stable across agent rebuilds (previously embedded the function object's memory address).
+- Inserted pasted text at the cursor position in the TUI prompt instead of appending.
+- Persisted the model binding before agent rebuild and on exit.
+- Loaded the debug inspector HTML via `importlib.resources` for frozen (PyInstaller) builds.
+
+### Engineering
+
+- Removed the tool-response truncation middleware and its settings.
+- Deprecated the reversible compression middleware and reader.
+- Kept the AGENTS.md repository-layout table in sync with the current tree.
+
+---
+
+## v0.1.38
+
+### New Features
+
+- Added a native Rust OpenAI chat transport (`RustOpenAIClient`) backed by `synapse-core-tool`, used as an OpenAI-compatible model backend.
+- Added an interactive HITL approval block: turn events emit `APPROVAL_REQUIRED`, the transcript mounts an `ApprovalBlock`, and decisions route through `resume_hitl` without treating `WAITING_APPROVAL` as a blocking busy state.
+- Added a `session-crash-repair` skill for recovering crashed sessions.
+
+### Bug Fixes
+
+- Fixed `usage_metadata` mapping in the OpenAI model: `prompt_tokens_details`/`completion_tokens_details` now map to `input_token_details`/`output_token_details` (cache_read and reasoning were always 0), `prompt_cache_hit_tokens` is preferred for cache reads on DeepSeek-compatible gateways, and the async run manager is passed through `_astream` so `on_llm_new_token` fires and TTFT/token rates update live.
+- Fixed the TUI thought block collapsing when clicking the expanded reasoning body; the toggle is now restricted to the header row(s) and clicks that finish a text selection are ignored.
+
+### Engineering
+
+- Reused the OpenAI HTTP client across requests in the native Rust transport (`synapse-core-tool` v0.1.4).
+- Deferred markdown parsing of long restored transcript bodies to a worker (bounded plain-text preview first) and mounted restored blocks in chunks of 12 to avoid one giant layout pass.
+- Cached syntax highlighting across renders (`lru_cache`, cap 16k chars) so repeated redraws of code fences skip re-tokenizing.
+- Cached `SelectableStatic` renders so selection drags skip markdown re-rendering.
+
+---
+
 ## v0.1.37
 
 ### Engineering

{synapse_cli_agent-0.1.37 → synapse_cli_agent-0.1.39}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: synapse-cli-agent
-Version: 0.1.37
+Version: 0.1.39
 Summary: Local coding agent built on LangChain Deep Agents (LocalShell, no sandbox)
 Project-URL: Homepage, https://github.com/alex8224/synapse-agent
 Project-URL: Repository, https://github.com/alex8224/synapse-agent

{synapse_cli_agent-0.1.37 → synapse_cli_agent-0.1.39}/README.zh-CN.md

@@ -415,7 +415,6 @@ uv run synapse run "修复 calculator.sub 的 bug，使 tests 全部通过" -w t
 | `AGENT_MCP_CONFIG` | - | MCP servers JSON |
 | `CHECKPOINT_BACKEND` | `sqlite` | `sqlite` 或 `memory` |
 | `AGENT_SESSION_PREWARM_ENABLED` | `false` | 恢复大上下文会话后在后台预热 provider 缓存（首次请求仍按输入 token 计费；详见 `docs/config.md`） |
-| `AGENT_ENABLE_TOOL_RESPONSE_TRUNCATE` | `false` | 启用工具响应折叠（keep 窗口外的大工具输出压成摘要+引用，大上下文会话可省 20-30%；详见 `docs/config.md`） |
 | `INHERIT_ENV` | `true` | shell 继承主机环境 |
 | `VIRTUAL_MODE` | `true` | 文件路径虚拟根 |
 | `AGENT_SHOW_REASONING_PLACEHOLDERS` | `true` | 是否显示网关未暴露推理文本时的占位思考节点；Codex 加密推理可设为 `false` 隐藏 |

synapse_cli_agent-0.1.39/approval-behavior.md

@@ -0,0 +1,46 @@
+# 审批（Approval）行为说明
+
+结论：打开审批后，agent 在执行**写操作类工具前会暂停等待用户决定**，而不是直接拒绝或跳过。
+
+依据代码：`src/synapse/runtime/safety.py`、`src/synapse/runtime/hitl.py`、`src/synapse/app/agent.py`、`src/synapse/ui/turn/controller.py`、`src/synapse/commands/slash_cmds.py`。
+
+## 如何正确打开审批
+
+| 方式 | 说明 |
+| --- | --- |
+| 环境变量 `AGENT_SAFETY_PROFILE=dev-approve` | 推荐方式（可在 `.env` 或系统环境变量中设置） |
+| TUI 内 `/safety dev-approve` | 切换后重建 agent |
+| 档位别名 | `approve` / `hitl` / `dev_approve` 均映射到 `dev-approve` |
+
+> 注意：仅设 `AGENT_REQUIRE_APPROVAL=true` 或 CLI `--require-approval` **不会生效**。
+> agent 构建时 `apply_safety_to_settings` 会按 `safety_profile`（默认 `dev-autopass`）把 `require_approval` 强制改回 `false`。
+> 必须切换到 `dev-approve` 档。
+
+## 打开后的行为
+
+| 阶段 | 表现 |
+| --- | --- |
+| 需要审批的工具 | 仅 `execute`、`write_file`、`edit_file`、`patch` 四类（`build_interrupt_on` 返回）；`read_file`、`search_files` 等只读工具照常执行，不拦截 |
+| 触发时机 | agent 一旦尝试调用上述工具，LangGraph 在**执行前**中断（interrupt），回合状态变为 `WAITING_APPROVAL` |
+| TUI 界面 | 顶部活动区显示 `waiting / approval`；转录区打印待批清单：工具名、参数预览、描述，末尾提示 `decide: /approve | /reject [reason]` |
+| 用户操作 | `/approve` 放行；`/reject [reason]` 拒绝（可附理由） |
+
+## 审批决策的两种结果
+
+| 决策 | 行为 |
+| --- | --- |
+| `/approve` | 恢复图执行，工具真正运行，agent 继续后续步骤 |
+| `/reject [reason]` | 工具不执行，拒绝信息（默认 `Rejected by user via /reject` 或自定义 reason）作为反馈回传给模型，agent 会据此调整方案或换工具重试 |
+
+## 其他要点
+
+| 项 | 说明 |
+| --- | --- |
+| 多个工具同时待批 | `build_decisions` 会按待批数量生成等量决策；一次 `/approve` 放行全部 |
+| 无待批时 | `/approve` 或 `/reject` 会提示 `no pending approval`，不做事 |
+| 黑名单 | `dev-approve` 档 `enable_command_blacklist=True`，但 `check_command` 目前仅定义、未接入运行时；`rm -rf` 等危险命令不会自动拦截，仍走人工审批 |
+| ACP 客户端 | 通过 `_request_permission_decisions` 请求权限，超过 `_max_permission_turns` 时报 `maximum permission resume turns exceeded` |
+
+## 一句话总结
+
+开启审批（`dev-approve`）后，agent 每次写文件或执行命令前都会停下等待用户 `/approve` 或 `/reject`，只读操作不受影响。

{synapse_cli_agent-0.1.37 → synapse_cli_agent-0.1.39}/docs/architecture-flow.md

@@ -467,7 +467,7 @@ load_settings(**overrides):
 | 工作区 | workspace, shell_timeout(120s), max_output_bytes(100KB) | Path.cwd() |
 | 安全 | require_approval(False), safety_profile("dev-autopass") | -- |
 | 检查点 | checkpoint_backend("sqlite") | project/.synapse/ |
-| 工具输出 | enable_tool_output_transform(True), threshold_bytes(512) | -- |
+| 工具输出 | enable_tool_output_transform(False), threshold_bytes(512) | -- |
 | 子代理 | enable_subagents(True) | -- |
 | MCP | enable_mcp(True), mcp_eager(False) | -- |
 | UI | theme("cursor-dark"), history_tail_turns(20) | -- |

{synapse_cli_agent-0.1.37 → synapse_cli_agent-0.1.39}/docs/config.md

@@ -77,13 +77,6 @@ Synapse 使用 **Pydantic Settings** 实现分层配置系统。
 | `SESSION_SUMMARY_MAX_CHARS` | `600` | 本地会话摘要的最大字符数（含多轮条目，超出时从最旧条目开始裁剪） |
 | `AGENT_HISTORY_TAIL_TURNS` | `20` | TUI 从轻量 transcript 投影初始读取/渲染的最近可见会话轮数；滚动到顶部后按 turn 游标加载更早历史，最多挂载 5 页 |
 | `AGENT_SESSION_PREWARM_ENABLED` | `false` | 恢复大上下文会话后，在后台对该会话历史发起一次最小模型请求，让 provider 预填充并缓存历史前缀，用户第一条消息可命中缓存、大幅缩短首 token 等待。注意：预热本身会按输入 token 计费一次，仅在需要时开启 |
-| `AGENT_ENABLE_TOOL_RESPONSE_TRUNCATE` | `false` | 启用工具响应裁剪：keep 窗口（默认最近 40K tokens）外的 `execute`/`read_file`/`search_files` 输出折叠为摘要，减小每轮请求体积（大上下文会话可省 20-30%）。请求层变换，不修改历史 |
-| `AGENT_TOOL_RESPONSE_TRUNCATE_KEEP_TOKENS` | `40000` | 工具响应裁剪的 keep 窗口（token），窗口内消息不裁剪 |
-| `AGENT_TOOL_RESPONSE_TRUNCATE_MAX_HEAD_CHARS` | `2000` | 关闭 fold 模式时，超长输出保留的头部字符数 |
-| `AGENT_TOOL_RESPONSE_TRUNCATE_MAX_TAIL_CHARS` | `0` | 关闭 fold 模式时，超长输出额外保留的尾部字符数（>0 表示 head+tail） |
-| `AGENT_TOOL_RESPONSE_TRUNCATE_FOLD_ENABLED` | `true` | fold 模式：窗口外输出一律折叠（有 `tool-output://` 引用的可经 `read_tool_result` 找回原文，无引用的保留头部锚点） |
-| `AGENT_TOOL_RESPONSE_TRUNCATE_FOLD_HEAD_CHARS` | `300` | fold 模式下无引用输出保留的头部锚点字符数 |
-| `AGENT_TOOL_RESPONSE_TRUNCATE_TOOLS` | `["execute","read_file","search_files"]` | 参与折叠/裁剪的工具名单（JSON 数组） |
 
 ### 长程目标（Goals）
 

{synapse_cli_agent-0.1.37 → synapse_cli_agent-0.1.39}/docs/design.md

@@ -250,7 +250,9 @@ py-agent/
 │   └── design.md                 # 本方案
 ├── AGENTS.md                     # 项目级记忆/约定（给 agent 读）
 ├── skills/                       # 可选 skills（渐进披露）
-│   └── python-testing/
+│   ├── session-crash-repair/
+│   │   └── SKILL.md
+│   └── session-cache-analysis/
 │       └── SKILL.md
 ├── src/
 │   └── coding_agent/

{synapse_cli_agent-0.1.37 → synapse_cli_agent-0.1.39}/docs/skills.md

@@ -6,9 +6,9 @@ Skills 是 Synapse 的可扩展插件系统，位于项目 `skills/` 目录下
 
 ```
 skills/
-├── python-testing/
+├── session-cache-analysis/
 │   └── SKILL.md
-└── python-memory-diagnostics/
+└── session-crash-repair/
     └── SKILL.md
 ```
 
@@ -18,16 +18,16 @@ skills/
 
 ```markdown
 ---
-name: python-testing
-description: How to run and write Python tests in this project with uv and pytest.
-license: MIT
-compatibility: Requires uv and pytest in a Python 3.12+ project.
-allowed_tools: execute, run_tests, read_file, write_file, edit_file
+name: session-cache-analysis
+description: Analyze the prompt cache hit rate of a Synapse session (thread).
+license: Apache-2.0
+compatibility: Requires a synapse source checkout with uv and Python 3.12+.
+allowed_tools: execute, read_file, write_file, search_files, find_files, search_session, read_session
 ---
 
-# Python Testing Skill
+# Session Cache Hit-Rate Analysis
 
-## Running Tests
+## 数据来源
 ...
 ```
 
@@ -47,8 +47,8 @@ Synapse 自带两个 Skills：
 
 | Skill | 说明 |
 |---|---|
-| `python-testing` | 使用 uv + pytest 运行和编写测试 |
-| `python-memory-diagnostics` | 诊断 Python 进程内存问题 |
+| `session-crash-repair` | 检测并修复异常退出后 checkpoint 不一致的会话（悬挂工具调用、挂起图任务、过期转录投影） |
+| `session-cache-analysis` | 分析会话的 prompt 缓存命中率，区分增量 miss 与全量逐出并定位根因 |
 
 ## 如何编写自定义 Skill
 

{synapse_cli_agent-0.1.37 → synapse_cli_agent-0.1.39}/docs/tool-output-transform.md

@@ -18,7 +18,7 @@ All transforms are deterministic. Synapse uses a low-cost `512` byte prefilter,
 
 ```json
 {
-  "enable_tool_output_transform": true,
+  "enable_tool_output_transform": false,
   "tool_output_transform_threshold_bytes": 512,
   "tool_output_disabled_types": ["code"],
   "tool_output_transform_plugins": ["my_package.transforms:my_transformer"],
@@ -26,10 +26,12 @@ All transforms are deterministic. Synapse uses a low-cost `512` byte prefilter,
 }
 ```
 
+Tool-output transformation is **off by default** (`enable_tool_output_transform: false`); set it to `true` to enable.
+
 Environment equivalents:
 
 ```text
-AGENT_ENABLE_TOOL_OUTPUT_TRANSFORM=true
+AGENT_ENABLE_TOOL_OUTPUT_TRANSFORM=false
 AGENT_TOOL_OUTPUT_TRANSFORM_THRESHOLD_BYTES=512
 AGENT_TOOL_OUTPUT_DISABLED_TYPES=["code"]
 AGENT_TOOL_OUTPUT_TRANSFORM_PLUGINS=["my_package.transforms:my_transformer"]

{synapse_cli_agent-0.1.37 → synapse_cli_agent-0.1.39}/docs/tutorial.md

@@ -328,9 +328,9 @@ synapse-agent/                       # 项目根目录
 │   └── fixtures/                    # 测试 fixtures
 │
 ├── skills/                          # Agent Skills
-│   ├── python-testing/              # Python 测试技能
+│   ├── session-crash-repair/        # 会话崩溃修复技能
 │   │   └── SKILL.md                 # 技能定义文件
-│   └── python-memory-diagnostics/   # 内存诊断技能
+│   └── session-cache-analysis/      # 会话缓存命中率分析技能
 │       └── SKILL.md
 │
 ├── docs/                            # 文档
@@ -1073,20 +1073,20 @@ Skills 是给 Agent 的可加载"专业说明手册"。
 ### 10.1 Skill 文件格式
 
 ```markdown
-<!-- skills/python-testing/SKILL.md -->
+<!-- skills/session-cache-analysis/SKILL.md -->
 
 ---
-name: python-testing
-description: How to run and write Python tests in this project with uv and pytest.
-license: MIT
-allowed-tools: execute run_tests read_file write_file edit_file
+name: session-cache-analysis
+description: Analyze the prompt cache hit rate of a Synapse session (thread).
+license: Apache-2.0
+allowed-tools: execute read_file write_file search_files find_files
 ---
 
-# Python testing skill
+# Session cache hit-rate analysis
 
-## Run tests
+## Data source
 Prefer:
-`uv run pytest`
+`load_messages_from_sqlite_file(checkpoints.sqlite, thread_id)`
 
 ...
 ```
@@ -1114,8 +1114,8 @@ Agent 启动时会扫描 `skills/` 目录，将所有 Skill 的描述注入系
 
 ### 10.3 现有 Skills
 
-- **python-testing**: 告诉 Agent 如何正确地运行和编写 Python 测试
-- **python-memory-diagnostics**: 告诉 Agent 如何诊断 Python 进程的内存问题
+- **session-crash-repair**: 告诉 Agent 如何检测并修复异常退出后 checkpoint 不一致的会话
+- **session-cache-analysis**: 告诉 Agent 如何分析会话的 prompt 缓存命中率并定位逐出根因
 
 ### 10.4 如何创建新 Skill
 

{synapse_cli_agent-0.1.37 → synapse_cli_agent-0.1.39}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "synapse-cli-agent"
-version = "0.1.37"
+version = "0.1.39"
 description = "Local coding agent built on LangChain Deep Agents (LocalShell, no sandbox)"
 readme = "README.md"
 license = { file = "LICENSE" }

synapse_cli_agent-0.1.39/release_body.md

@@ -0,0 +1,21 @@
+## v0.1.39
+
+### New Features
+
+- Stamped session-affinity headers on model requests in both the Python runtime and the native Rust OpenAI client, for consistent session binding at upstream gateways.
+- Added a `session-cache-analysis` skill for computing per-session prompt cache hit rates and diagnosing cache eviction.
+
+### Bug Fixes
+
+- Hashed tools by their OpenAI wire form instead of the raw `StructuredTool` dump, keeping `tools_hash`/`schema_hash` stable across agent rebuilds (previously embedded the function object's memory address).
+- Inserted pasted text at the cursor position in the TUI prompt instead of appending.
+- Persisted the model binding before agent rebuild and on exit.
+- Loaded the debug inspector HTML via `importlib.resources` for frozen (PyInstaller) builds.
+
+### Engineering
+
+- Removed the tool-response truncation middleware and its settings.
+- Deprecated the reversible compression middleware and reader.
+- Kept the AGENTS.md repository-layout table in sync with the current tree.
+
+---