Merge remote-tracking branch 'upstream/main' into feat/replay-consistency-harness

git commitgit commit#:wq::q!:q!:q!q!

Author: k0mondor

.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/mkdocs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install MkDocs
+        run: python -m pip install --upgrade pip mkdocs
+
+      - name: Build documentation
+        run: mkdocs build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/release.yml

@@ -0,0 +1,89 @@
+name: Auto Release when Tag
+on:
+  push:
+    tags:
+      - 'v*'
+      - 'test/v*'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    runs-on: [self-hosted, trpc-agent-python-ci]
+    timeout-minutes: 30
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install release dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements-test.txt
+          pip install build twine flake8 yapf
+
+      - name: Validate tag version
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#test/v}"
+          TAG_VERSION="${TAG_VERSION#v}"
+          PACKAGE_VERSION=$(python -c "from trpc_agent_sdk.version import __version__; print(__version__)")
+          if [ "$TAG_VERSION" != "$PACKAGE_VERSION" ]; then
+            echo "::error::Tag version '$TAG_VERSION' does not match package version '$PACKAGE_VERSION'."
+            exit 1
+          fi
+
+      - name: Get changed Python files
+        id: changed
+        run: |
+          FILES=$(git diff --name-only --diff-filter=ACM HEAD~1...HEAD -- '*.py' | grep '^trpc_agent_sdk/' || true)
+          if [ -z "$FILES" ]; then
+            echo "has_files=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_files=true" >> "$GITHUB_OUTPUT"
+            echo "$FILES" > "$RUNNER_TEMP/changed_py_files.txt"
+            echo "Changed Python files:"
+            echo "$FILES"
+          fi
+
+      - name: Check formatting with YAPF
+        if: steps.changed.outputs.has_files == 'true'
+        run: |
+          FILES=$(cat "$RUNNER_TEMP/changed_py_files.txt" | tr '\n' ' ')
+          diff_output=$(yapf --diff $FILES) || true
+          if [ -n "$diff_output" ]; then
+            echo "$diff_output"
+            echo "::error::Code formatting check failed for changed files. Run 'yapf -i <file>' to fix."
+            exit 1
+          fi
+
+      - name: Lint with flake8
+        if: steps.changed.outputs.has_files == 'true'
+        run: |
+          FILES=$(cat "$RUNNER_TEMP/changed_py_files.txt" | tr '\n' ' ')
+          flake8 $FILES
+
+      - name: Run tests with coverage
+        run: |
+          pytest --cov=trpc_agent_sdk --cov-report=xml --cov-report=term --cov-fail-under=80 tests/
+
+      - name: Build package
+        run: |
+          python -m build
+
+      - name: Check package
+        run: |
+          python -m twine check dist/*
+
+      - name: Publish to PyPI
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          python -m twine upload dist/*
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}

CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [1.1.12](https://github.com/trpc-group/trpc-agent-python/releases/tag/v1.1.12) (2026-07-10)
+
+### Features
+
+* Agent: Added support for dynamically created sub-agents to forward runtime events directly into the parent agent event stream, so callers can observe child-agent progress, tool activity, and final outputs without waiting for the whole delegated task to finish.
+* Agent: Added dynamic sub-agent creation support, allowing agents to create and use child agents at runtime for more flexible task decomposition and delegation.
+* Goal: Added Goal support aligned with the Go implementation, giving agents a structured way to carry task objectives through the execution flow.
+* A2A: Added optional `app_name` support to `TrpcA2aAgentService`, allowing the Runner app identity to differ from the exposed A2A service name while keeping the existing `service_name` fallback behavior.
+* Session: Updated `list_sessions()` so `user_id` can be omitted. When `user_id=None`, InMemory, SQL, Redis, and Eval session services now return all sessions under the specified `app_name` without loading session events.
+* Skill: Added the `skills_hub` module to support centralized skill discovery and management.
+
+### Bug Fixes
+
+* Graph: Fixed `GraphAgent` `AgentNode.last_response` so it no longer records thinking text or intermediate tool-call round text as the node's final response. The graph now uses `Event.is_final_response()` and removes thinking content before saving the last response.
+* A2A: Fixed internal pipeline example scripts and paths so the example workflow can be triggered and run with the expected files.
+* Docs: Fixed README optional dependency installation commands by quoting extras, removing extra spaces, and normalizing package-extra casing so shell parsing works correctly.
+
+### Docs
+
+* Docs: Added MkDocs site entry pages and navigation for the existing English and Chinese documentation, plus a GitHub Pages workflow so the README documentation badge can point to a published documentation site.
+* Docs: Added documentation and test coverage for listing sessions across all users under an app by passing `user_id=None`.
+
+### Internal
+
+* CI: Added and adjusted internal pipeline test trigger files used by repository automation.
+
 ## [1.1.11](https://github.com/trpc-group/trpc-agent-python/releases/tag/v1.1.11) (2026-06-26)
 
 ### Features

README.md

@@ -84,7 +84,7 @@ pip install trpc-agent-py
 Install optional capabilities as needed:
 
 ```bash
-pip install trpc-agent-py[a2a,ag-ui,knowledge,agent-claude,mem0, Mempalace, langfuse]
+pip install "trpc-agent-py[a2a,ag-ui,knowledge,agent-claude,mem0,mempalace,langfuse]"
 ```
 
 ### Develop Weather Agent

README.zh_CN.md

@@ -84,10 +84,9 @@ pip install trpc-agent-py
 按需安装扩展能力：
 
 ```bash
-pip install trpc-agent-py[a2a,ag-ui,knowledge,agent-claude,mem0, Mempalace, langfuse]
+pip install "trpc-agent-py[a2a,ag-ui,knowledge,agent-claude,mem0,mempalace,langfuse]"
 ```
 
-
 ### 开发天气查询Agent
 
 ```python

docs/mkdocs/en/index.md

@@ -0,0 +1,21 @@
+# English Documentation
+
+Welcome to the English documentation for tRPC-Agent-Python.
+
+## Getting Started
+
+- [LLM Agent](./llm_agent.md): Build a general-purpose LLM-powered agent.
+- [Model Invocation](./model.md): Configure OpenAI, Anthropic, and LiteLLM models.
+- [Tools](./tool.md): Add function tools, file tools, MCP tools, and agent tools.
+- [Skills](./skill.md): Package reusable workflows with `SKILL.md`.
+- [Code Executor](./code_executor.md): Execute code through local or sandboxed runtimes.
+
+## Core Capabilities
+
+- [Session](./session.md): Manage conversation events and state.
+- [Memory](./memory.md): Store and retrieve long-term memories.
+- [Knowledge](./knowledge.md): Build RAG workflows with LangChain components.
+- [Multi-Agent](./multi_agents.md): Compose agents for complex workflows.
+- [Evaluation](./evaluation.md): Evaluate agent behavior and response quality.
+
+For source code and examples, see the [GitHub repository](https://github.com/trpc-group/trpc-agent-python).

docs/mkdocs/en/session.md

@@ -109,11 +109,18 @@ session = await session_service.get_session(
 
 **List Sessions**:
 ```python
+# Specify user_id: returns all sessions for that user (without events)
 session_list = await session_service.list_sessions(
     app_name="my_app",
     user_id="user_001"
 )
-# Returns ListSessionsResponse, containing all sessions for the user (without events)
+
+# user_id=None: returns sessions across all users for the app
+all_session_list = await session_service.list_sessions(
+    app_name="my_app",
+    user_id=None
+)
+# Returns ListSessionsResponse, containing matching sessions (without events)
 ```
 
 **Delete Session**:
@@ -128,7 +135,7 @@ await session_service.delete_session(
 **Implementation Logic** (`_base_session_service.py`):
 - `create_session`: Creates a session, separates and stores app/user/session state
 - `get_session`: Retrieves a session, merges app/user/session state, applies event filtering
-- `list_sessions`: Lists sessions (excludes events to reduce data transfer)
+- `list_sessions`: Lists sessions (excludes events to reduce data transfer); passing `user_id=None` returns sessions across all users for the app
 - `delete_session`: Deletes a session and its associated data
 
 ---
@@ -611,6 +618,7 @@ session = await session_service.get_session(
 )
 
 # List existing Sessions
+# Specify user_id to return that user's sessions; user_id=None returns sessions across all users for the app
 session_list = await session_service.list_sessions(
     app_name=app_name,
     user_id=user_id

docs/mkdocs/en/sub_agent.md

@@ -21,6 +21,19 @@ A **short-lived sub-agent** is a natural fit for these problems: a fresh context
 
 The difference is *who defines the role*: the developer (Spawn) or the LLM (Dynamic).
 
+### How this differs from other multi-agent mechanisms
+
+The framework already offers several ways to compose agents (see [Multi Agents](multi_agents.md)). Spawned Sub-Agents solve a different problem:
+
+| Mechanism | Agents involved | Who decides when to invoke | Context | Typical use |
+| --- | --- | --- | --- | --- |
+| **Chain / Parallel / Cycle Agent** | **Pre-built** fixed agent instances | **Deterministic** orchestration — run in list order / in parallel / in a loop, regardless of input | Each agent independent | Fixed multi-step workflows |
+| **Sub Agents (transfer)** | Pre-registered agents | Parent **transfers control** at runtime; the sub-agent then takes over the conversation | Shared session | **Hand off** the whole conversation to a better-suited agent |
+| **AgentTool** | Wraps **an existing agent instance** as a tool | Parent LLM calls it on demand | Shares/syncs state & artifacts back to parent | Reuse a **specific, already-built** agent |
+| **Spawned Sub-Agents** | **Created on the fly** per call, destroyed after | Parent LLM calls it on demand | **Strictly isolated**: fresh ephemeral session, history/state not shared by default | Delegate a **one-off** subtask while keeping the parent context clean |
+
+In one line: **Chain/Parallel/Cycle** deterministically orchestrate a fixed set of agents; **transfer** hands the conversation off; **AgentTool** reuses one existing agent as a tool; while **Spawned Sub-Agents** create an **isolated, short-lived** sub-agent on the spot for a single task and discard it afterward — the emphasis is on **on-demand runtime creation** and **context isolation**, not reusing an existing agent or transferring control.
+
 ## Quick Start
 
 ```python
@@ -173,8 +186,19 @@ class SubAgentConfig:
 
     max_turns: int | None = None
     """Max LLM calls the sub-agent may make. None = unlimited."""
+
+    forward_events: bool = False
+    """Whether to forward the sub-agent's execution events to the parent
+    runner's consumer as progress updates.
+
+    True: the orchestrator can display the sub-agent's execution live (model
+    output, tool calls, tool results); the parent agent's LLM still receives
+    only the sub-agent's final result. False (default): the sub-agent runs
+    silently and only its final result is returned."""
 ```
 
+Forwarded events reach the consumer as progress events; they are **not** written to the parent session and **never** enter the parent agent's LLM context. Consumers identify them via `tool_progress=True` on `event.custom_metadata` and read the execution from `payload` (`author` / `partial` / `content`, plus optional `error` / `usage`).
+
 ## Usage
 
 ### SpawnSubAgentTool
@@ -270,3 +294,4 @@ orchestrator = LlmAgent(
 - **Session isolation**: sub-agents run in a fresh ephemeral session. Parent history is not shared by default; opt in via `include_parent_history=True`.
 - **Nesting**: 1-level hard cap. Sub-agents cannot spawn further sub-agents.
 - **Result shape**: the sub-agent's final text is returned as the tool result string.
+- **Live execution (`forward_events`)**: set `SubAgentConfig(forward_events=True)` to stream the sub-agent's execution to the parent runner's consumer for display. Forwarded events are progress events — they never enter the parent LLM's context, which still receives only the final result. Consumers detect them via `tool_progress=True` on `event.custom_metadata` and read `payload`. See `examples/dynamic_subagent` and `examples/spawn_subagent` for a working consumer.

docs/mkdocs/index.md

@@ -0,0 +1,23 @@
+# tRPC-Agent-Python Documentation
+
+tRPC-Agent-Python is a production-grade Agent framework deeply integrated with the Python AI ecosystem. It provides an end-to-end foundation for agent building, orchestration, tool integration, session and long-term memory, service deployment, and observability.
+
+Choose a language to get started:
+
+- [English Documentation](./en/)
+- [中文文档](./zh/)
+
+## Quick Links
+
+- [LLM Agent](./en/llm_agent.md)
+- [Model Invocation](./en/model.md)
+- [Tools](./en/tool.md)
+- [Skills](./en/skill.md)
+- [Code Executor](./en/code_executor.md)
+- [Session](./en/session.md)
+- [Memory](./en/memory.md)
+
+## Project
+
+- [GitHub Repository](https://github.com/trpc-group/trpc-agent-python)
+- [PyPI Package](https://pypi.org/project/trpc-agent-py/)

docs/mkdocs/zh/index.md

@@ -0,0 +1,21 @@
+# 中文文档
+
+欢迎阅读 tRPC-Agent-Python 中文文档。
+
+## 快速开始
+
+- [LLM Agent](./llm_agent.md)：构建通用 LLM Agent。
+- [模型调用](./model.md)：配置 OpenAI、Anthropic 和 LiteLLM 模型。
+- [工具](./tool.md)：接入函数工具、文件工具、MCP 工具和 Agent 工具。
+- [Skills](./skill.md)：通过 `SKILL.md` 封装可复用工作流。
+- [代码执行器](./code_executor.md)：通过本地或沙箱运行时代码执行。
+
+## 核心能力
+
+- [Session](./session.md)：管理会话事件与状态。
+- [Memory](./memory.md)：存储和检索长期记忆。
+- [Knowledge](./knowledge.md)：基于 LangChain 组件构建 RAG 工作流。
+- [多 Agent](./multi_agents.md)：编排多个 Agent 完成复杂任务。
+- [Evaluation](./evaluation.md)：评测 Agent 行为和回复质量。
+
+源码与示例请参考 [GitHub 仓库](https://github.com/trpc-group/trpc-agent-python)。