Skip to content

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

6.6 KB
Raw Blame
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.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, Depends, Query

from openviking.server.auth import get_request_context
from openviking.server.identity import RequestContext, Role
from openviking.server.models import Response
from openviking.service.task_store import SYSTEM_TASK_ACCOUNT_ID, SYSTEM_TASK_USER_ID
from openviking.service.task_tracker import get_task_tracker
from openviking_cli.exceptions import (
    FailedPreconditionError,
    OpenVikingError,
    PermissionDeniedError,
)

router = APIRouter(prefix="/api/v1", tags=["tasks"])


@router.get("/tasks/{task_id}")
async def get_task(
    task_id: str,
    include_events: bool = Query(False, description="Include recorded execution events"),
    _ctx: RequestContext = Depends(get_request_context),
):
    """Get the status of a single background task."""
    tracker = get_task_tracker()
    get_task_record = tracker.get_with_events if include_events else tracker.get
    if _ctx.role == Role.ROOT:
        task = await get_task_record(task_id)
        if task is None:
            task = await get_task_record(
                task_id, account_id=_ctx.account_id, user_id=_ctx.user.user_id
            )
        if task is None:
            task = await get_task_record(
                task_id,
                account_id=SYSTEM_TASK_ACCOUNT_ID,
                user_id=SYSTEM_TASK_USER_ID,
            )
    else:
        task = await get_task_record(
            task_id,
            account_id=_ctx.account_id,
            user_id=_ctx.user.user_id,
        )
    if not task:
        raise OpenVikingError(
            "Task not found or expired",
            code="NOT_FOUND",
            details={"resource": task_id, "type": "task"},
        )
    return Response(status="ok", result=task.to_dict(include_events=include_events))


@router.post("/tasks/{task_id}/cancel")
async def cancel_task(
    task_id: str,
    _ctx: RequestContext = Depends(get_request_context),
):
    """Request cooperative cancellation of a background task."""
    if _ctx.role == Role.ROOT:
        raise PermissionDeniedError("ROOT may not cancel tasks")
    tracker = get_task_tracker()
    try:
        task = await tracker.cancel(
            task_id,
            account_id=_ctx.account_id,
            user_id=_ctx.user.user_id,
        )
    except ValueError as exc:
        raise FailedPreconditionError(str(exc)) from exc
    if task is None:
        raise OpenVikingError(
            "Task not found or expired",
            code="NOT_FOUND",
            details={"resource": task_id, "type": "task"},
        )
    return Response(status="ok", result=task.to_dict())


@router.get("/tasks")
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/cancelling/completed/failed/cancelled)",
    ),
    resource_id: Optional[str] = Query(None, description="Filter by resource ID (e.g. session_id)"),
    include_internal: bool = Query(False, description="Include internal Connector child tasks"),
    limit: int = Query(50, ge=1, le=200, description="Max results"),
    pagination: Optional[str] = Query(None, pattern="^cursor$"),
    cursor: Optional[str] = Query(None, max_length=2048),
    q: Optional[str] = Query(None, max_length=200),
    _ctx: RequestContext = Depends(get_request_context),
):
    """List background tasks with optional filters."""
    tracker = get_task_tracker()
    if pagination == "cursor":
        from openviking.service.task_pagination import decode_cursor, encode_cursor, page_scope

        filters = {
            "task_type": task_type,
            "status": status,
            "resource_id": resource_id,
            "include_internal": include_internal,
            "q": q,
        }
        scope = page_scope(
            account=_ctx.account_id, user=_ctx.user.user_id, role=str(_ctx.role), **filters
        )
        list_call = (
            tracker.list_root_tasks(
                account_id=_ctx.account_id,
                user_id=_ctx.user.user_id,
                limit=limit + 1,
                before=decode_cursor(cursor, scope),
                task_type=task_type,
                status=status,
                resource_id=resource_id,
                include_internal=include_internal,
                q=q,
            )
            if _ctx.role == Role.ROOT
            else tracker.list_tasks(
                account_id=_ctx.account_id,
                user_id=_ctx.user.user_id,
                limit=limit + 1,
                before=decode_cursor(cursor, scope),
                task_type=task_type,
                status=status,
                resource_id=resource_id,
                include_internal=include_internal,
                q=q,
            )
        )
        tasks = await list_call
        more = len(tasks) > limit
        items = [t.to_dict() for t in tasks[:limit]]
        return Response(
            status="ok",
            result={
                "items": items,
                "has_more": more,
                "next_cursor": encode_cursor(items[-1], scope) if more else None,
            },
        )
    if _ctx.role == Role.ROOT:
        system_tasks = await tracker.list_tasks(
            task_type=task_type,
            status=status,
            resource_id=resource_id,
            limit=limit,
            account_id=SYSTEM_TASK_ACCOUNT_ID,
            user_id=SYSTEM_TASK_USER_ID,
            include_internal=include_internal,
        )
        cached_tasks = await tracker.list_tasks(
            task_type=task_type,
            status=status,
            resource_id=resource_id,
            limit=limit,
            include_internal=include_internal,
        )
        tasks_by_id = {task.task_id: task for task in cached_tasks}
        tasks_by_id.update({task.task_id: task for task in system_tasks})
        tasks = sorted(tasks_by_id.values(), key=lambda task: task.created_at, reverse=True)[:limit]
    else:
        tasks = await tracker.list_tasks(
            task_type=task_type,
            status=status,
            resource_id=resource_id,
            limit=limit,
            account_id=_ctx.account_id,
            user_id=_ctx.user.user_id,
            include_internal=include_internal,
        )
    return Response(status="ok", result=[t.to_dict() for t in tasks])