Feature/advanced memory

.flake8

@@ -1,3 +1,3 @@
 [flake8]
 max-line-length = 120
-ignore = E402, W503
+ignore = E402, W503, W504

.github/code_review/prompts/findings.md

@@ -1,4 +1,11 @@
-你现在的任务不是重新做代码审查，而是将已经生成的 `review.md` 提取为结构化结果，供后续脚本用于行内评论、阻断判断和其他自动化处理。
+最高优先级输出协议：
+1. 整个回复只能包含一个 JSON 对象，除此之外不能出现任何字符。
+2. 回复的第一个字符必须是 `{`，最后一个字符必须是 `}`。
+3. 读取文件、分析问题、确认行号和核对结果的过程必须静默完成，不得输出进度、思考过程、问题清单、总结或完成提示。
+4. 禁止输出“我已确认”“现在生成”“基于 review.md”“共发现”“让我分析”“已经完成”等过程性文字。
+5. 即使定位失败或信息不足，也必须直接按下述格式输出 JSON；通过保守字段值和 `inline_candidate=false` 表达，不得在 JSON 外解释原因。
+
+你现在的任务不是重新做代码审查，而是将已经生成的 `review.md` 提取为结构化结果，供后续脚本用于行内评论和其他自动化处理。
 
 输入文件：
 1. 仓库根目录下的 `review.md`：这是主依据，包含第一阶段已经确认的问题。
@@ -17,8 +24,7 @@
 - `Warning` -> `warning`
 - `Suggestion` -> `suggestion`
 
-输出 JSON 格式：
-```json
+输出 JSON 的结构必须是：
 {
   "findings": [
     {
@@ -32,7 +38,6 @@
     }
   ]
 }
-```
 
 字段要求：
 1. `severity`：必须是 `critical`、`warning`、`suggestion` 之一。
@@ -52,13 +57,14 @@
 2. 如果一个问题已经在第一阶段被合并表述为一个综合问题（例如“命令注入 + 路径穿越”），不要在这里再次拆分成多个新问题，除非 `review.md` 本身已经明确拆开。
 3. `body` 不要照抄整段 review 原文；应提炼成适合行内评论展示的短说明。
 4. 不允许因为定位失败、信息缺失或不适合行内评论而省略第一阶段已经明确列出的问题；这类问题必须保留在 `findings` 中，并通过 `inline_candidate=false` 与保守字段值表达。
-5. 如果 `review.md` 中没有任何问题，输出：
-```json
-{"findings":[]}
-```
+5. 如果 `review.md` 中没有任何问题，唯一输出为 `{"findings":[]}`。
 
 校验要求：
-1. 输出必须能被标准 JSON 解析器直接解析。
-2. 所有字符串必须使用双引号。
-3. 不要在 JSON 外再输出任何额外字符。
-4. 不要输出 ```json 或 ```，也不要输出任何注释。
+1. 输出必须能被标准 JSON 解析器直接解析，等价于 Python `json.loads` 可以一次解析成功。
+2. 所有属性名和字符串必须使用双引号，不能使用单引号代替。
+3. 字符串内部的双引号、反斜杠、换行符等特殊字符必须按照 JSON 规范转义。
+4. 数组和对象的最后一个元素后不能有多余逗号。
+5. 不要输出 Markdown 代码块、注释、前后缀、空行或任何解释文字。
+6. 输出前在内部静默检查：内容只能有一个顶层对象，并且只能从 `{` 开始、到 `}` 结束。
+
+现在开始静默处理。最终回复只能是 JSON，第一个字符必须是 `{`。

.gitignore

