chore(release): prepare ksadk 0.6.9 public candidate

.github/pull_request_template.md

@@ -6,7 +6,7 @@
 
 - [ ] `uv run --extra dev pytest -q`
 - [ ] `make public-audit`
-- [ ] `make public-docs-build`
+- [ ] `make docs-site-build`
 - [ ] `make open-source-audit-dist` if package artifacts changed.
 - [ ] `uv build`
 - [ ] `uv run --extra dev python -m twine check dist/*`

.github/workflows/ci.yml

@@ -12,7 +12,7 @@ jobs:
   test:
     runs-on: ubuntu-latest
     env:
-      KSADK_WEB_VERSION: "0.2.16"
+      KSADK_WEB_VERSION: "0.2.18"
     steps:
       - uses: actions/checkout@v4
 
@@ -46,24 +46,13 @@ jobs:
         run: uv build
 
       - name: Run public release gate tests
-        run: |
-          uv run --extra dev pytest \
-            tests/test_open_source_audit.py \
-            tests/test_runtime_common_packaging.py \
-            tests/test_public_release_positioning.py \
-            tests/test_tracing_setup_otlp.py \
-            tests/test_check_publication_state.py \
-            tests/test_check_approval_record.py \
-            tests/test_markdown_repair.py \
-            tests/test_conversation_runtime.py \
-            tests/test_server_session_app.py \
-            -q
+        run: make public-test
 
       - name: Audit public repository candidate
         run: uv run --extra dev python scripts/open_source_audit.py --target public-repo
 
       - name: Build and audit public docs
