Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(storage): preserve deletion and session durability (#3553)

Hao Zhede9c3cec15e8
diff --git a/.github/workflows/api_test.yml b/.github/workflows/api_test.yml
index b85e4648a..aa0a99e13 100644
--- a/.github/workflows/api_test.yml
+++ b/.github/workflows/api_test.yml
@@ -468,7 +468,7 @@ jobs:
--ignore=filesystem/slow/
echo "Running basic tests only (parallel, excluding filesystem and slow tests)..."
uv run python -m pytest . -v -n 4 --html=api-test-report.html --self-contained-html \
- --ignore=retrieval/ --ignore=resources/test_pack.py --ignore=resources/test_wait_processed.py \
+ --ignore=retrieval/ --ignore=resources/test_add_resource.py --ignore=resources/test_pack.py --ignore=resources/test_wait_processed.py \
--ignore=admin/ --ignore=skills/ --ignore=system/test_system_status.py --ignore=system/test_is_healthy.py --ignore=system/test_system_wait.py \
--ignore=scenarios/ --ignore=filesystem/ -k "not test_observer" \
--ignore=common/slow/ --ignore=content/slow/ --ignore=resources/slow/ --ignore=sessions/slow/ \
@@ -491,7 +491,7 @@ jobs:
uv run python -m pytest . -v -n 4 --html=api-test-report.html --self-contained-html --ignore=filesystem/ --ignore=scenarios/resources_retrieval_slow/ --ignore=scenarios/resources_retrieval/ --ignore=common/slow/ --ignore=content/slow/ --ignore=resources/slow/ --ignore=retrieval/slow/ --ignore=sessions/slow/ --ignore=tasks/slow/ --ignore=skills/slow/ --ignore=scenarios/slow/ --ignore=scenarios/stability_error/slow/
} else {
Write-Host "Running basic tests only (no VLM/Embedding, Windows: skipping filesystem and slow tests)"
- uv run python -m pytest . -v -n 4 --html=api-test-report.html --self-contained-html --ignore=retrieval/ --ignore=resources/test_pack.py --ignore=resources/test_wait_processed.py --ignore=admin/ --ignore=skills/ --ignore=system/test_system_status.py --ignore=system/test_is_healthy.py --ignore=system/test_system_wait.py --ignore=filesystem/ --ignore=scenarios/ --ignore=common/slow/ --ignore=content/slow/ --ignore=resources/slow/ --ignore=sessions/slow/ --ignore=tasks/slow/ --ignore=skills/slow/ -k "not test_observer"
+ uv run python -m pytest . -v -n 4 --html=api-test-report.html --self-contained-html --ignore=retrieval/ --ignore=resources/test_add_resource.py --ignore=resources/test_pack.py --ignore=resources/test_wait_processed.py --ignore=admin/ --ignore=skills/ --ignore=system/test_system_status.py --ignore=system/test_is_healthy.py --ignore=system/test_system_wait.py --ignore=filesystem/ --ignore=scenarios/ --ignore=common/slow/ --ignore=content/slow/ --ignore=resources/slow/ --ignore=sessions/slow/ --ignore=tasks/slow/ --ignore=skills/slow/ -k "not test_observer"
}
continue-on-error: true
diff --git a/crates/ragfs/src/cache/wrapper.rs b/crates/ragfs/src/cache/wrapper.rs
index 2df524d6a..300912a3c 100644
--- a/crates/ragfs/src/cache/wrapper.rs
+++ b/crates/ragfs/src/cache/wrapper.rs
@@ -999,11 +999,14 @@ impl FileSystem for CachedFileSystem {
async fn remove_all(&self, path: &str) -> Result<()> {
let _guard = self.operation_lock.write().await;
- self.backend.remove_all(path).await?;
+ let result = self.backend.remove_all(path).await;
+ // Recursive deletion is not transactional: a backend can remove part of
+ // the subtree before reporting an error. Invalidate conservatively so
+ // provider-backed caches cannot continue serving deleted objects.
self.bump_generation(path).await;
self.invalidate_path_objects(path).await;
self.invalidate_parent_directory(path).await;
- Ok(())
+ result
}
async fn read(&self, path: &str, offset: u64, size: u64) -> Result<Vec<u8>> {
diff --git a/crates/ragfs/src/plugins/s3fs/cache.rs b/crates/ragfs/src/plugins/s3fs/cache.rs
index 65e1c9e40..ac3719428 100644
--- a/crates/ragfs/src/plugins/s3fs/cache.rs
+++ b/crates/ragfs/src/plugins/s3fs/cache.rs
@@ -98,10 +98,20 @@ impl<T: Clone> TtlLruCache<T> {
return;
}
+ let normalized_prefix = if prefix == "/" {
+ "/"
+ } else {
+ prefix.trim_end_matches('/')
+ };
+ let child_prefix = if normalized_prefix == "/" {
+ "/".to_string()
+ } else {
+ format!("{normalized_prefix}/")
+ };
let to_remove: Vec<String> = inner
.cache
.iter()
- .filter(|(k, _)| *k == prefix || k.starts_with(&format!("{}/", prefix)))
+ .filter(|(k, _)| *k == normalized_prefix || k.starts_with(&child_prefix))
.map(|(k, _)| k.clone())
.collect();
@@ -297,4 +307,32 @@ mod tests {
cache.put("/test".to_string(), vec![]).await;
assert!(cache.get("/test").await.is_none());
}
+
+ #[tokio::test]
+ async fn test_root_prefix_invalidation_clears_descendants() {
+ let cache = S3ListDirCache::new(10, 60, true);
+ cache.put("/".to_string(), vec![]).await;
+ cache.put("/a".to_string(), vec![]).await;
+ cache.put("/a/b".to_string(), vec![]).await;
+
+ cache.invalidate_prefix("/").await;
+
+ assert!(cache.get("/").await.is_none());
+ assert!(cache.get("/a").await.is_none());
+ assert!(cache.get("/a/b").await.is_none());
+ }
+
+ #[tokio::test]
+ async fn test_prefix_invalidation_normalizes_trailing_slash() {
+ let cache = S3ListDirCache::new(10, 60, true);
+ cache.put("/a".to_string(), vec![]).await;
+ cache.put("/a/b".to_string(), vec![]).await;
+ cache.put("/ab".to_string(), vec![]).await;
+
+ cache.invalidate_prefix("/a/").await;
+
+ assert!(cache.get("/a").await.is_none());
+ assert!(cache.get("/a/b").await.is_none());
+ assert!(cache.get("/ab").await.is_some());
+ }
}
diff --git a/crates/ragfs/src/plugins/s3fs/client.rs b/crates/ragfs/src/plugins/s3fs/client.rs
index e37b8161e..edc1508e9 100644
--- a/crates/ragfs/src/plugins/s3fs/client.rs
+++ b/crates/ragfs/src/plugins/s3fs/client.rs
@@ -18,6 +18,28 @@ use std::time::{Duration, SystemTime, UNIX_EPOCH};
const ENCODED_SEGMENT_PREFIX: char = '!';
const HEX_UPPER: &[u8; 16] = b"0123456789ABCDEF";
+fn partial_delete_error(bucket: &str, errors: &[aws_sdk_s3::types::Error]) -> Option<Error> {
+ if errors.is_empty() {
+ return None;
+ }
+
+ let details = errors
+ .iter()
+ .map(|error| {
+ format!(
+ "key={} code={} message={}",
+ error.key().unwrap_or("<unknown>"),
+ error.code().unwrap_or("<unknown>"),
+ error.message().unwrap_or("<unknown>")
+ )
+ })
+ .collect::<Vec<_>>()
+ .join("; ");
+ Some(Error::internal(format!(
+ "S3 DeleteObjects partial failure: bucket={bucket} errors=[{details}]"
+ )))
+}
+
fn build_s3_error_message(
op: &str,
scope: &str,
@@ -775,7 +797,8 @@ impl S3Client {
.build()
.map_err(|e| format_bucket_s3_error("BuildDelete", &self.bucket, e))?;
- self.client
+ let response = self
+ .client
.delete_objects()
.bucket(&self.bucket)
.delete(delete)
@@ -784,6 +807,9 @@ impl S3Client {
.map_err(|e| {
format_sdk_s3_error("DeleteObjects", &format!("bucket={}", self.bucket), &e)
})?;
+ if let Some(error) = partial_delete_error(&self.bucket, response.errors()) {
+ return Err(error);
+ }
}
}
@@ -1273,6 +1299,19 @@ mod tests {
assert_eq!(test_client("", "").build_key("/a b"), "a b");
}
+ #[test]
+ fn test_partial_delete_error_reports_each_failed_key() {
+ let errors = [aws_sdk_s3::types::Error::builder()
+ .key("denied.txt")
+ .code("AccessDenied")
+ .message("denied")
+ .build()];
+
+ let error = partial_delete_error("bucket", &errors).unwrap();
+ assert!(error.to_string().contains("key=denied.txt"));
+ assert!(error.to_string().contains("code=AccessDenied"));
+ }
+
#[test]
fn test_detect_content_type_for_key_uses_filename_extension() {
assert_eq!(
diff --git a/crates/ragfs/src/plugins/s3fs/mod.rs b/crates/ragfs/src/plugins/s3fs/mod.rs
index d49334965..d059ce15d 100644
--- a/crates/ragfs/src/plugins/s3fs/mod.rs
+++ b/crates/ragfs/src/plugins/s3fs/mod.rs
@@ -48,6 +48,24 @@ fn s3_is_excluded_path(path: &str, exclude_path: &str) -> bool {
.is_some_and(|suffix| suffix.starts_with('/'))
}
+async fn finalize_remove_all(
+ dir_cache: &S3ListDirCache,
+ stat_cache: &S3StatCache,
+ path: &str,
+ result: Result<()>,
+) -> Result<()> {
+ if path == "/" {
+ dir_cache.invalidate_prefix("/").await;
+ stat_cache.invalidate_prefix("/").await;
+ } else {
+ dir_cache.invalidate_parent(path).await;
+ dir_cache.invalidate_prefix(path).await;
+ stat_cache.invalidate_prefix(path).await;
+ }
+
+ result
+}
+
/// Abstract trait for reading chunks from a file during grep.
/// Extracted to allow unit testing chunk-boundary logic with mock providers.
#[async_trait]
@@ -532,24 +550,25 @@ impl FileSystem for S3FileSystem {
if normalized == "/" {
// Delete everything under prefix
- self.client.delete_directory("").await?;
- self.dir_cache.invalidate_prefix("/").await;
- self.stat_cache.invalidate_prefix("/").await;
- return Ok(());
+ let result = self.client.delete_directory("").await;
+ return finalize_remove_all(&self.dir_cache, &self.stat_cache, &normalized, result)
+ .await;
}
- // Delete the file itself (if it exists as a file)
- let key = self.client.build_key(&normalized);
- let _ = self.client.delete_object(&key).await;
-
- // Delete directory and all children
- self.client.delete_directory(&normalized).await?;
+ let result = async {
+ // Delete the file itself (if it exists as a file)
+ let key = self.client.build_key(&normalized);
+ self.client.delete_object(&key).await?;
- self.dir_cache.invalidate_parent(&normalized).await;
- self.dir_cache.invalidate_prefix(&normalized).await;
- self.stat_cache.invalidate_prefix(&normalized).await;
+ // Delete directory and all children
+ self.client.delete_directory(&normalized).await
+ }
+ .await;
- Ok(())
+ // DeleteObjects may succeed for only part of a batch. Always evict the
+ // affected cache scope before returning its error so deleted objects do
+ // not remain visible until cache expiry.
+ finalize_remove_all(&self.dir_cache, &self.stat_cache, &normalized, result).await
}
async fn read(&self, path: &str, offset: u64, size: u64) -> Result<Vec<u8>> {
@@ -1539,6 +1558,50 @@ mod tests {
assert!(plugin.validate(&config).await.is_ok());
}
+ #[tokio::test]
+ async fn test_partial_remove_all_error_invalidates_deleted_prefix_caches() {
+ let dir_cache = S3ListDirCache::new(10, 60, true);
+ let stat_cache = S3StatCache::new(10, 60, true);
+
+ let info = FileInfo {
+ name: "file.txt".to_string(),
+ size: 1,
+ mode: 0o644,
+ mod_time: SystemTime::now(),
+ is_dir: false,
+ };
+ dir_cache
+ .put("/parent".to_string(), vec![info.clone()])
+ .await;
+ dir_cache
+ .put("/parent/child".to_string(), vec![info.clone()])
+ .await;
+ dir_cache
+ .put("/unrelated".to_string(), vec![info.clone()])
+ .await;
+ stat_cache
+ .put("/parent/child/file.txt".to_string(), Some(info.clone()))
+ .await;
+ stat_cache
+ .put("/unrelated/file.txt".to_string(), Some(info))
+ .await;
+
+ let result = finalize_remove_all(
+ &dir_cache,
+ &stat_cache,
+ "/parent/child",
+ Err(Error::internal("S3 DeleteObjects partial failure")),
+ )
+ .await;
+
+ assert!(result.is_err());
+ assert!(dir_cache.get("/parent").await.is_none());
+ assert!(dir_cache.get("/parent/child").await.is_none());
+ assert!(stat_cache.get("/parent/child/file.txt").await.is_none());
+ assert!(dir_cache.get("/unrelated").await.is_some());
+ assert!(stat_cache.get("/unrelated/file.txt").await.is_some());
+ }
+
#[test]
fn test_s3_is_excluded_path() {
assert!(
diff --git a/crates/ragfs/tests/cache_wrapper.rs b/crates/ragfs/tests/cache_wrapper.rs
index d624e59ae..3c4354847 100644
--- a/crates/ragfs/tests/cache_wrapper.rs
+++ b/crates/ragfs/tests/cache_wrapper.rs
@@ -6,7 +6,7 @@ use ragfs::cache::{
};
use ragfs::core::{FsContextInner, GrepResult, MultiWriteWrappedFS, TreeEntry, FS_CTX};
use ragfs::plugins::MemFileSystem;
-use ragfs::{FileInfo, FileSystem, Result, WriteFlag};
+use ragfs::{Error, FileInfo, FileSystem, Result, WriteFlag};
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::{Arc, Mutex};
use std::time::Duration;
@@ -20,6 +20,7 @@ struct CountingFileSystem {
greps: Arc<AtomicU64>,
trees: Arc<AtomicU64>,
read_delay: Duration,
+ partial_remove_path: Option<String>,
}
struct DeleteFailingProvider {
@@ -211,6 +212,7 @@ impl CountingFileSystem {
greps: Arc::new(AtomicU64::new(0)),
trees: Arc::new(AtomicU64::new(0)),
read_delay: Duration::ZERO,
+ partial_remove_path: None,
}
}
@@ -219,6 +221,11 @@ impl CountingFileSystem {
self
}
+ fn with_partial_remove_failure(mut self, path: &str) -> Self {
+ self.partial_remove_path = Some(path.to_string());
+ self
+ }
+
fn read_count(&self) -> u64 {
self.reads.load(Ordering::Relaxed)
}
@@ -255,6 +262,12 @@ impl FileSystem for CountingFileSystem {
}
async fn remove_all(&self, path: &str) -> Result<()> {
+ if let Some(partial_remove_path) = &self.partial_remove_path {
+ self.inner.remove(partial_remove_path).await?;
+ return Err(Error::internal(format!(
+ "remove_all partially removed {partial_remove_path} under {path}"
+ )));
+ }
self.inner.remove_all(path).await
}
@@ -1191,6 +1204,52 @@ async fn remove_all_generation_rejects_residual_descendant_cache_entries() {
assert_eq!(probe.read_count(), 2);
}
+#[tokio::test]
+async fn remove_all_error_invalidates_cached_state_after_partial_mutation() {
+ let backend = CountingFileSystem::new().with_partial_remove_failure("/tree/deleted.txt");
+ backend.mkdir("/tree", 0o755).await.unwrap();
+ backend
+ .write("/tree/deleted.txt", b"deleted", 0, WriteFlag::Create)
+ .await
+ .unwrap();
+ backend
+ .write("/tree/survivor.txt", b"survivor", 0, WriteFlag::Create)
+ .await
+ .unwrap();
+ backend
+ .write("/unrelated.txt", b"unrelated", 0, WriteFlag::Create)
+ .await
+ .unwrap();
+ let probe = backend.clone();
+ let (fs, _) = cached_fs(backend);
+
+ assert_eq!(
+ fs.read("/tree/deleted.txt", 0, 0).await.unwrap(),
+ b"deleted"
+ );
+ assert_eq!(
+ fs.read("/tree/survivor.txt", 0, 0).await.unwrap(),
+ b"survivor"
+ );
+ assert_eq!(fs.read("/unrelated.txt", 0, 0).await.unwrap(), b"unrelated");
+ assert_eq!(fs.read_dir("/tree").await.unwrap().len(), 2);
+
+ let error = fs.remove_all("/tree").await.unwrap_err();
+ assert!(error.to_string().contains("partially removed"));
+
+ assert!(fs.read("/tree/deleted.txt", 0, 0).await.is_err());
+ assert_eq!(
+ fs.read("/tree/survivor.txt", 0, 0).await.unwrap(),
+ b"survivor"
+ );
+ assert_eq!(fs.read("/unrelated.txt", 0, 0).await.unwrap(), b"unrelated");
+ let entries = fs.read_dir("/tree").await.unwrap();
+ assert_eq!(entries.len(), 1);
+ assert_eq!(entries[0].name, "survivor.txt");
+ assert_eq!(probe.read_count(), 5);
+ assert_eq!(probe.read_dir_count(), 2);
+}
+
#[tokio::test]
async fn shared_provider_generation_bump_invalidates_other_wrappers() {
let backend = CountingFileSystem::new();
diff --git a/docs/en/about/02-changelog.md b/docs/en/about/02-changelog.md
index c205f8561..e6b67bd62 100644
--- a/docs/en/about/02-changelog.md
+++ b/docs/en/about/02-changelog.md
@@ -3,6 +3,18 @@
All notable changes to OpenViking will be documented in this file.
This changelog is automatically generated from [GitHub Releases](https://github.com/volcengine/OpenViking/releases).
+## Unreleased
+
+- **Session policy compatibility**: String `"false"` memory-policy switches now disable
+ extraction correctly. Existing boolean-like values remain temporarily compatible and
+ emit deprecation warnings; use JSON booleans for new configurations.
+- **External peer identity migration**: Mixed-script log-ingestion identities now use
+ lossless `ext-<base64>` ids. The `ext-` namespace is reserved, so ASCII identities that
+ would otherwise enter it are encoded as well. Older lossy peer directories are not read
+ automatically because multiple identities may have collided with each other or with a
+ real ASCII peer; migrating that ambiguous history requires an operator-controlled
+ ownership decision.
+
## v0.4.9 (2026-07-10)
### Highlights
diff --git a/docs/en/agent-integrations/09-log-ingestion.md b/docs/en/agent-integrations/09-log-ingestion.md
index e6c81f8c1..d5905f450 100644
--- a/docs/en/agent-integrations/09-log-ingestion.md
+++ b/docs/en/agent-integrations/09-log-ingestion.md
@@ -94,7 +94,14 @@ Every message carries a peer_id so OpenViking can profile both the human and the
- assistant turns: `{harness}/{model}` (or `{harness}/{provider}/{model}` when the provider is meaningful), e.g. `claude_code/claude-opus-4-8`, `opencode/bytedance_ark/doubao-...`;
- user turns: single-user dev harnesses (claude_code / codex / opencode) use the git identity of the session cwd repo (`user.email` / `user.name`), falling back to the configured `ingest.user` when there is no git repo; group-chat harnesses (hermes / openclaw) use the original username from the log (selected by `user_field`).
-Non-ASCII identifiers (e.g. a CJK username) fall back to a valid `ext-<base64>` form.
+Identifiers containing any non-ASCII characters (for example, a CJK or mixed-script
+username) use a collision-free `ext-<base64>` form that encodes the complete identifier.
+The `ext-` namespace is reserved: an ASCII identity that would sanitize to an `ext-` id is
+also encoded so it cannot impersonate an encoded identity. New reads and writes use only
+the canonical id. Older versions may have collapsed multiple mixed-script identities—or
+a mixed-script identity and a real ASCII identity—into the same peer directory. OpenViking
+therefore does not attach those ambiguous directories as automatic aliases; operators must
+decide ownership before migrating existing data.
## How it works
diff --git a/docs/en/api/05-sessions.md b/docs/en/api/05-sessions.md
index 57866c08f..a2f28878f 100644
--- a/docs/en/api/05-sessions.md
+++ b/docs/en/api/05-sessions.md
@@ -42,7 +42,7 @@ Create a new session. Sessions are containers for conversations, storing message
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| session_id | str | No | None | Session ID. Creates new session with auto-generated ID if None |
-| memory_policy | object | No | None | Default memory extraction policy for the session. Optional `self` and `peer` switches control write targets, optional `working_memory.enabled=false` skips archive summaries, and optional top-level `memory_types` limits extraction to specific enabled memory schemas. When `memory_types` is omitted or `null`, all enabled memory schemas are allowed. Invalid shapes or unknown memory types are rejected with `InvalidArgumentError`. |
+| memory_policy | object | No | None | Default memory extraction policy for the session. Optional `self` and `peer` switches control write targets, optional `working_memory.enabled=false` skips archive summaries, and optional top-level `memory_types` limits extraction to specific enabled memory schemas. Use JSON booleans for every `enabled` value. Legacy boolean-like values remain accepted temporarily (including string `"false"`, which is parsed as false) but emit a deprecation warning. When `memory_types` is omitted or `null`, all enabled memory schemas are allowed. Invalid shapes or unknown memory types are rejected with `InvalidArgumentError`. |
#### 3. Usage Examples
diff --git a/docs/zh/about/02-changelog.md b/docs/zh/about/02-changelog.md
index 88e86e538..54654a6ef 100644
--- a/docs/zh/about/02-changelog.md
+++ b/docs/zh/about/02-changelog.md
@@ -3,6 +3,15 @@
OpenViking 的所有重要变更都将记录在此文件中。
此更新日志从 [GitHub Releases](https://github.com/volcengine/OpenViking/releases) 自动生成。
+## 未发布
+
+- **Session policy 兼容性**:字符串 `"false"` 现在会正确关闭对应的记忆抽取开关。
+ 现有 boolean-like 值暂时保持兼容并产生弃用警告;新配置应使用 JSON 布尔值。
+- **外部 peer identity 迁移**:日志导入中的混合文字标识改用无损的
+ `ext-<base64>` id。`ext-` 命名空间为编码身份保留,因此原本会进入该命名空间的
+ ASCII 身份也会被编码。系统不会自动读取旧的有损 peer 目录,因为多个身份可能彼此冲突,
+ 也可能与真实 ASCII peer 冲突;迁移这些归属不明确的历史数据需要运维人员明确确认归属。
+
## v0.4.9 (2026-07-10)
### 重点更新
diff --git a/docs/zh/agent-integrations/09-log-ingestion.md b/docs/zh/agent-integrations/09-log-ingestion.md
index 135b8d9a3..c90271ecf 100644
--- a/docs/zh/agent-integrations/09-log-ingestion.md
+++ b/docs/zh/agent-integrations/09-log-ingestion.md
@@ -94,7 +94,12 @@ openviking-server ingest status
- assistant 消息:`{harness}/{模型名}`(provider 有意义时为 `{harness}/{provider}/{模型名}`),例如 `claude_code/claude-opus-4-8`、`opencode/bytedance_ark/doubao-...`;
- user 消息:单用户开发型 harness(claude_code / codex / opencode)取会话 cwd 所在仓库的 git 身份(`user.email` / `user.name`),无 git 仓库时回退为配置的 `ingest.user`;群聊 harness(hermes / openclaw)取日志里的原始用户名(由 `user_field` 指定)。
-非 ASCII 标识(如中文用户名)会回退为合法的 `ext-<base64>` 形式。
+任何包含非 ASCII 字符的标识(例如中文或混合文字用户名)都会将完整标识编码为无碰撞的
+`ext-<base64>` 形式。`ext-` 命名空间为编码身份保留;如果 ASCII 身份清理后会成为
+`ext-` id,系统也会对其编码,避免它冒充已有编码身份。新的读取和写入只使用规范 id。
+旧版本可能把多个混合文字身份,或一个混合文字身份与真实 ASCII 身份,折叠到同一个 peer
+目录中。OpenViking 不会把这些归属不明确的目录自动附加为别名;迁移既有数据前,
+运维人员必须先确认其真实归属。
## 工作原理
diff --git a/docs/zh/api/05-sessions.md b/docs/zh/api/05-sessions.md
index ac0006937..2c4c94572 100644
--- a/docs/zh/api/05-sessions.md
+++ b/docs/zh/api/05-sessions.md
@@ -42,7 +42,7 @@ Session API 按认证用户作用域访问会话,并返回 canonical user sess
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| session_id | str | 否 | None | 会话 ID。如果为 None,则创建一个自动生成 ID 的新会话 |
-| memory_policy | object | 否 | None | 会话默认的记忆抽取策略。可选的 `self` 和 `peer` 开关控制写入目标;可选的 `working_memory.enabled=false` 跳过 archive summary;可选的顶层 `memory_types` 将抽取限制为指定的 enabled memory schema。未传或为 `null` 时允许所有 enabled memory schema。非法结构或未知 memory type 会以 `InvalidArgumentError` 拒绝。 |
+| memory_policy | object | 否 | None | 会话默认的记忆抽取策略。可选的 `self` 和 `peer` 开关控制写入目标;可选的 `working_memory.enabled=false` 跳过 archive summary;可选的顶层 `memory_types` 将抽取限制为指定的 enabled memory schema。所有 `enabled` 值都应使用 JSON 布尔值。旧版 boolean-like 值暂时仍兼容(字符串 `"false"` 会正确解析为 false),但会产生弃用警告。未传或为 `null` 时允许所有 enabled memory schema。非法结构或未知 memory type 会以 `InvalidArgumentError` 拒绝。 |
#### 3. 使用示例
diff --git a/openviking/ingest/peer.py b/openviking/ingest/peer.py
index 00b531782..59df2d5b4 100644
--- a/openviking/ingest/peer.py
+++ b/openviking/ingest/peer.py
@@ -8,9 +8,9 @@
session cwd repo, falling back to the configured OV user;
* group-chat harnesses (hermes/openclaw) -> the original username from the log.
-peer_id must match OpenViking's identifier rules (``[a-zA-Z0-9_.@-]+``). ASCII values
-stay human-readable; anything else (e.g. CJK usernames) is base64-encoded as ``ext-…``,
-mirroring vikingbot's external-peer convention.
+peer_id must match OpenViking's identifier rules (``[a-zA-Z0-9_.@-]+``). Safe ASCII
+values stay human-readable except for the reserved ``ext-`` namespace; non-ASCII and
+reserved-prefix values are base64-encoded as ``ext-…``.
"""
from __future__ import annotations
@@ -36,21 +36,32 @@ def _sanitize_component(value: str) -> str:
return cleaned
+def _encoded_external_peer(value: str) -> Optional[str]:
+ encoded = base64.urlsafe_b64encode(value.encode("utf-8")).decode("ascii").rstrip("=")
+ return safe_peer_id(f"ext-{encoded}")
+
+
def safe_external_peer(raw: Optional[str]) -> Optional[str]:
- """Return a valid peer_id for an arbitrary external identifier (readable if ASCII)."""
+ """Return a valid peer_id while keeping encoded and readable IDs disjoint."""
if not raw:
return None
text = str(raw).strip()
if not text:
return None
+ if not text.isascii():
+ return _encoded_external_peer(text)
sanitized = _sanitize_component(text)
if sanitized:
+ # ``ext-`` is the namespace for encoded external identities. Escape
+ # readable inputs that would enter it so they cannot impersonate the
+ # non-ASCII identity whose base64 payload they happen to contain.
+ if sanitized.startswith("ext-"):
+ return _encoded_external_peer(text)
pid = safe_peer_id(sanitized)
if pid:
return pid
- # Non-ASCII / unsanitizable -> stable, valid, unique fallback.
- encoded = base64.urlsafe_b64encode(text.encode("utf-8")).decode("ascii").rstrip("=")
- return safe_peer_id(f"ext-{encoded}")
+ # Unsanitizable ASCII -> stable, valid, unique fallback.
+ return _encoded_external_peer(text)
def assistant_peer_id(
diff --git a/openviking/session/memory/utils/streaming_batcher.py b/openviking/session/memory/utils/streaming_batcher.py
index 272426708..d6644cf15 100644
--- a/openviking/session/memory/utils/streaming_batcher.py
+++ b/openviking/session/memory/utils/streaming_batcher.py
@@ -176,11 +176,25 @@ class StreamingBatcher(Generic[T, R]):
async def _run_timer_loop(self) -> None:
while True:
+ flush_task: asyncio.Task[R | None] | None = None
try:
await asyncio.sleep(self.config.timer_check_interval_seconds)
if await self._should_flush_by_time_or_count():
- await self.flush("time")
+ flush_task = asyncio.create_task(
+ self.flush("time"),
+ name=f"{self.name}-flush-time",
+ )
+ await asyncio.shield(flush_task)
except asyncio.CancelledError:
+ if flush_task is not None:
+ try:
+ await flush_task
+ except Exception as exc:
+ logger.warning(
+ "[%s] timer flush failed while stopping: %s",
+ self.name,
+ exc,
+ )
raise
except Exception as exc:
logger.warning("[%s] timer flush iteration failed: %s", self.name, exc)
diff --git a/openviking/session/memory_policy.py b/openviking/session/memory_policy.py
index 03629d334..f5c2bf3e6 100644
--- a/openviking/session/memory_policy.py
+++ b/openviking/session/memory_policy.py
@@ -4,6 +4,7 @@
from __future__ import annotations
+import warnings
from dataclasses import dataclass
from typing import Any, Optional
@@ -11,6 +12,8 @@ from openviking_cli.exceptions import InvalidArgumentError
_POLICY_KEYS = {"self", "peer", "memory_types", "working_memory"}
_TARGET_KEYS = {"enabled"}
+_TRUE_STRINGS = {"1", "true", "yes", "on"}
+_FALSE_STRINGS = {"", "0", "false", "no", "off"}
def _memory_policy_shape_error(key: str) -> str:
@@ -25,6 +28,28 @@ def _memory_policy_keys_error(key: str) -> str:
return "memory_policy target supports only: enabled"
+def _parse_enabled(value: Any, *, key: str) -> bool:
+ if isinstance(value, bool):
+ return value
+
+ warnings.warn(
+ f"memory_policy.{key}.enabled should be a boolean; legacy coercion is deprecated",
+ FutureWarning,
+ stacklevel=3,
+ )
+ if isinstance(value, str):
+ normalized = value.strip().casefold()
+ if normalized in _TRUE_STRINGS:
+ return True
+ if normalized in _FALSE_STRINGS:
+ return False
+
+ # Preserve the permissive pre-v0.5 behavior for uncommon legacy values.
+ # This avoids breaking persisted policy dictionaries while callers migrate
+ # to genuine JSON booleans.
+ return bool(value)
+
+
def _target_enabled(data: Any, *, default_enabled: bool, key: str = "target") -> bool:
if data is None:
return default_enabled
@@ -33,7 +58,9 @@ def _target_enabled(data: Any, *, default_enabled: bool, key: str = "target") ->
extra_keys = set(data) - _TARGET_KEYS
if extra_keys:
raise InvalidArgumentError(_memory_policy_keys_error(key))
- return bool(data.get("enabled", default_enabled))
+ if "enabled" not in data:
+ return default_enabled
+ return _parse_enabled(data["enabled"], key=key)
def _parse_memory_types(data: Any) -> Optional[set[str]]:
diff --git a/tests/ingest/fixtures/peer_id_compat.json b/tests/ingest/fixtures/peer_id_compat.json
new file mode 100644
index 000000000..e9db37abc
--- /dev/null
+++ b/tests/ingest/fixtures/peer_id_compat.json
@@ -0,0 +1,26 @@
+[
+ {
+ "raw": "alice",
+ "canonical": "alice"
+ },
+ {
+ "raw": "张三 Alice",
+ "canonical": "ext-5byg5LiJIEFsaWNl"
+ },
+ {
+ "raw": "李四 Alice",
+ "canonical": "ext-5p2O5ZubIEFsaWNl"
+ },
+ {
+ "raw": "José",
+ "canonical": "ext-Sm9zw6k"
+ },
+ {
+ "raw": "杨冠姝",
+ "canonical": "ext-5p2o5Yag5aed"
+ },
+ {
+ "raw": "ext-5byg5LiJIEFsaWNl",
+ "canonical": "ext-ZXh0LTVieWc1TGlKSUVGc2FXTmw"
+ }
+]
diff --git a/tests/ingest/test_peer.py b/tests/ingest/test_peer.py
index ab06db8e6..c8b61f819 100644
--- a/tests/ingest/test_peer.py
+++ b/tests/ingest/test_peer.py
@@ -2,6 +2,9 @@
# SPDX-License-Identifier: AGPL-3.0
"""peer_id resolution: assistant model peers, human/git peers, group usernames."""
+import json
+from pathlib import Path
+
from openviking.ingest.peer import (
assistant_peer_id,
resolve_git_human_peer,
@@ -27,6 +30,38 @@ def test_external_peer_non_ascii_falls_back_to_ext():
assert pid is not None and pid.startswith("ext-")
+def test_external_peer_mixed_unicode_encodes_full_value_without_collisions():
+ first = safe_external_peer("张三 Alice")
+ second = safe_external_peer("李四 Alice")
+
+ assert first != second
+ assert first is not None and first.startswith("ext-")
+ assert second is not None and second.startswith("ext-")
+
+
+def test_external_peer_encoded_namespace_cannot_be_impersonated_by_ascii_name():
+ mixed_script = safe_external_peer("张三 Alice")
+ ascii_lookalike = safe_external_peer("ext-5byg5LiJIEFsaWNl")
+ sanitized_lookalike = safe_external_peer("ext 5byg5LiJIEFsaWNl")
+
+ assert mixed_script == "ext-5byg5LiJIEFsaWNl"
+ assert ascii_lookalike == "ext-ZXh0LTVieWc1TGlKSUVGc2FXTmw"
+ assert sanitized_lookalike == "ext-ZXh0IDVieWc1TGlKSUVGc2FXTmw"
+ assert len({mixed_script, ascii_lookalike, sanitized_lookalike}) == 3
+
+
+def test_external_peer_compatibility_fixture():
+ fixture_path = Path(__file__).parent / "fixtures" / "peer_id_compat.json"
+ cases = json.loads(fixture_path.read_text(encoding="utf-8"))
+
+ for case in cases:
+ canonical = safe_external_peer(case["raw"])
+ assert canonical == case["canonical"]
+
+ canonical_ids = [safe_external_peer(case["raw"]) for case in cases]
+ assert len(canonical_ids) == len(set(canonical_ids))
+
+
def test_git_human_peer_falls_back_without_repo(tmp_path):
# tmp_path is not a git repo -> configured fallback is used
assert resolve_git_human_peer(str(tmp_path), "me") == "me"
diff --git a/tests/retrieve/test_type_quota_recall.py b/tests/retrieve/test_type_quota_recall.py
index bbc94d032..ebc19207e 100644
--- a/tests/retrieve/test_type_quota_recall.py
+++ b/tests/retrieve/test_type_quota_recall.py
@@ -4,7 +4,7 @@
import asyncio
from types import SimpleNamespace
-from openviking.retrieve.type_quota_recall import search_type_quota_recall
+from openviking.retrieve.type_quota_recall import memory_target_roots, search_type_quota_recall
from openviking.server.identity import RequestContext, Role
from openviking_cli.session.user_id import UserIdentifier
@@ -14,6 +14,19 @@ class _FakeFindResult:
self.memories = memories or []
+def test_memory_target_roots_keep_encoded_peer_isolated_from_legacy_collision():
+ ctx = RequestContext(
+ user=UserIdentifier.the_default_user("test_user"),
+ role=Role.USER,
+ actor_peer_id="ext-5byg5LiJIEFsaWNl",
+ )
+
+ assert memory_target_roots(ctx) == [
+ "viking://user/test_user/memories",
+ "viking://user/test_user/peers/ext-5byg5LiJIEFsaWNl/memories",
+ ]
+
+
async def test_independent_type_searches_start_concurrently():
started_targets: list[str] = []
all_started = asyncio.Event()
diff --git a/tests/server/test_actor_peer_retrieval_targets.py b/tests/server/test_actor_peer_retrieval_targets.py
index 66b141f1b..6f4d52368 100644
--- a/tests/server/test_actor_peer_retrieval_targets.py
+++ b/tests/server/test_actor_peer_retrieval_targets.py
@@ -86,6 +86,20 @@ def test_actor_default_memory_targets_actor_peer_memory():
]
+def test_encoded_actor_cannot_read_colliding_ascii_peer():
+ encoded_peer = "ext-5byg5LiJIEFsaWNl"
+
+ assert default_target_directories(_ctx(encoded_peer), context_type=ContextType.MEMORY) == [
+ "viking://user/support_bot/memories",
+ f"viking://user/support_bot/peers/{encoded_peer}/memories",
+ ]
+ with pytest.raises(PermissionDeniedError, match="another peer"):
+ _target_dirs(
+ "viking://user/support_bot/peers/Alice/memories",
+ actor_peer_id=encoded_peer,
+ )
+
+
def test_actor_skill_defaults_include_user_and_shared_agent_skills():
assert default_target_directories(
_ctx("web-visitor-alice"), context_type=ContextType.SKILL
diff --git a/tests/session/memory/test_memory_isolation_handler.py b/tests/session/memory/test_memory_isolation_handler.py
index eacf39000..21ccdc3aa 100644
--- a/tests/session/memory/test_memory_isolation_handler.py
+++ b/tests/session/memory/test_memory_isolation_handler.py
@@ -151,6 +151,29 @@ class TestGetReadScope:
assert "viking://user/support_bot/peers/__self/memories" not in dirs
assert "viking://user/support_bot/peers/web-visitor-alice/memories" in dirs
+ def test_render_schema_directories_keep_encoded_peer_isolated(self):
+ from openviking.session.memory.dataclass import MemoryTypeSchema
+
+ ctx = create_ctx(user_id="support_bot")
+ extract_ctx = create_mock_extract_context(
+ [create_message("user", peer_id="ext-5byg5LiJIEFsaWNl")]
+ )
+ handler = MemoryIsolationHandler(
+ ctx,
+ extract_ctx,
+ allow_self=False,
+ allowed_peer_ids={"ext-5byg5LiJIEFsaWNl"},
+ )
+ schema = MemoryTypeSchema(
+ memory_type="preferences",
+ filename_template="preferences.md",
+ directory="viking://user/{{ user_space }}/memories",
+ )
+
+ assert handler.render_schema_directories(schema) == [
+ "viking://user/support_bot/peers/ext-5byg5LiJIEFsaWNl/memories",
+ ]
+
def test_render_schema_directories_peer_enabled_false_uses_self_only(self):
from openviking.session.memory.dataclass import MemoryTypeSchema
diff --git a/tests/unit/session/fixtures/memory_policy_compat.json b/tests/unit/session/fixtures/memory_policy_compat.json
new file mode 100644
index 000000000..ec4ccaf0e
--- /dev/null
+++ b/tests/unit/session/fixtures/memory_policy_compat.json
@@ -0,0 +1,47 @@
+[
+ {
+ "value": false,
+ "expected": false,
+ "deprecated": false
+ },
+ {
+ "value": true,
+ "expected": true,
+ "deprecated": false
+ },
+ {
+ "value": "false",
+ "expected": false,
+ "deprecated": true
+ },
+ {
+ "value": "OFF",
+ "expected": false,
+ "deprecated": true
+ },
+ {
+ "value": "true",
+ "expected": true,
+ "deprecated": true
+ },
+ {
+ "value": 0,
+ "expected": false,
+ "deprecated": true
+ },
+ {
+ "value": 1,
+ "expected": true,
+ "deprecated": true
+ },
+ {
+ "value": null,
+ "expected": false,
+ "deprecated": true
+ },
+ {
+ "value": "legacy-nonempty",
+ "expected": true,
+ "deprecated": true
+ }
+]
diff --git a/tests/unit/session/test_memory_policy.py b/tests/unit/session/test_memory_policy.py
index dbf8c9839..f1116b450 100644
--- a/tests/unit/session/test_memory_policy.py
+++ b/tests/unit/session/test_memory_policy.py
@@ -1,6 +1,10 @@
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
+import json
+import warnings
+from pathlib import Path
+
import pytest
from openviking.session.memory.dataclass import MemoryField, MemoryTypeSchema
@@ -66,6 +70,25 @@ def test_memory_policy_rejects_invalid_working_memory_shape():
MemoryPolicy.from_dict({"working_memory": {"enabled": True, "mode": "summary"}})
+def test_memory_policy_legacy_enabled_compatibility_fixture():
+ fixture_path = Path(__file__).parent / "fixtures" / "memory_policy_compat.json"
+ cases = json.loads(fixture_path.read_text(encoding="utf-8"))
+
+ for case in cases:
+ with warnings.catch_warnings(record=True) as caught:
+ warnings.simplefilter("always")
+ policy = MemoryPolicy.from_dict({"peer": {"enabled": case["value"]}})
+
+ assert policy.peer_enabled is case["expected"]
+ deprecations = [item for item in caught if item.category is FutureWarning]
+ assert bool(deprecations) is case["deprecated"]
+
+
+def test_memory_policy_legacy_enabled_warning_is_user_visible():
+ with pytest.warns(FutureWarning, match="legacy coercion is deprecated"):
+ MemoryPolicy.from_dict({"peer": {"enabled": "false"}})
+
+
def test_memory_policy_rejects_invalid_memory_types():
policy = MemoryPolicy.from_dict({"memory_types": ["profile", "missing"]})
diff --git a/tests/unit/test_streaming_batcher.py b/tests/unit/test_streaming_batcher.py
new file mode 100644
index 000000000..fa5306fa7
--- /dev/null
+++ b/tests/unit/test_streaming_batcher.py
@@ -0,0 +1,84 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+import asyncio
+
+import pytest
+
+from openviking.session.memory.utils.streaming_batcher import (
+ StreamingBatcher,
+ StreamingBatcherConfig,
+)
+
+
+async def test_close_waits_for_in_flight_timer_flush():
+ started = asyncio.Event()
+ finish = asyncio.Event()
+
+ async def process_batch(items: list[str], _reason: str) -> str:
+ started.set()
+ await finish.wait()
+ return ",".join(items)
+
+ batcher = StreamingBatcher(
+ name="test",
+ process_batch=process_batch,
+ config=StreamingBatcherConfig(
+ max_items_per_batch=10,
+ max_wait_seconds=0.01,
+ timer_check_interval_seconds=0.001,
+ ),
+ )
+ submit = asyncio.create_task(batcher.submit("item"))
+ await asyncio.wait_for(started.wait(), timeout=1)
+
+ close = asyncio.create_task(batcher.close())
+ await asyncio.sleep(0)
+ finish.set()
+
+ assert await asyncio.wait_for(submit, timeout=1) == "item"
+ assert await asyncio.wait_for(close, timeout=1) is None
+
+
+async def test_close_drains_failing_timer_flush_without_unhandled_task():
+ started = asyncio.Event()
+ finish = asyncio.Event()
+ unhandled: list[dict[str, object]] = []
+ loop = asyncio.get_running_loop()
+ previous_handler = loop.get_exception_handler()
+
+ async def process_batch(_items: list[str], _reason: str) -> str:
+ started.set()
+ await finish.wait()
+ raise RuntimeError("boom")
+
+ batcher = StreamingBatcher(
+ name="failing-test",
+ process_batch=process_batch,
+ config=StreamingBatcherConfig(
+ max_items_per_batch=10,
+ max_wait_seconds=0.01,
+ timer_check_interval_seconds=0.001,
+ ),
+ )
+ loop.set_exception_handler(lambda _loop, context: unhandled.append(context))
+ try:
+ submit = asyncio.create_task(batcher.submit("item"))
+ await asyncio.wait_for(started.wait(), timeout=1)
+
+ close = asyncio.create_task(batcher.close())
+ await asyncio.sleep(0)
+ finish.set()
+
+ with pytest.raises(RuntimeError, match="boom"):
+ await asyncio.wait_for(submit, timeout=1)
+ assert await asyncio.wait_for(close, timeout=1) is None
+ await asyncio.sleep(0)
+
+ assert submit.done()
+ assert close.done()
+ assert unhandled == []
+ finally:
+ loop.set_exception_handler(previous_handler)