@@ -4,6 +4,7 @@
 *.lock
 *.log
 examples/*.log
+examples/tool_safety/real_agent_safety_audit.jsonl
 
 trpc-agent-py.egg-info
 

CHANGELOG.md

@@ -1,5 +1,92 @@
 # Changelog
 
+## [1.1.19](https://github.com/trpc-group/trpc-agent-python/releases/tag/v1.1.19) (2026-08-21)
+
+Version bump to keep the `main` and `r0.1` branches in sync; carries forward the fixes already included in 1.1.18 (LLM streaming interruption span fixes and CI extension package installation).
+
+## [1.1.18](https://github.com/trpc-group/trpc-agent-python/releases/tag/v1.1.18) (2026-08-21)
+
+### Bug Fixes
+
+* Telemetry: Fixed `agent_run` and runner spans misreporting success with empty output when LLM streaming output was interrupted mid-stream (network interruption, model business error, or a retry-swallowed failure on a later turn after a tool call).
+  * Error responses no longer clear the partial text already streamed; the span is now marked as failed and the accumulated output is preserved with an `[INTERRUPTED]` prefix.
+  * In multi-turn runs, the interrupted text is appended after already-collected turn content instead of being dropped.
+  * The `call_llm` span's `llm_response` attribute now also backfills the already-streamed content when the retry layer converts a raised exception into a terminal error response.
+
+### Internal
+
+* CI: Added extension package installation to `pipeline_test/run_all_examples.sh` so the full set of examples can be run in CI.
+
+## [1.1.17](https://github.com/trpc-group/trpc-agent-python/releases/tag/v1.1.17) (2026-08-19)
+
+### Features
+
+* Telemetry: Langfuse export now preserves user-defined span attributes. Fields prefixed with `langfuse` are passed through as-is; other custom attributes are collected into metadata so teams can observe custom instrumentation alongside built-in trace data.
+
+### Bug Fixes
+
+* AG-UI: Fixed AGUI connections being closed too early when an `AgentNode` emitted an error `Event`. The server no longer sends `RunErrorEvent` immediately on the first error event; it waits until the final event carries an error after the agent run has finished. This allows agents such as `GraphAgent` to continue executing subsequent nodes instead of terminating the client connection prematurely.
+* Telemetry: Fixed four classes of span status and output loss during agent interruption or failure:
+  * Runner initialization failures now report error status through `trace_runner()` even when `InvocationContext` is not yet available (`invocation_context` is optional), while still writing the remaining runner business attributes.
+  * LLM call failures converted by the retry layer into `LlmResponse(error_code=...)` are no longer recorded as successful spans; trace reporting now checks `llm_response.error_code`.
+  * External cancellation via `asyncio.CancelledError` now marks the root invocation span as failed and preserves accumulated partial streamed text instead of leaving the span successful with missing output.
+  * `GeneratorExit` during generator shutdown now backfills partial streamed text into `agent_action`, preventing already emitted content from being lost when the client disconnects or the stream is closed early.
+
+### Internal
+
+* Build: Optimized installation speed for faster dependency setup and project bootstrap.
+
+## [1.1.16](https://github.com/trpc-group/trpc-agent-python/releases/tag/v1.1.16) (2026-08-11)
+
+### Features
+
+* Model: Added OpenAI Responses API support in `OpenAIModel`, including streaming, tool calls, and related adapter integration, so agents can use the Responses API alongside existing chat-completions flows.
+* Graph: Strengthened `GraphAgent` human-in-the-loop support and resume behavior, including clearer HITL event handling, checkpoint recovery, and AG-UI integration updates for interrupted graph runs.
+* Agent: Added configurable run limits for `LlmAgent` through `AgentRunLimits`, allowing callers to cap total turns, LLM calls, and tool calls and fail fast when a budget is exceeded.
+* Eval/Optimization: Added an evaluation-and-optimization closed loop, covering pipeline config validation, standardized evaluation, failure attribution, case diff analysis, gate/budget decisions, real optimizer write-back, atomic report publishing, audit indexing, and offline model / trace replay validation.
+* Examples: Added `examples/optimization/eval_optimize_loop` for the evaluation-optimization workflow and `examples/llmagent_with_limit` for demonstrating agent run limits.
+
+### Bug Fixes
+
+* Tools: Fixed `BashTool` whitelist validation so every executable segment in standalone commands, pipelines, and compound shell syntax (`;`, `&&`, `||`, newlines, background `&`) is checked. Heredoc bodies are treated as data, and unverifiable substitution syntax now fails closed.
+* Code Execution: Deferred `docker` and `python-magic` imports to first use, preventing import-time hangs or crashes on Windows and other environments without Docker Desktop or libmagic installed.
+* Telemetry: Fixed missing trace reporting when LLM calls are cancelled with `GeneratorExit` after a client disconnects during deployed service runs.
+* Eval/Optimization: Hardened report publishing, credential redaction, telemetry completeness, and config snapshot handling so optimization artifacts do not leak secrets or publish partial state.
+
+### Docs
+
+* Docs: Added English and Chinese documentation for OpenAI Responses API usage, GraphAgent HITL/resume behavior, and `LlmAgent` run-limit configuration.
+
+### Internal
+
+* CI: Optimized code-review prompt output to reduce blocking review noise.
+* CI: Improved full pipeline example execution coverage in `pipeline_test/run_all_examples.sh`.
+* Code Execution: Follow-up lazy-import fixes for Docker CLI helpers and content-type detection, including thread-safe magic probing and test compatibility updates.
+
+## [1.1.15](https://github.com/trpc-group/trpc-agent-python/releases/tag/v1.1.15) (2026-08-03)
+
+### Features
+
+* Tools: Added a Tool Script Safety Guard that scans Bash / Python scripts before execution and returns `allow` / `deny` / `needs_human_review`. It covers dangerous commands, sensitive path access, dependency installs, unknown network calls, and privilege escalation, and can be enabled on `BashTool`, local code executors, Skill, and MCP tool flows.
+* Tools: Added configurable safety policies, custom rule registration, JSONL audit logs, and telemetry attributes so teams can tune what to block, what to review, and how to observe safety decisions.
+* Testing: Added a Session / Memory / Summary multi-backend replay consistency framework. The same agent trajectories can be replayed on InMemory, SQLite, and optional Redis backends to compare events, state, memory, and summary results, with known SQLite summary drift reported instead of silently ignored.
+* Examples: Added a Skill-based code review agent example, including sandbox execution, review report generation, and policy filters for reviewing diffs / repositories more safely.
+* Examples: Added PostgreSQL storage support to the code review agent example, so review records can be persisted beyond the default SQLite backend.
+* Examples: Added pytest configuration and failure fallback handling for evaluation examples, making evaluation runs more resilient when individual cases fail.
+
+### Bug Fixes
+
+* Tools: Fixed `ToolSafetyFilter` only scanning the first non-empty script-like argument. It now scans all recognized fields such as `script` / `code` / `command` / `cmd` / `python_code` / `bash_code` / `code_blocks`, including mixed-language requests, so a safe earlier field can no longer hide a later dangerous command.
+* Tools: For unknown-language segments, keep running Bash rules but only merge Python findings when AST parsing succeeds. This avoids `PY_PARSE_ERROR_REVIEW` false positives that could block safe Bash scripts under strict review mode.
+* Model: Fixed Hunyuan hy3 conversations breaking the thinking chain when later turns omitted thinking content. Thinking text is now preserved when the model requires it for follow-up calls.
+* Model: Fixed tool calls being dropped when the model returned invalid JSON tool arguments. The SDK now tries `json_repair` first, and if repair fails it returns a parameter error to the agent instead of silently discarding the call.
+* Telemetry: Fixed missing traces for model retries and model call failures. Retry attempts and failure details are now recorded on the corresponding spans.
+
+### Docs
+
+* Docs: Added Tool Script Safety Guard design notes, policy examples, response schema examples, and a real-agent demo covering Tool / Skill / MCP / CodeExecutor allow-review-deny scenarios.
+* Docs: Expanded replay consistency README and implementation notes, including positive consistency checks and negative injection detection cases.
+
 ## [1.1.14](https://github.com/trpc-group/trpc-agent-python/releases/tag/v1.1.14) (2026-07-24)
 
 ### Features

INSTALL.md

@@ -65,7 +65,7 @@ Install optional extensions:
 
 ```bash
 # Choose as needed, multiple extensions can be combined with commas
-pip install "trpc-agent-py[a2a,knowledge,agent-claude]"
+pip install "trpc-agent-py[graph,a2a,knowledge,knowledge-hf,agent-claude]"
 ```
 
 ---
@@ -77,47 +77,73 @@ pip install "trpc-agent-py[a2a,knowledge,agent-claude]"
 git clone https://github.com/trpc-group/trpc-agent-python.git
 cd trpc-agent-python
 # Create and activate a virtual environment
-python3 -m venv .venv
+./build.sh
 source .venv/bin/activate        # Linux / macOS
 # .venv\Scripts\activate         # Windows
-# Install
-pip install -e .
 ```
 
 ### uv Installation
 
-[uv](https://docs.astral.sh/uv/) manages the Python toolchain, virtual environment and dependencies based on the repository's `pyproject.toml` for fast, reproducible installs. This project provides a script for one-shot setup on macOS:
+[uv](https://docs.astral.sh/uv/) provides fast dependency installation.
+
+#### Install in a user project (recommended)
+
+```bash
+# Install uv if it is not already available
+python -m pip install uv
+
+# Install the published package in a virtual environment
+uv venv --python 3.12
+source .venv/bin/activate
+uv pip install trpc-agent-py
+
+# Install optional capabilities as needed
+# uv pip install "trpc-agent-py[graph,a2a,knowledge,knowledge-hf,agent-claude]"
+```
+
+For a project managed by uv:
+
+```bash
+# Core package only
+uv add trpc-agent-py
+# Or: core + optional extras (one command is enough)
+# uv add "trpc-agent-py[graph,a2a,knowledge,knowledge-hf,agent-claude]"
+```
+
+#### Develop this repository from source
+
+After cloning the repository, use the same cross-platform build script:
 
 ```bash
 git clone https://github.com/trpc-group/trpc-agent-python.git
 cd trpc-agent-python
 
-# Install uv on macOS (see https://docs.astral.sh/uv/getting-started/installation/)
-curl -LsSf https://astral.sh/uv/install.sh | sh
-
-# One-shot setup
-bash build_mac_uv.sh
+./build.sh uv
 
-# add optional extras
-EXTRAS="a2a knowledge" bash build_mac_uv.sh
+# Or: core + optional extras (one command is enough; installer defaults to uv)
+# ./build.sh "[dev,graph,a2a,knowledge,knowledge-hf]"
+# ./build.sh uv "[dev,graph,a2a,knowledge,knowledge-hf]"
+source .venv/bin/activate
 ```
 
 Or run the steps manually:
 
 ```bash
 uv venv --python-preference only-system   # use the local Python
 uv sync --extra dev                       # core + dev tooling
-uv sync --extra a2a --extra knowledge     # add optional extras
+uv sync --extra graph --extra a2a --extra knowledge --extra knowledge-hf
 uv sync                                   # production install (core only)
 
-# Run commands inside the environment without activating it for evaluation
+# Run commands inside the environment without activating it
 uv run python -c "from trpc_agent_sdk.version import __version__; print(__version__)"
 ```
 
 To speed up downloads via a mirror, pass `--default-index`, e.g.:
 
 ```bash
 uv sync --default-index https://mirrors.cloud.tencent.com/pypi/simple
+# Or in a user project:
+# uv pip install trpc-agent-py --index-url https://mirrors.cloud.tencent.com/pypi/simple
 ```
 
 ### Optional Dependencies Reference
@@ -127,7 +153,9 @@ uv sync --default-index https://mirrors.cloud.tencent.com/pypi/simple
 | `a2a`            | Google A2A protocol           | `pip install "trpc-agent-py[a2a]"`            |
 | `ag-ui`          | AG-UI protocol                | `pip install "trpc-agent-py[ag-ui]"`          |
 | `agent-claude`   | Claude Agent                  | `pip install "trpc-agent-py[agent-claude]"`   |
+| `graph`          | LangGraphAgent and graph DSL (includes langchain) | `pip install "trpc-agent-py[graph]"`          |
 | `knowledge`      | Knowledge base / RAG          | `pip install "trpc-agent-py[knowledge]"`      |
+| `knowledge-hf`   | Hugging Face embeddings       | `pip install "trpc-agent-py[knowledge-hf]"`   |
 | `mem0`           | Long-term memory (Mem0)       | `pip install "trpc-agent-py[mem0]"`           |
 | `langchain_tool` | LangChain Tool integration    | `pip install "trpc-agent-py[langchain_tool]"` |
 | `langfuse`       | Langfuse observability        | `pip install "trpc-agent-py[langfuse]"`       |
@@ -163,6 +191,7 @@ TRPC_AGENT_MODEL_NAME="your-model-name"
 **Option 2**: Export directly to the shell environment
 
 ```bash
+# Export environment variables
 export TRPC_AGENT_API_KEY="your-api-key"
 export TRPC_AGENT_BASE_URL="your-base-url"
 export TRPC_AGENT_MODEL_NAME="your-model-name"
@@ -202,6 +231,7 @@ Expected output:
 ```
 All core modules imported successfully.
 ```
+
 ### Run Unit Tests
 
 ```bash
@@ -220,10 +250,10 @@ pytest tests/ -v
 **Solution**: Use a mirror to speed up downloads.
 
 ```bash
-# Temporary usage Tencent Cloud mirror
+# Temporary usage
 pip install trpc-agent-py -i https://mirrors.cloud.tencent.com/pypi/simple
 
-# Set global Tencent Cloud mirror
+# Set global mirror
 pip config set global.index-url https://mirrors.cloud.tencent.com/pypi/simple
 ```
 
@@ -243,10 +273,10 @@ Other available mirrors:
 ERROR: Package 'trpc-agent-py' requires a different Python: 3.9.x not in '>=3.10'
 ```
 
-**Solution**: Upgrade to Python 3.12.
+**Solution**: Upgrade to Python3.12.
 
 ```bash
-# Solution 1: Using pyenv to install Python 3.12
+# Solution 1: Using pyenv to install Python3.12
 pyenv install 3.12
 pyenv local 3.12