-        run: make public-docs-build
+        run: make docs-site-build
 
       - name: Check package metadata
         run: uv run --extra dev python -m twine check dist/*

.github/workflows/publish-pypi.yml

@@ -9,7 +9,10 @@ on:
       ksadk_web_version:
         description: KsADK Web npm version to bundle
         required: false
-        default: "0.2.16"
+        default: "0.2.18"
+      approved_source_commit:
+        description: Reviewed source commit SHA recorded in docs/maintainer-approval-record.md
+        required: false
 
 permissions:
   contents: read
@@ -26,7 +29,8 @@ jobs:
     environment:
       name: pypi
     env:
-      KSADK_WEB_VERSION: ${{ github.event.inputs.ksadk_web_version || '0.2.16' }}
+      KSADK_WEB_VERSION: ${{ github.event.inputs.ksadk_web_version || '0.2.18' }}
+      KSADK_APPROVED_SOURCE_COMMIT: ${{ github.event.inputs.approved_source_commit || vars.KSADK_APPROVED_SOURCE_COMMIT }}
     permissions:
       contents: read
       id-token: write

AGENTS.md

@@ -37,7 +37,7 @@
 - `ksadk.skills` / `ksadk.skills.runtime` 是 Skill Runtime 上层应用，负责 Skill Center 消费、包校验、安全解压、loader、工具定义和 `execute_skills` 编排。
 - E2B backend 是当前优先实现路径；后续可扩展 KOP / 平台私有 backend，但业务逻辑不要写死到 E2B 特定对象。
 - ADK Runner 可做自动工具注入；LangGraph / DeepAgents 等已编译 graph 默认提供 helper 或显式接入，不强行魔改用户 graph。
-- 沙箱镜像内最小 agent 交付物以 `deploy/skill-runtime/` 为准。
+- 沙箱镜像内最小 agent 交付物以 `ksadk/skills/runtime/agent.py` 为准；顶层 `deploy/` 已迁出本仓。
 - Skill Service 管注册、CRUD、版本治理；KsADK 只消费运行时必要接口，例如 `ListSkillsBySpaceId`、`GetSkillDownloadUrl`。
 
 ## 5. 跨仓边界
@@ -83,13 +83,14 @@
 - 未经用户明确批准，不得改 `pyproject.toml` / `ksadk/version.py` 版本号，不得新增或改写 CHANGELOG 发版条目。
 - 用户批准发布后，正式 PyPI 发布优先走 GitHub Release / `workflow_dispatch` 触发的 Trusted Publishing；本地 `make publish` / `make publish-test` 仅作为明确批准的应急路径，不绕过 Makefile 手写上传命令。
 - 不得在同一轮协作中擅自连续发布多个版本承载中间修复。
-- `master` 是内部开发主干；GitHub `main` 是公开主干。不得直接 `merge master -> main`，公开同步必须走 `release/public-x.y.z` 或等价候选分支。
-- 公开候选必须先推内部 ezone 审核，再推 GitHub、发 GitHub Release、上传 PyPI 或发布 Pages。
+- `master` 是内部开发主干；GitHub `main` 是公开主干。不得直接 `merge master -> main`，公开同步必须走 clean export candidate、GitHub PR 或等价的受审核公开候选流程。
+- GitHub 侧不得存在可写的 `master` 公开分支，也不得把内部 `master` 直接 push 到 GitHub；如果误推到了 `github/master`，第一时间删除远端分支并清理本地跟踪引用，再重新走公开候选流程。
+- 公开候选必须先通过 `make public-preflight` 和 review，再合入 GitHub `main`；npm、PyPI、GitHub Pages 都必须由可信 GitHub workflow 发布，不走本地 publish/upload。
 - 公开发布前必须运行 `make public-preflight`。如果只做发布状态核对，运行 `make public-publish-check`。失败时不得发布。
 - 每次公开 GitHub Release 对应的公开提交都必须打 tag 留痕，优先使用 `make public-release-tag V=x.y.z`。
 - 公开分支长期工作树可以保留，但只能作为公开同步/发布工作区，不做日常内部开发。
 - 不得把 `.pypirc`、私有 registry 凭证、kubeconfig、真实 API Key 或临时 token 放入仓库根目录；正式 PyPI 发布默认使用 Trusted Publishing，只有应急本地发布才允许 PyPI 凭证来自 `~/.pypirc`、环境变量或 CI Secret。
-- 完整公开同步流程见 `docs/release/public-release-workflow.md`；该文档优先于口头约定。
+- 完整公开同步流程见 `docs/public-release-workflow.md`；该文档优先于口头约定。
 
 发布前必须检查：
 

CHANGELOG.md

@@ -5,6 +5,46 @@
 格式参考 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)，
 版本遵循 [Semantic Versioning](https://semver.org/spec/v2.0.0.html)。
 
+## [0.6.9] - 2026-07-07
+
+### 亮点
+
+- **run 状态双维度字段**：新增 `run_mode`（background/foreground/unknown）和 `run_trigger`（new_run/checkpoint_resume/approval_resume/unknown）两个独立维度字段，区分"怎么跑"和"怎么开始"，替代单字段 `run_kind` 的语义错误。后台长任务从 checkpoint 恢复时不再丢失"这是后台任务"的信息，前端可直接消费 `ActiveRunMode` / `ActiveRunTrigger` 判断长任务会话，无需从事件流推断。
+- **checkpoint 可恢复性聚合字段**：`ListSessionCheckpoints` 响应新增 `ResumableTotal` / `HasResumableCheckpoint`，解决 `Total > 0` 不能代表"可恢复"的误判（终态/过期/memory_local checkpoint 会让 Total 非空但不可恢复）。恢复按钮可用性应看 `HasResumableCheckpoint`。
+- **state_delta.active_run 对齐**：ksadk 与 agentengine-server 现都把 `run_mode` / `run_trigger` 写入 `state_delta.active_run`，Session 对象的 `ActiveRunMode` / `ActiveRunTrigger` 由 state 重建，刷新/分享链接/切 session 都能恢复一致状态。
+- **会话事件续订与历史分页收敛**：runtime `ListSessionEvents` / `SubscribeRunEvents` 支持 `AfterSeqId` 增量续订，session backends 支持 `BeforeSeqId` 向前翻页，控制台可从最新窗口进入历史并稳定重连，不再依赖全量扫事件。
+- **真实 token usage 契约补齐**：ADK、LangChain、LangGraph runner 在单轮内累计多次 LLM 调用 usage，同时保留 `last_usage`，让服务端可以同时得到会话累计 token 消耗和最后一轮上下文窗口占用，避免用累计值误当窗口占用。
+
+### 新增
+
+- 新增 `ksadk/conversations/run_kinds.py`：`run_mode` / `run_trigger` 枚举常量 + `validate_run_mode` / `validate_run_trigger` + `trigger_from_resume_input`（从 resume_input 推导 trigger）。
+- `append_run_status_event` 新增 `run_mode` / `run_trigger` 参数，写入事件 `metadata` 与 `state_delta.active_run`。
+- `PreparedConversationTurn` 新增 `run_mode` / `run_trigger` 字段，`build_run_input` 按 checkpoint_resume / approval_resume / new_run 分支回填。
+- `invoke_conversation_once` / `_iter_conversation_turn_events` / `stream_responses_conversation_turn` / `stream_conversation_turn` 透传 `run_mode`；18+ 处 `append_run_status_event` 调用点按 endpoint 语义传值。
+- 各 endpoint 按产品语义标记 run_mode：`RunAgent Background:true` 与 `ResumeRun Stream:true` 标 `background`；普通 `RunAgent Stream:true`、`ResumeRun Stream:false`、`/v1/responses`、`/v1/chat/completions`、`/run_sse` 标 `foreground`。
+- `_DetachedSSEStream` 构造与终态 fallback 写入 `run_mode` / `run_trigger`。
+- 新增 `_latest_session_run_metadata` helper（不改原 `_latest_session_run_status`，保护现有契约），`_session_to_action_payload` 顶层新增 `ActiveRunMode` / `ActiveRunTrigger`。
+- `_list_checkpoints_payload` 新增 `ResumableTotal` / `HasResumableCheckpoint` 聚合字段。规则：`IsResumable===true && ReplayAllowed!==false && IsTerminal!==true && CheckpointStatus not in {expired, disabled}`，不排除 `resumed`（已恢复过的仍计入，符合存档点可反复读）。
+- agentengine-server 侧新建 `app/services/run_kinds.py`（独立维护，不 import ksadk，用测试约束一致性），`_append_run_status` 与 `_serialize_session` 同步写入/读取新字段。
+- 新增 `ksadk/runners/usage_accumulator.py`，统一归一化并累加 OpenAI/ADK/LangChain/LangGraph usage 字段，覆盖 `input_tokens`、`output_tokens`、`total_tokens` 及 token details。
+- runtime `ListSessionEvents` 新增 `AfterSeqId` / `BeforeSeqId` 过滤能力；`SubscribeRunEvents` 支持 `AfterSeqId`，用于断线后只推送已读序号之后的新事件。
+- `SessionService.get_events()` 在 in-memory、local SQLite、Postgres 后端补齐 `after_seq_id` / `before_seq_id` 过滤，保持最新窗口、向后增量、向前翻页三类语义一致。
+
+### 变更
+
+- `run_status` 事件 `metadata` 与 `state_delta.active_run` 扩展为含 `run_mode` / `run_trigger`；旧 session 缺字段降级 `unknown`，不破坏现有 `ActiveInvocationId` / `ActiveRunStatus` 契约。
+- approval 续跑的 `run_mode` 跟随原 run（不写死 foreground），需从原 run 上下文透传。
+- server 侧 `run_status` 事件 `content` 仍为 `{status, detail}`，`run_mode` / `run_trigger` 只写进 `state_delta`，避免破坏现有消费方。
+- runner 返回 `metadata.usage` 继续表示单次响应的累计真实消耗；新增 `metadata.last_usage` 表示最后一次模型调用的 usage，供上层计算 `ContextUsage` 等窗口占用指标。
+- LangChain / LangGraph 的 final chunk metadata 增加 `usage` 与 `last_usage`，保留原响应内容结构，避免只取最后一个 chunk 或最后一次 LLM 调用造成 token 少算。
+
+### 修复
+
+- 修复 ADK runner 单轮内多次 LLM 调用时只保留最后一次 usage，导致会话累计 token 消耗少算的问题。
+- 修复 BaseRunner 从响应列表尾部反向取 usage，遇到多段模型调用时无法聚合的问题。
+- 修复 runtime 事件分页只支持 offset/limit，前端重连和历史向上翻页需要额外扫全量事件的问题。
+- 修复 `SubscribeRunEvents` hosted/runtime 双链路续订语义不一致，断线重连可能重复消费旧事件的问题。
+
 ## [0.6.8] - 2026-07-03
 
 ### 亮点

CONTRIBUTING.md

@@ -17,14 +17,16 @@ Run focused checks before sending a change:
 ```bash
 uv run --extra dev pytest -q
 make open-source-audit
-make public-docs-audit
+make docs-site-build
+make public-audit
 uv build
 uv run --extra dev python -m twine check dist/*
 ```
 
-`public-docs-audit` builds the curated GitHub Pages candidate from
-`public-docs/`. It must not publish `.zread/wiki`, `.zread/site`, internal
-deployment notes, or private generated snapshots.
+`docs-site-build` builds the Fumadocs GitHub Pages candidate from
+`docs-site/`. `public-audit` checks that public repository candidates do not
+publish `.zread/wiki`, `.zread/site`, internal deployment notes, or private
+generated snapshots.
 
 `open-source-audit` checks the current public repository candidate for files
 that should not enter the open-source surface.