Skip to content

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

feat(tasks): add async task tracking API for background operations (#476)

dr3243636-opscd4bf4436857
diff --git a/openviking/server/app.py b/openviking/server/app.py
index 0867d1751..c22794e14 100644
--- a/openviking/server/app.py
+++ b/openviking/server/app.py
@@ -27,8 +27,10 @@ from openviking.server.routers import (
search_router,
sessions_router,
system_router,
+ tasks_router,
)
from openviking.service.core import OpenVikingService
+from openviking.service.task_tracker import get_task_tracker
from openviking_cli.exceptions import OpenVikingError
from openviking_cli.utils import get_logger
@@ -83,9 +85,14 @@ def create_app(
config.host,
)
+ # Start TaskTracker cleanup loop
+ task_tracker = get_task_tracker()
+ task_tracker.start_cleanup_loop()
+
yield
# Cleanup
+ task_tracker.stop_cleanup_loop()
if service:
await service.close()
logger.info("OpenVikingService closed")
@@ -169,6 +176,7 @@ def create_app(
app.include_router(pack_router)
app.include_router(debug_router)
app.include_router(observer_router)
+ app.include_router(tasks_router)
app.include_router(bot_router, prefix="/bot/v1")
return app
diff --git a/openviking/server/routers/__init__.py b/openviking/server/routers/__init__.py
index 05a75f97c..12aa9f344 100644
--- a/openviking/server/routers/__init__.py
+++ b/openviking/server/routers/__init__.py
@@ -14,6 +14,7 @@ from openviking.server.routers.resources import router as resources_router
from openviking.server.routers.search import router as search_router
from openviking.server.routers.sessions import router as sessions_router
from openviking.server.routers.system import router as system_router
+from openviking.server.routers.tasks import router as tasks_router
__all__ = [
"admin_router",
@@ -28,4 +29,5 @@ __all__ = [
"pack_router",
"debug_router",
"observer_router",
+ "tasks_router",
]
diff --git a/openviking/server/routers/sessions.py b/openviking/server/routers/sessions.py
index 1dab60752..871932e57 100644
--- a/openviking/server/routers/sessions.py
+++ b/openviking/server/routers/sessions.py
@@ -13,7 +13,8 @@ from openviking.message.part import TextPart, part_from_dict
from openviking.server.auth import get_request_context
from openviking.server.dependencies import get_service
from openviking.server.identity import RequestContext
-from openviking.server.models import Response
+from openviking.server.models import ErrorInfo, Response
+from openviking.service.task_tracker import get_task_tracker
router = APIRouter(prefix="/api/v1/sessions", tags=["sessions"])
logger = logging.getLogger(__name__)
@@ -152,38 +153,77 @@ async def commit_session(
):
"""Commit a session (archive and extract memories).
- When wait=False, the commit is processed in the background.
- This is useful for avoiding blocking when the commit involves
- LLM calls for memory extraction.
+ When wait=False, the commit is processed in the background and a
+ ``task_id`` is returned. Use ``GET /tasks/{task_id}`` to poll for
+ completion status, results, or errors.
+
+ When wait=True (default), the commit blocks until complete and
+ returns the full result inline.
"""
service = get_service()
+ tracker = get_task_tracker()
+
if wait:
+ # Reject if same session already has a background commit running
+ if tracker.has_running("session_commit", session_id):
+ return Response(
+ status="error",
+ error=ErrorInfo(
+ code="CONFLICT",
+ message=f"Session {session_id} already has a commit in progress",
+ ),
+ )
result = await service.sessions.commit_async(session_id, _ctx)
return Response(status="ok", result=result)
- asyncio.create_task(_background_commit(service, session_id, _ctx))
+ # Atomically check + create to prevent race conditions
+ task = tracker.create_if_no_running("session_commit", session_id)
+ if task is None:
+ return Response(
+ status="error",
+ error=ErrorInfo(
+ code="CONFLICT",
+ message=f"Session {session_id} already has a commit in progress",
+ ),
+ )
+ asyncio.create_task(_background_commit_tracked(service, session_id, _ctx, task.task_id))
+
return Response(
status="ok",
result={
"session_id": session_id,
"status": "accepted",
+ "task_id": task.task_id,
"message": "Commit is processing in the background",
},
)
-async def _background_commit(service, session_id: str, ctx: RequestContext) -> None:
- """Run session commit in background."""
+async def _background_commit_tracked(
+ service, session_id: str, ctx: RequestContext, task_id: str
+) -> None:
+ """Run session commit in background with task tracking."""
+ tracker = get_task_tracker()
+ tracker.start(task_id)
try:
result = await service.sessions.commit_async(session_id, ctx)
- memories = result.get("memories_extracted", 0)
+ tracker.complete(
+ task_id,
+ {
+ "session_id": session_id,
+ "memories_extracted": result.get("memories_extracted", 0),
+ "archived": result.get("archived", False),
+ },
+ )
logger.info(
- "Background commit completed: session=%s, memories=%d",
+ "Background commit completed: session=%s task=%s memories=%d",
session_id,
- memories,
+ task_id,
+ result.get("memories_extracted", 0),
)
- except Exception:
- logger.exception("Background commit failed: session=%s", session_id)
+ except Exception as exc:
+ tracker.fail(task_id, str(exc))
+ logger.exception("Background commit failed: session=%s task=%s", session_id, task_id)
@router.post("/{session_id}/extract")
diff --git a/openviking/server/routers/tasks.py b/openviking/server/routers/tasks.py
new file mode 100644
index 000000000..e165ad558
--- /dev/null
+++ b/openviking/server/routers/tasks.py
@@ -0,0 +1,47 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""Task tracking endpoints for OpenViking HTTP Server.
+
+Provides observability for background operations (e.g. session commit
+with ``wait=false``). Callers receive a ``task_id`` and can poll these
+endpoints to check completion, results, or errors.
+"""
+
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException, Query
+
+from openviking.server.models import Response
+from openviking.service.task_tracker import get_task_tracker
+
+router = APIRouter(prefix="/api/v1", tags=["tasks"])
+
+
[email protected]("/tasks/{task_id}")
+async def get_task(task_id: str):
+ """Get the status of a single background task."""
+ tracker = get_task_tracker()
+ task = tracker.get(task_id)
+ if not task:
+ raise HTTPException(status_code=404, detail="Task not found or expired")
+ return Response(status="ok", result=task.to_dict())
+
+
+async def list_tasks(
+ task_type: Optional[str] = Query(None, description="Filter by task type (e.g. session_commit)"),
+ status: Optional[str] = Query(
+ None, description="Filter by status (pending/running/completed/failed)"
+ ),
+ resource_id: Optional[str] = Query(None, description="Filter by resource ID (e.g. session_id)"),
+ limit: int = Query(50, le=200, description="Max results"),
+):
+ """List background tasks with optional filters."""
+ tracker = get_task_tracker()
+ tasks = tracker.list_tasks(
+ task_type=task_type,
+ status=status,
+ resource_id=resource_id,
+ limit=limit,
+ )
+ return Response(status="ok", result=[t.to_dict() for t in tasks])
diff --git a/openviking/service/task_tracker.py b/openviking/service/task_tracker.py
new file mode 100644
index 000000000..e001cccd5
--- /dev/null
+++ b/openviking/service/task_tracker.py
@@ -0,0 +1,294 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Async Task Tracker for OpenViking.
+
+Provides a lightweight, in-memory registry for tracking background operations
+(e.g. session commit with wait=false). Callers receive a task_id that can be
+polled via the /tasks API to check completion status, results, or errors.
+
+Design decisions:
+ - v1 is pure in-memory (no persistence). Tasks are lost on restart.
+ - Thread-safe (QueueManager workers run in separate threads).
+ - TTL-based cleanup prevents unbounded memory growth.
+ - Error messages are sanitized to avoid leaking sensitive data.
+"""
+
+import asyncio
+import re
+import threading
+import time
+from copy import deepcopy
+from dataclasses import asdict, dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional
+from uuid import uuid4
+
+from openviking_cli.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class TaskStatus(str, Enum):
+ """Lifecycle states of an async task."""
+
+ PENDING = "pending"
+ RUNNING = "running"
+ COMPLETED = "completed"
+ FAILED = "failed"
+
+
+@dataclass
+class TaskRecord:
+ """Immutable snapshot of an async task."""
+
+ task_id: str
+ task_type: str # e.g. "session_commit"
+ status: TaskStatus = TaskStatus.PENDING
+ created_at: float = field(default_factory=time.time)
+ updated_at: float = field(default_factory=time.time)
+ resource_id: Optional[str] = None # e.g. session_id
+ result: Optional[Dict[str, Any]] = None
+ error: Optional[str] = None
+
+ def to_dict(self) -> Dict[str, Any]:
+ """Serialize for JSON response."""
+ d = asdict(self)
+ d["status"] = self.status.value
+ return d
+
+
+# ── Singleton ──
+
+_instance: Optional["TaskTracker"] = None
+_init_lock = threading.Lock()
+
+
+def get_task_tracker() -> "TaskTracker":
+ """Get or create the global TaskTracker singleton."""
+ global _instance
+ if _instance is None:
+ with _init_lock:
+ if _instance is None:
+ _instance = TaskTracker()
+ return _instance
+
+
+def reset_task_tracker() -> None:
+ """Reset singleton (for testing)."""
+ global _instance
+ _instance = None
+
+
+# ── Sanitization ──
+
+_SENSITIVE_PATTERNS = re.compile(
+ r"(sk-|cr_|ghp_|ntn_|xox[baprs]-|Bearer\s+)[a-zA-Z0-9._-]+",
+ re.IGNORECASE,
+)
+
+_MAX_ERROR_LEN = 500
+
+
+def _sanitize_error(error: str) -> str:
+ """Remove potential secrets from error messages."""
+ sanitized = _SENSITIVE_PATTERNS.sub("[REDACTED]", error)
+ if len(sanitized) > _MAX_ERROR_LEN:
+ sanitized = sanitized[:_MAX_ERROR_LEN] + "...[truncated]"
+ return sanitized
+
+
+# ── TaskTracker ──
+
+
+class TaskTracker:
+ """In-memory async task tracker with TTL-based cleanup.
+
+ Thread-safe: all mutations go through ``_lock``.
+ """
+
+ MAX_TASKS = 10_000
+ TTL_COMPLETED = 86_400 # 24 hours
+ TTL_FAILED = 604_800 # 7 days
+ CLEANUP_INTERVAL = 300 # 5 minutes
+
+ def __init__(self) -> None:
+ self._tasks: Dict[str, TaskRecord] = {}
+ self._lock = threading.Lock()
+ self._cleanup_task: Optional[asyncio.Task] = None
+ logger.info("[TaskTracker] Initialized (in-memory, max_tasks=%d)", self.MAX_TASKS)
+
+ # ── Lifecycle ──
+
+ def start_cleanup_loop(self) -> None:
+ """Start the background TTL cleanup coroutine.
+
+ Safe to call multiple times; subsequent calls are no-ops.
+ Must be called from within a running event loop.
+ """
+ if self._cleanup_task is not None and not self._cleanup_task.done():
+ return
+ self._cleanup_task = asyncio.create_task(self._cleanup_loop())
+ logger.debug("[TaskTracker] Cleanup loop started")
+
+ def stop_cleanup_loop(self) -> None:
+ """Cancel the background cleanup task. Safe to call if not started."""
+ if self._cleanup_task is not None and not self._cleanup_task.done():
+ self._cleanup_task.cancel()
+ logger.debug("[TaskTracker] Cleanup loop stopped")
+
+ async def _cleanup_loop(self) -> None:
+ while True:
+ try:
+ await asyncio.sleep(self.CLEANUP_INTERVAL)
+ self._evict_expired()
+ except asyncio.CancelledError:
+ break
+ except Exception:
+ logger.exception("[TaskTracker] Cleanup error")
+
+ def _evict_expired(self) -> None:
+ """Remove expired tasks and enforce MAX_TASKS."""
+ now = time.time()
+ with self._lock:
+ to_delete = []
+ for tid, t in self._tasks.items():
+ if t.status == TaskStatus.COMPLETED and (now - t.updated_at) > self.TTL_COMPLETED:
+ to_delete.append(tid)
+ elif t.status == TaskStatus.FAILED and (now - t.updated_at) > self.TTL_FAILED:
+ to_delete.append(tid)
+ for tid in to_delete:
+ del self._tasks[tid]
+
+ # FIFO eviction if still over limit
+ if len(self._tasks) > self.MAX_TASKS:
+ sorted_tasks = sorted(self._tasks.items(), key=lambda x: x[1].created_at)
+ excess = len(self._tasks) - self.MAX_TASKS
+ for tid, _ in sorted_tasks[:excess]:
+ del self._tasks[tid]
+
+ if to_delete:
+ logger.debug("[TaskTracker] Evicted %d expired tasks", len(to_delete))
+
+ # ── CRUD ──
+
+ def create(self, task_type: str, resource_id: Optional[str] = None) -> TaskRecord:
+ """Register a new pending task. Returns a snapshot copy."""
+ task = TaskRecord(
+ task_id=str(uuid4()),
+ task_type=task_type,
+ resource_id=resource_id,
+ )
+ with self._lock:
+ self._tasks[task.task_id] = task
+ logger.debug(
+ "[TaskTracker] Created task %s type=%s resource=%s",
+ task.task_id,
+ task_type,
+ resource_id,
+ )
+ return self._copy(task)
+
+ def create_if_no_running(self, task_type: str, resource_id: str) -> Optional[TaskRecord]:
+ """Atomically check for running tasks and create a new one if none exist.
+
+ Returns TaskRecord on success, None if a running task already exists.
+ This eliminates the race condition between has_running() and create().
+ """
+ with self._lock:
+ # Check for existing running tasks
+ has_active = any(
+ t.task_type == task_type
+ and t.resource_id == resource_id
+ and t.status in (TaskStatus.PENDING, TaskStatus.RUNNING)
+ for t in self._tasks.values()
+ )
+ if has_active:
+ return None
+ # Create atomically within same lock
+ task = TaskRecord(
+ task_id=str(uuid4()),
+ task_type=task_type,
+ resource_id=resource_id,
+ )
+ self._tasks[task.task_id] = task
+ logger.debug(
+ "[TaskTracker] Created task %s type=%s resource=%s",
+ task.task_id,
+ task_type,
+ resource_id,
+ )
+ return self._copy(task)
+
+ def start(self, task_id: str) -> None:
+ """Transition task to RUNNING."""
+ with self._lock:
+ task = self._tasks.get(task_id)
+ if task:
+ task.status = TaskStatus.RUNNING
+ task.updated_at = time.time()
+
+ def complete(self, task_id: str, result: Optional[Dict[str, Any]] = None) -> None:
+ """Transition task to COMPLETED with optional result."""
+ with self._lock:
+ task = self._tasks.get(task_id)
+ if task:
+ task.status = TaskStatus.COMPLETED
+ task.result = result
+ task.updated_at = time.time()
+ logger.info("[TaskTracker] Task %s completed", task_id)
+
+ def fail(self, task_id: str, error: str) -> None:
+ """Transition task to FAILED with sanitized error."""
+ with self._lock:
+ task = self._tasks.get(task_id)
+ if task:
+ task.status = TaskStatus.FAILED
+ task.error = _sanitize_error(error)
+ task.updated_at = time.time()
+ logger.warning("[TaskTracker] Task %s failed: %s", task_id, _sanitize_error(error))
+
+ def get(self, task_id: str) -> Optional[TaskRecord]:
+ """Look up a single task. Returns a snapshot copy (None if not found)."""
+ with self._lock:
+ task = self._tasks.get(task_id)
+ return self._copy(task) if task else None
+
+ def list_tasks(
+ self,
+ task_type: Optional[str] = None,
+ status: Optional[str] = None,
+ resource_id: Optional[str] = None,
+ limit: int = 50,
+ ) -> List[TaskRecord]:
+ """List tasks with optional filters. Most-recent first. Returns snapshot copies."""
+ with self._lock:
+ tasks = [self._copy(t) for t in self._tasks.values()]
+ if task_type:
+ tasks = [t for t in tasks if t.task_type == task_type]
+ if status:
+ tasks = [t for t in tasks if t.status.value == status]
+ if resource_id:
+ tasks = [t for t in tasks if t.resource_id == resource_id]
+ tasks.sort(key=lambda t: t.created_at, reverse=True)
+ return tasks[:limit]
+
+ def has_running(self, task_type: str, resource_id: str) -> bool:
+ """Check if there is already a running task for the given type+resource."""
+ with self._lock:
+ return any(
+ t.task_type == task_type
+ and t.resource_id == resource_id
+ and t.status in (TaskStatus.PENDING, TaskStatus.RUNNING)
+ for t in self._tasks.values()
+ )
+
+ @staticmethod
+ def _copy(task: TaskRecord) -> TaskRecord:
+ """Return a defensive copy of a TaskRecord."""
+ return deepcopy(task)
+
+ def count(self) -> int:
+ """Return total task count."""
+ with self._lock:
+ return len(self._tasks)
diff --git a/tests/conftest.py b/tests/conftest.py
index 9ace5753d..fafdc332b 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -13,6 +13,66 @@ import pytest_asyncio
from openviking import AsyncOpenViking
+
+# ── Workaround: local .so may lack AGFS_Grep symbol (new in latest source) ──
+def _patch_agfs_grep_if_missing():
+ """Wrap _setup_functions to catch missing AGFS_Grep and skip its binding."""
+ try:
+ from openviking.pyagfs.binding_client import BindingLib
+
+ _orig_setup = BindingLib._setup_functions
+
+ def _safe_setup(self):
+ try:
+ _orig_setup(self)
+ except AttributeError as e:
+ if "AGFS_Grep" not in str(e):
+ raise
+ # Re-implement _setup_functions but skip AGFS_Grep lines.
+ # We do this by temporarily removing the Grep lines from the
+ # source, but since we can't edit .so, we monkey-patch the lib
+ # object's __getattr__ to not fail on AGFS_Grep.
+ import ctypes
+
+ class _GrepStub:
+ """Fake ctypes function descriptor for AGFS_Grep."""
+
+ argtypes = [
+ ctypes.c_int64,
+ ctypes.c_char_p,
+ ctypes.c_char_p,
+ ctypes.c_int,
+ ctypes.c_int,
+ ctypes.c_int,
+ ctypes.c_int,
+ ]
+ restype = ctypes.c_char_p
+
+ def __call__(self, *args):
+ return b'{"error":"AGFS_Grep not available in this .so version"}'
+
+ # Patch at the CDLL instance level by overriding __getattr__
+ orig_class = type(self.lib)
+ orig_getattr = orig_class.__getattr__
+
+ def patched_getattr(cdll_self, name):
+ if name == "AGFS_Grep":
+ return _GrepStub()
+ return orig_getattr(cdll_self, name)
+
+ orig_class.__getattr__ = patched_getattr
+ try:
+ _orig_setup(self)
+ finally:
+ orig_class.__getattr__ = orig_getattr
+
+ BindingLib._setup_functions = _safe_setup
+ except Exception:
+ pass
+
+
+_patch_agfs_grep_if_missing()
+
# Test data root directory
PROJECT_ROOT = Path(__file__).parent.parent
TEST_TMP_DIR = PROJECT_ROOT / "test_data" / "tmp"
diff --git a/tests/test_session_task_tracking.py b/tests/test_session_task_tracking.py
new file mode 100644
index 000000000..ab779fb2d
--- /dev/null
+++ b/tests/test_session_task_tracking.py
@@ -0,0 +1,262 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Integration tests for session commit task tracking via HTTP API."""
+
+import asyncio
+from typing import AsyncGenerator, Tuple
+
+import httpx
+import pytest_asyncio
+
+from openviking import AsyncOpenViking
+from openviking.server.app import create_app
+from openviking.server.config import ServerConfig
+from openviking.server.dependencies import set_service
+from openviking.service.core import OpenVikingService
+from openviking.service.task_tracker import reset_task_tracker
+
+
+@pytest_asyncio.fixture
+async def api_client(temp_dir) -> AsyncGenerator[Tuple[httpx.AsyncClient, OpenVikingService], None]:
+ """Create in-process HTTP client for API endpoint tests."""
+ reset_task_tracker()
+ service = OpenVikingService(path=str(temp_dir / "api_data"))
+ await service.initialize()
+ app = create_app(config=ServerConfig(), service=service)
+ set_service(service)
+
+ transport = httpx.ASGITransport(app=app)
+ async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as client:
+ yield client, service
+
+ await service.close()
+ await AsyncOpenViking.reset()
+ reset_task_tracker()
+
+
+async def _new_session_with_message(client: httpx.AsyncClient) -> str:
+ resp = await client.post("/api/v1/sessions", json={})
+ assert resp.status_code == 200
+ session_id = resp.json()["result"]["session_id"]
+ await client.post(
+ f"/api/v1/sessions/{session_id}/messages",
+ json={"role": "user", "content": "hello world"},
+ )
+ return session_id
+
+
+# ── wait=false returns task_id ──
+
+
+async def test_commit_wait_false_returns_task_id(api_client):
+ """wait=false should return a task_id for polling."""
+ client, service = api_client
+ session_id = await _new_session_with_message(client)
+
+ done = asyncio.Event()
+
+ async def fake_commit(_sid, _ctx):
+ await asyncio.sleep(0.1)
+ done.set()
+ return {"session_id": _sid, "status": "committed", "memories_extracted": 0}
+
+ service.sessions.commit_async = fake_commit
+
+ resp = await client.post(f"/api/v1/sessions/{session_id}/commit", params={"wait": False})
+ assert resp.status_code == 200
+ body = resp.json()
+ assert body["result"]["status"] == "accepted"
+ assert "task_id" in body["result"]
+
+ await asyncio.wait_for(done.wait(), timeout=2.0)
+
+
+# ── Task lifecycle: pending → running → completed ──
+
+
+async def test_task_lifecycle_success(api_client):
+ """Task should transition pending→running→completed on success."""
+ client, service = api_client
+ session_id = await _new_session_with_message(client)
+
+ commit_started = asyncio.Event()
+ commit_gate = asyncio.Event()
+
+ async def gated_commit(_sid, _ctx):
+ commit_started.set()
+ await commit_gate.wait()
+ return {"session_id": _sid, "status": "committed", "memories_extracted": 5}
+
+ service.sessions.commit_async = gated_commit
+
+ # Fire background commit
+ resp = await client.post(f"/api/v1/sessions/{session_id}/commit", params={"wait": False})
+ task_id = resp.json()["result"]["task_id"]
+
+ # Wait for commit to start
+ await asyncio.wait_for(commit_started.wait(), timeout=2.0)
+
+ # Task should be running
+ task_resp = await client.get(f"/api/v1/tasks/{task_id}")
+ assert task_resp.status_code == 200
+ assert task_resp.json()["result"]["status"] == "running"
+
+ # Release the commit
+ commit_gate.set()
+ await asyncio.sleep(0.1)
+
+ # Task should be completed
+ task_resp = await client.get(f"/api/v1/tasks/{task_id}")
+ assert task_resp.status_code == 200
+ result = task_resp.json()["result"]
+ assert result["status"] == "completed"
+ assert result["result"]["memories_extracted"] == 5
+
+
+# ── Task lifecycle: pending → running → failed ──
+
+
+async def test_task_lifecycle_failure(api_client):
+ """Task should transition to failed on commit error."""
+ client, service = api_client
+ session_id = await _new_session_with_message(client)
+
+ async def failing_commit(_sid, _ctx):
+ raise RuntimeError("LLM provider timeout")
+
+ service.sessions.commit_async = failing_commit
+
+ resp = await client.post(f"/api/v1/sessions/{session_id}/commit", params={"wait": False})
+ task_id = resp.json()["result"]["task_id"]
+
+ await asyncio.sleep(0.2)
+
+ task_resp = await client.get(f"/api/v1/tasks/{task_id}")
+ assert task_resp.status_code == 200
+ result = task_resp.json()["result"]
+ assert result["status"] == "failed"
+ assert "LLM provider timeout" in result["error"]
+
+
+# ── Duplicate commit rejection ──
+
+
+async def test_duplicate_commit_rejected(api_client):
+ """Second commit on same session should be rejected while first is running."""
+ client, service = api_client
+ session_id = await _new_session_with_message(client)
+
+ gate = asyncio.Event()
+
+ async def slow_commit(_sid, _ctx):
+ await gate.wait()
+ return {"session_id": _sid, "status": "committed", "memories_extracted": 0}
+
+ service.sessions.commit_async = slow_commit
+
+ # First commit
+ resp1 = await client.post(f"/api/v1/sessions/{session_id}/commit", params={"wait": False})
+ assert resp1.json()["result"]["status"] == "accepted"
+
+ # Second commit should be rejected
+ resp2 = await client.post(f"/api/v1/sessions/{session_id}/commit", params={"wait": False})
+ assert resp2.json()["status"] == "error"
+ assert "already has a commit in progress" in resp2.json()["error"]["message"]
+
+ gate.set()
+ await asyncio.sleep(0.1)
+
+
+# ── GET /tasks/{id} 404 ──
+
+
+async def test_get_nonexistent_task_returns_404(api_client):
+ client, _ = api_client
+ resp = await client.get("/api/v1/tasks/nonexistent-id")
+ assert resp.status_code == 404
+
+
+# ── GET /tasks list ──
+
+
+async def test_list_tasks(api_client):
+ client, service = api_client
+ session_id = await _new_session_with_message(client)
+
+ async def instant_commit(_sid, _ctx):
+ return {"session_id": _sid, "status": "committed", "memories_extracted": 0}
+
+ service.sessions.commit_async = instant_commit
+
+ await client.post(f"/api/v1/sessions/{session_id}/commit", params={"wait": False})
+ await asyncio.sleep(0.1)
+
+ resp = await client.get("/api/v1/tasks", params={"task_type": "session_commit"})
+ assert resp.status_code == 200
+ tasks = resp.json()["result"]
+ assert len(tasks) >= 1
+ assert tasks[0]["task_type"] == "session_commit"
+
+
+async def test_list_tasks_filter_status(api_client):
+ client, service = api_client
+
+ async def instant_commit(_sid, _ctx):
+ return {"session_id": _sid, "status": "committed", "memories_extracted": 0}
+
+ service.sessions.commit_async = instant_commit
+
+ session_id = await _new_session_with_message(client)
+ await client.post(f"/api/v1/sessions/{session_id}/commit", params={"wait": False})
+ await asyncio.sleep(0.1)
+
+ # completed tasks
+ resp = await client.get("/api/v1/tasks", params={"status": "completed"})
+ assert resp.status_code == 200
+ for t in resp.json()["result"]:
+ assert t["status"] == "completed"
+
+
+# ── wait=true still works (backward compat) ──
+
+
+async def test_wait_true_still_works(api_client):
+ """wait=true should return inline result, no task_id."""
+ client, service = api_client
+ session_id = await _new_session_with_message(client)
+
+ async def instant_commit(_sid, _ctx):
+ return {"session_id": _sid, "status": "committed", "memories_extracted": 2}
+
+ service.sessions.commit_async = instant_commit
+
+ resp = await client.post(f"/api/v1/sessions/{session_id}/commit", params={"wait": True})
+ assert resp.status_code == 200
+ body = resp.json()
+ assert body["result"]["status"] == "committed"
+ assert "task_id" not in body["result"]
+
+
+# ── Error sanitization in task ──
+
+
+async def test_error_sanitized_in_task(api_client):
+ """Errors stored in tasks should have secrets redacted."""
+ client, service = api_client
+ session_id = await _new_session_with_message(client)
+
+ async def leaky_commit(_sid, _ctx):
+ raise RuntimeError("Auth failed with key sk-ant-api03-DAqSsuperSecretKey123")
+
+ service.sessions.commit_async = leaky_commit
+
+ resp = await client.post(f"/api/v1/sessions/{session_id}/commit", params={"wait": False})
+ task_id = resp.json()["result"]["task_id"]
+
+ await asyncio.sleep(0.2)
+
+ task_resp = await client.get(f"/api/v1/tasks/{task_id}")
+ error = task_resp.json()["result"]["error"]
+ assert "superSecretKey" not in error
+ assert "[REDACTED]" in error
diff --git a/tests/test_task_tracker.py b/tests/test_task_tracker.py
new file mode 100644
index 000000000..e000933d1
--- /dev/null
+++ b/tests/test_task_tracker.py
@@ -0,0 +1,244 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Unit tests for TaskTracker."""
+
+import time
+
+import pytest
+
+from openviking.service.task_tracker import (
+ TaskStatus,
+ TaskTracker,
+ _sanitize_error,
+ get_task_tracker,
+ reset_task_tracker,
+)
+
+
[email protected](autouse=True)
+def clean_singleton():
+ """Reset singleton before and after each test."""
+ reset_task_tracker()
+ yield
+ reset_task_tracker()
+
+
+def tracker() -> TaskTracker:
+ return TaskTracker()
+
+
+# ── Basic CRUD ──
+
+
+def test_create_task(tracker: TaskTracker):
+ task = tracker.create("session_commit", resource_id="sess-123")
+ assert task.task_id
+ assert task.task_type == "session_commit"
+ assert task.resource_id == "sess-123"
+ assert task.status == TaskStatus.PENDING
+
+
+def test_start_task(tracker: TaskTracker):
+ task = tracker.create("session_commit")
+ tracker.start(task.task_id)
+ retrieved = tracker.get(task.task_id)
+ assert retrieved is not None
+ assert retrieved.status == TaskStatus.RUNNING
+
+
+def test_complete_task(tracker: TaskTracker):
+ task = tracker.create("session_commit", resource_id="s1")
+ tracker.start(task.task_id)
+ tracker.complete(task.task_id, {"memories_extracted": 3})
+ retrieved = tracker.get(task.task_id)
+ assert retrieved is not None
+ assert retrieved.status == TaskStatus.COMPLETED
+ assert retrieved.result == {"memories_extracted": 3}
+
+
+def test_fail_task(tracker: TaskTracker):
+ task = tracker.create("session_commit")
+ tracker.start(task.task_id)
+ tracker.fail(task.task_id, "LLM timeout")
+ retrieved = tracker.get(task.task_id)
+ assert retrieved is not None
+ assert retrieved.status == TaskStatus.FAILED
+ assert "LLM timeout" in retrieved.error
+
+
+def test_get_nonexistent_returns_none(tracker: TaskTracker):
+ assert tracker.get("does-not-exist") is None
+
+
+# ── List / Filter ──
+
+
+def test_list_all(tracker: TaskTracker):
+ tracker.create("session_commit", resource_id="s1")
+ tracker.create("resource_ingest", resource_id="r1")
+ tasks = tracker.list_tasks()
+ assert len(tasks) == 2
+
+
+def test_list_filter_by_type(tracker: TaskTracker):
+ tracker.create("session_commit")
+ tracker.create("resource_ingest")
+ tasks = tracker.list_tasks(task_type="session_commit")
+ assert len(tasks) == 1
+ assert tasks[0].task_type == "session_commit"
+
+
+def test_list_filter_by_status(tracker: TaskTracker):
+ t1 = tracker.create("session_commit")
+ tracker.create("session_commit")
+ tracker.start(t1.task_id)
+ tracker.complete(t1.task_id, {})
+
+ completed = tracker.list_tasks(status="completed")
+ assert len(completed) == 1
+ pending = tracker.list_tasks(status="pending")
+ assert len(pending) == 1
+
+
+def test_list_filter_by_resource_id(tracker: TaskTracker):
+ tracker.create("session_commit", resource_id="s1")
+ tracker.create("session_commit", resource_id="s2")
+ tasks = tracker.list_tasks(resource_id="s1")
+ assert len(tasks) == 1
+ assert tasks[0].resource_id == "s1"
+
+
+def test_list_limit(tracker: TaskTracker):
+ for i in range(10):
+ tracker.create("session_commit", resource_id=f"s{i}")
+ tasks = tracker.list_tasks(limit=3)
+ assert len(tasks) == 3
+
+
+def test_list_order_most_recent_first(tracker: TaskTracker):
+ tracker.create("session_commit", resource_id="first")
+ tracker.create("session_commit", resource_id="second")
+ tasks = tracker.list_tasks()
+ assert tasks[0].resource_id == "second"
+ assert tasks[1].resource_id == "first"
+
+
+# ── Duplicate detection ──
+
+
+def test_has_running_detects_pending(tracker: TaskTracker):
+ tracker.create("session_commit", resource_id="s1")
+ assert tracker.has_running("session_commit", "s1") is True
+
+
+def test_has_running_detects_running(tracker: TaskTracker):
+ t = tracker.create("session_commit", resource_id="s1")
+ tracker.start(t.task_id)
+ assert tracker.has_running("session_commit", "s1") is True
+
+
+def test_has_running_false_after_complete(tracker: TaskTracker):
+ t = tracker.create("session_commit", resource_id="s1")
+ tracker.start(t.task_id)
+ tracker.complete(t.task_id, {})
+ assert tracker.has_running("session_commit", "s1") is False
+
+
+def test_has_running_false_after_fail(tracker: TaskTracker):
+ t = tracker.create("session_commit", resource_id="s1")
+ tracker.start(t.task_id)
+ tracker.fail(t.task_id, "error")
+ assert tracker.has_running("session_commit", "s1") is False
+
+
+# ── Serialization ──
+
+
+def test_to_dict(tracker: TaskTracker):
+ task = tracker.create("session_commit", resource_id="s1")
+ d = task.to_dict()
+ assert d["task_id"] == task.task_id
+ assert d["status"] == "pending"
+ assert d["task_type"] == "session_commit"
+ assert d["resource_id"] == "s1"
+ assert isinstance(d["created_at"], float)
+
+
+# ── Sanitization ──
+
+
+def test_sanitize_removes_sk_key():
+ assert "[REDACTED]" in _sanitize_error("Error with sk-ant-api03-DAqSxxxxx")
+
+
+def test_sanitize_removes_ghp_token():
+ assert "[REDACTED]" in _sanitize_error("Auth failed ghp_" + "x" * 36)
+
+
+def test_sanitize_removes_bearer_token():
+ assert "[REDACTED]" in _sanitize_error("Bearer xoxb-1234567890-abcdefghij")
+
+
+def test_sanitize_truncates_long_error():
+ long_error = "x" * 1000
+ sanitized = _sanitize_error(long_error)
+ assert len(sanitized) <= 520 # 500 + "...[truncated]"
+ assert sanitized.endswith("...[truncated]")
+
+
+def test_sanitize_preserves_safe_error():
+ safe = "LLM timeout after 30s"
+ assert _sanitize_error(safe) == safe
+
+
+# ── TTL / Eviction ──
+
+
+def test_evict_expired_completed(tracker: TaskTracker):
+ t = tracker.create("session_commit")
+ tracker.start(t.task_id)
+ tracker.complete(t.task_id, {})
+ # Simulate old timestamp (access internal state; get() returns defensive copies)
+ tracker._tasks[t.task_id].updated_at = time.time() - tracker.TTL_COMPLETED - 1
+ tracker._evict_expired()
+ assert tracker.get(t.task_id) is None
+
+
+def test_evict_keeps_recent_completed(tracker: TaskTracker):
+ t = tracker.create("session_commit")
+ tracker.start(t.task_id)
+ tracker.complete(t.task_id, {})
+ tracker._evict_expired()
+ assert tracker.get(t.task_id) is not None
+
+
+def test_evict_fifo_when_over_limit(tracker: TaskTracker):
+ tracker.MAX_TASKS = 5
+ tasks = []
+ for i in range(7):
+ tasks.append(tracker.create("session_commit", resource_id=f"s{i}"))
+ tracker._evict_expired()
+ assert tracker.count() == 5
+ # Oldest should be gone
+ assert tracker.get(tasks[0].task_id) is None
+ assert tracker.get(tasks[1].task_id) is None
+ # Newest should remain
+ assert tracker.get(tasks[6].task_id) is not None
+
+
+# ── Singleton ──
+
+
+def test_singleton():
+ t1 = get_task_tracker()
+ t2 = get_task_tracker()
+ assert t1 is t2
+
+
+def test_singleton_reset():
+ t1 = get_task_tracker()
+ reset_task_tracker()
+ t2 = get_task_tracker()
+ assert t1 is not t2