Skip to content

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

30.5 KB
Raw Blame
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""Sessions endpoints for OpenViking HTTP Server."""

from typing import Any, Dict, List, Literal, Optional

from fastapi import APIRouter, Body, Depends, HTTPException, Path, Query
from pydantic import BaseModel, Field, StrictBool, field_validator, model_validator

from openviking.core.path_variables import resolve_path_variables
from openviking.core.peer_id import normalize_peer_id
from openviking.core.uri_validation import validate_request_viking_uri
from openviking.message.part import Part, TextPart, part_from_dict
from openviking.server.auth import get_session_request_context
from openviking.server.dependencies import get_service
from openviking.server.identity import RequestContext
from openviking.server.models import Response
from openviking.server.responses import error_response
from openviking.server.telemetry import run_operation
from openviking.session.auto_commit_policy import validate_idle_timeout_input
from openviking.telemetry import TelemetryRequest
from openviking.utils.image_search import is_viking_uri
from openviking_cli.utils import get_logger

router = APIRouter(prefix="/api/v1/sessions", tags=["sessions"])
logger = get_logger(__name__)


class TextPartRequest(BaseModel):
    """Text part request model."""

    type: Literal["text"] = "text"
    text: str


class ContextPartRequest(BaseModel):
    """Context part request model."""

    type: Literal["context"] = "context"
    uri: str = ""
    context_type: Literal["memory", "resource", "skill"] = "memory"
    abstract: str = ""


class ToolPartRequest(BaseModel):
    """Tool part request model."""

    type: Literal["tool"] = "tool"
    tool_id: str = ""
    tool_name: str = ""
    tool_uri: str = ""
    skill_uri: str = ""
    tool_input: Optional[Dict[str, Any]] = None
    tool_output: str = ""
    tool_status: str = "pending"
    duration_ms: Optional[float] = None
    prompt_tokens: Optional[int] = None
    completion_tokens: Optional[int] = None
    tool_output_ref: str = ""
    tool_output_truncated: bool = False
    tool_output_original_chars: Optional[int] = None
    tool_output_preview_chars: Optional[int] = None
    tool_output_sha256: str = ""
    tool_output_storage_uri: str = ""
    tool_output_mime_type: str = "text/plain"
    tool_output_source_ref: str = ""
    tool_output_source_offset: Optional[int] = None
    tool_output_source_limit: Optional[int] = None
    tool_output_externalization_error: str = ""
    tool_output_group_id: str = ""
    tool_output_externalized_reason: str = ""
    tool_output_group_original_chars: Optional[int] = None
    tool_output_group_budget_chars: Optional[int] = None


PartRequest = TextPartRequest | ContextPartRequest | ToolPartRequest


class AutoCommitPolicyRequest(BaseModel):
    """Session-level auto-commit policy overrides.

    All fields are optional. ``idle_timeout_seconds`` validates its write-time
    minimum here so legacy stored policies remain readable. Other bounds are
    clamped by ``AutoCommitPolicy``.
    """

    pending_token_threshold: Optional[int] = None
    message_count_threshold: Optional[int] = None
    idle_timeout_seconds: Optional[int] = None
    keep_recent_count: Optional[int] = None
    min_commit_interval_seconds: Optional[int] = None

    model_config = {"extra": "forbid"}

    @field_validator("idle_timeout_seconds")
    @classmethod
    def validate_idle_timeout_seconds(cls, value: Optional[int]) -> Optional[int]:
        return None if value is None else validate_idle_timeout_input(value)

    @model_validator(mode="after")
    def reject_explicit_null_fields(self) -> "AutoCommitPolicyRequest":
        null_fields = [field for field in self.model_fields_set if getattr(self, field) is None]
        if null_fields:
            raise ValueError(
                "auto_commit_policy fields must be integers; use "
                "auto_commit_policy=null to disable automatic commits"
            )
        return self


class EventExtractionConfigRequest(BaseModel):
    """Default event-memory extraction settings for a session."""

    tags: Optional[List[str]] = Field(
        default=None,
        description=(
            "Default custom scalar tags applied to event memories extracted from "
            "this session. Each element is a strict 'key=value' string. Commit-time "
            "tags override this default; an empty list clears it."
        ),
    )

    model_config = {"extra": "forbid"}


class MemoryExtractionConfigRequest(BaseModel):
    """Per-memory-type extraction configuration."""

    events: Optional[EventExtractionConfigRequest] = None

    model_config = {"extra": "forbid"}


class AddMessageRequest(BaseModel):
    """Request model for adding a message.

    Supports two modes:
    1. Simple mode: provide `content` string (backward compatible)
    2. Parts mode: provide `parts` array for full Part support

    If both are provided, `parts` takes precedence.
    """

    role: str
    peer_id: Optional[str] = None
    content: Optional[str] = None
    parts: Optional[List[Dict[str, Any]]] = None
    created_at: Optional[str] = None
    turn_id: Optional[str] = None
    message_kind: Optional[
        Literal["user_query", "assistant_step", "tool_transport", "checkpoint"]
    ] = None
    source_message_ids: Optional[List[str]] = None
    telemetry: TelemetryRequest = False

    @field_validator("peer_id")
    @classmethod
    def validate_peer_id(cls, value: Optional[str]) -> Optional[str]:
        return normalize_peer_id(value)

    @model_validator(mode="after")
    def validate_content_or_parts(self) -> "AddMessageRequest":
        if self.content is None and self.parts is None:
            raise ValueError("Either 'content' or 'parts' must be provided")
        return self


class BatchAddMessageRequest(BaseModel):
    """Request model for adding multiple messages in a single request."""

    messages: List[AddMessageRequest] = Field(..., max_length=100)
    telemetry: TelemetryRequest = False


class CreateSessionRequest(BaseModel):
    """Request model for creating a session."""

    session_id: Optional[str] = None
    memory_policy: Optional[Dict[str, Any]] = None
    auto_commit_policy: Optional[AutoCommitPolicyRequest] = None
    memory_extraction_config: Optional[MemoryExtractionConfigRequest] = None
    telemetry: TelemetryRequest = False


def _event_tags_from_extraction_config(
    config: Optional[MemoryExtractionConfigRequest],
) -> Optional[List[str]]:
    """Extract event default tags from a memory extraction config.

    Returns ``None`` when the caller did not specify event tags (so the session
    default is left untouched), otherwise the provided list (possibly empty to
    clear the default). Normalization/validation happens in the service layer.
    """
    if config is None:
        return None
    events = config.events
    if events is None:
        return None
    return events.tags


def _commit_event_tags(
    metadata: "Optional[ExtractionMetadataRequest]",
) -> Optional[List[str]]:
    """Extract commit-time event tags from ``extraction_metadata``.

    Returns ``None`` when the caller did not specify event tags (so the session
    default applies), otherwise the provided list (possibly empty to disable
    default-tag injection for this commit). Normalization/validation happens in
    the service layer.
    """
    if metadata is None or metadata.event is None:
        return None
    return metadata.event.tags


def _resolve_message_parts(msg_request: AddMessageRequest, ctx: RequestContext) -> List[Part]:
    """Resolve parts from an AddMessageRequest, handling path variables."""
    if msg_request.parts is not None:
        return [_part_request_to_part(p, ctx) for p in msg_request.parts]
    return [TextPart(text=msg_request.content or "")]


def _session_pending_tokens(session: Any) -> int:
    """Read the post-write pending-token count from a session.

    Returns 0 when the session object does not expose ``meta`` so the response
    stays well-formed against lightweight or legacy session implementations.
    """
    meta = getattr(session, "meta", None)
    try:
        return max(0, int(getattr(meta, "pending_tokens", 0) or 0))
    except (TypeError, ValueError):
        return 0


def _part_request_to_part(raw_part: Dict[str, Any], ctx: RequestContext) -> Part:
    """Convert request part payload into an internal Part."""
    if not isinstance(raw_part, dict):
        return TextPart(text=str(raw_part))

    part_copy = dict(raw_part)
    if part_copy.get("type") == "context" and part_copy.get("uri"):
        part_copy["uri"] = validate_request_viking_uri(
            resolve_path_variables(part_copy["uri"]), ctx
        )
    if part_copy.get("type") == "tool":
        if part_copy.get("tool_uri"):
            part_copy["tool_uri"] = validate_request_viking_uri(
                resolve_path_variables(part_copy["tool_uri"]), ctx, field_name="tool_uri"
            )
        if part_copy.get("skill_uri"):
            part_copy["skill_uri"] = validate_request_viking_uri(
                resolve_path_variables(part_copy["skill_uri"]), ctx, field_name="skill_uri"
            )
        if part_copy.get("tool_output_storage_uri"):
            part_copy["tool_output_storage_uri"] = validate_request_viking_uri(
                resolve_path_variables(part_copy["tool_output_storage_uri"]),
                ctx,
                field_name="tool_output_storage_uri",
            )
    if part_copy.get("type") == "image_url":
        image_url = part_copy.get("image_url")
        if isinstance(image_url, dict) and "url" in image_url:
            image_url = dict(image_url)
            resolved_url = resolve_path_variables(image_url["url"])
            if is_viking_uri(resolved_url):
                resolved_url = validate_request_viking_uri(
                    resolved_url, ctx, field_name="image_url"
                )
            image_url["url"] = resolved_url
            part_copy["image_url"] = image_url
        elif isinstance(image_url, str):
            resolved_url = resolve_path_variables(image_url)
            part_copy["image_url"] = (
                validate_request_viking_uri(resolved_url, ctx, field_name="image_url")
                if is_viking_uri(resolved_url)
                else resolved_url
            )
    try:
        return part_from_dict(part_copy)
    except ValueError as exc:
        raise HTTPException(status_code=400, detail=str(exc)) from exc


def _to_jsonable(value: Any) -> Any:
    """Convert internal objects (e.g. Context) into JSON-serializable values."""
    to_dict = getattr(value, "to_dict", None)
    if callable(to_dict):
        return to_dict()
    if isinstance(value, list):
        return [_to_jsonable(item) for item in value]
    if isinstance(value, dict):
        return {k: _to_jsonable(v) for k, v in value.items()}
    return value


@router.post("")
async def create_session(
    request: CreateSessionRequest = Body(default_factory=CreateSessionRequest),
    _ctx: RequestContext = Depends(get_session_request_context),
):
    """Create a new session.

    If session_id is provided, creates a session with the given ID.
    If session_id is None, creates a new session with auto-generated ID.
    """
    service = get_service()

    update_auto_commit_policy = "auto_commit_policy" in request.model_fields_set
    auto_commit_policy_payload: Optional[Dict[str, Any]] = None
    if request.auto_commit_policy is not None:
        auto_commit_policy_payload = request.auto_commit_policy.model_dump(exclude_none=True)

    event_tags = _event_tags_from_extraction_config(request.memory_extraction_config)

    async def _create() -> dict[str, Any]:
        await service.initialize_user_directories(_ctx)
        session = await service.sessions.create(
            _ctx,
            request.session_id,
            memory_policy=request.memory_policy,
            auto_commit_policy=auto_commit_policy_payload,
            update_auto_commit_policy=update_auto_commit_policy,
            event_tags=event_tags,
        )
        return {
            "session_id": session.session_id,
            "uri": session.uri,
            "user": session.user.to_dict(),
            "auto_commit_policy": service.sessions.effective_auto_commit_policy(session),
            "memory_extraction_config": service.sessions.effective_memory_extraction_config(
                session
            ),
        }

    execution = await run_operation(
        operation="session.create",
        telemetry=request.telemetry,
        fn=_create,
    )
    return Response(status="ok", result=execution.result, telemetry=execution.telemetry)


@router.get("")
async def list_sessions(
    _ctx: RequestContext = Depends(get_session_request_context),
):
    """List all sessions."""
    service = get_service()
    result = await service.sessions.sessions(_ctx)
    return Response(status="ok", result=result)


@router.get("/{session_id}")
async def get_session(
    session_id: str = Path(..., description="Session ID"),
    auto_create: bool = Query(False, description="Create the session if it does not exist"),
    _ctx: RequestContext = Depends(get_session_request_context),
):
    """Get session details."""
    from openviking_cli.exceptions import NotFoundError

    service = get_service()
    try:
        session = await service.sessions.get(session_id, _ctx, auto_create=auto_create)
    except NotFoundError:
        return error_response("NOT_FOUND", f"Session {session_id} not found")
    result = session.meta.to_dict()
    result["uri"] = session.uri
    result["user"] = session.user.to_dict()
    result["pending_tokens"] = int(session.meta.pending_tokens or 0)
    result["auto_commit_policy"] = service.sessions.effective_auto_commit_policy(session)
    result.pop("event_search_tags", None)
    result["memory_extraction_config"] = service.sessions.effective_memory_extraction_config(
        session
    )
    return Response(status="ok", result=result)


class UpdateSessionConfigRequest(BaseModel):
    """Request body for PATCH /sessions/{id}/config.

    Only the mutable extraction config is editable. Fields left unset are not
    changed; setting ``events.tags`` to an empty list clears the default.
    """

    memory_extraction_config: Optional[MemoryExtractionConfigRequest] = None
    auto_commit_policy: Optional[AutoCommitPolicyRequest] = None
    telemetry: TelemetryRequest = False

    model_config = {"extra": "forbid"}


@router.patch("/{session_id}/config")
async def update_session_config(
    session_id: str = Path(..., description="Session ID"),
    request: UpdateSessionConfigRequest = Body(default_factory=UpdateSessionConfigRequest),
    _ctx: RequestContext = Depends(get_session_request_context),
):
    """Update mutable session config (event-memory default tags).

    Takes effect on subsequent message writes, idle scans, and commits.
    ``auto_commit_policy=null`` disables automatic commits.
    """
    from openviking_cli.exceptions import NotFoundError

    service = get_service()
    event_tags = _event_tags_from_extraction_config(request.memory_extraction_config)
    update_auto_commit_policy = "auto_commit_policy" in request.model_fields_set
    auto_commit_policy = (
        request.auto_commit_policy.model_dump(exclude_none=True)
        if request.auto_commit_policy is not None
        else None
    )

    async def _update() -> dict[str, Any]:
        session = await service.sessions.update_config(
            session_id,
            _ctx,
            event_tags=event_tags,
            auto_commit_policy=auto_commit_policy,
            update_auto_commit_policy=update_auto_commit_policy,
        )
        return {
            "session_id": session.session_id,
            "auto_commit_policy": service.sessions.effective_auto_commit_policy(session),
            "memory_extraction_config": service.sessions.effective_memory_extraction_config(
                session
            ),
        }

    try:
        execution = await run_operation(
            operation="session.update_config",
            telemetry=request.telemetry,
            fn=_update,
        )
    except NotFoundError:
        return error_response("NOT_FOUND", f"Session {session_id} not found")
    return Response(status="ok", result=execution.result, telemetry=execution.telemetry).model_dump(
        exclude_none=True
    )


@router.get("/{session_id}/tool-results")
async def list_tool_results(
    session_id: str = Path(..., description="Session ID"),
    tool_name: Optional[str] = Query(None, description="Filter by tool name"),
    limit: int = Query(50, ge=1, description="Maximum number of tool results"),
    _ctx: RequestContext = Depends(get_session_request_context),
):
    """List externalized tool results for a session."""
    service = get_service()
    session = await service.sessions.open(session_id, _ctx, auto_create=False)
    result = await session.list_tool_results(tool_name=tool_name, limit=limit)
    return Response(status="ok", result=_to_jsonable(result))


@router.get("/{session_id}/tool-results/{tool_result_id}")
async def read_tool_result(
    session_id: str = Path(..., description="Session ID"),
    tool_result_id: str = Path(..., description="Tool result ID"),
    offset: int = Query(0, ge=0, description="Unicode character offset"),
    limit: int = Query(20_000, description="Maximum Unicode characters to return"),
    include_metadata: bool = Query(True, description="Include metadata in response"),
    _ctx: RequestContext = Depends(get_session_request_context),
):
    """Read an externalized tool result by Unicode character range."""
    if limit < -1:
        return error_response(
            "INVALID_ARGUMENT",
            "limit must be -1 or greater than or equal to 0",
            details={"field": "limit", "value": limit},
        )
    service = get_service()
    session = await service.sessions.open(session_id, _ctx, auto_create=False)
    result = await session.read_tool_result(
        tool_result_id,
        offset=offset,
        limit=limit,
        include_metadata=include_metadata,
    )
    return Response(status="ok", result=_to_jsonable(result))


@router.get("/{session_id}/tool-results/{tool_result_id}/search")
async def search_tool_result(
    session_id: str = Path(..., description="Session ID"),
    tool_result_id: str = Path(..., description="Tool result ID"),
    q: str = Query(..., min_length=1, description="Search query"),
    limit: int = Query(20, ge=1, description="Maximum matches"),
    context_chars: int = Query(300, ge=0, description="Context characters around each hit"),
    _ctx: RequestContext = Depends(get_session_request_context),
):
    """Search within an externalized tool result."""
    service = get_service()
    session = await service.sessions.open(session_id, _ctx, auto_create=False)
    result = await session.search_tool_result(
        tool_result_id,
        query=q,
        limit=limit,
        context_chars=context_chars,
    )
    return Response(status="ok", result=_to_jsonable(result))


@router.get("/{session_id}/context")
async def get_session_context(
    session_id: str = Path(..., description="Session ID"),
    token_budget: int = Query(128_000, description="Token budget for session context"),
    _ctx: RequestContext = Depends(get_session_request_context),
):
    """Get assembled session context."""
    if token_budget < 0:
        return error_response(
            "INVALID_ARGUMENT",
            "token_budget must be greater than or equal to 0",
            details={"field": "token_budget", "value": token_budget},
        )

    service = get_service()
    session = await service.sessions.get(session_id, _ctx, auto_create=False)
    result = await session.get_session_context(token_budget=token_budget)
    return Response(status="ok", result=_to_jsonable(result))


@router.get("/{session_id}/archives/{archive_id}")
async def get_session_archive(
    session_id: str = Path(..., description="Session ID"),
    archive_id: str = Path(..., description="Archive ID"),
    _ctx: RequestContext = Depends(get_session_request_context),
):
    """Get one completed archive for a session."""
    from openviking_cli.exceptions import NotFoundError

    service = get_service()
    session = await service.sessions.open(session_id, _ctx, auto_create=False)
    try:
        result = await session.get_session_archive(archive_id)
    except NotFoundError:
        return error_response(code="NOT_FOUND", message=f"Archive {archive_id} not found")
    return Response(status="ok", result=_to_jsonable(result))


@router.delete("/{session_id}")
async def delete_session(
    session_id: str = Path(..., description="Session ID"),
    _ctx: RequestContext = Depends(get_session_request_context),
):
    """Delete a session."""
    service = get_service()
    await service.sessions.delete(session_id, _ctx)
    return Response(status="ok", result={"session_id": session_id})


class EventExtractionMetadataRequest(BaseModel):
    """Commit-time event-memory tag override.

    ``tags`` uses three-state semantics: unset/``None`` falls back to the
    session default, an empty list disables default-tag injection for this
    commit, and a non-empty list overrides the session default. Existing tags
    on a pre-existing URI are not removed. Normalization happens in the service
    layer, so ``None`` is preserved here (not coerced to ``[]``).
    """

    tags: Optional[List[str]] = Field(
        default=None,
        description=(
            "Custom scalar tags applied to event memories from this commit. Each "
            "element is a strict 'key=value' string. Overrides the session default; "
            "an empty list disables default-tag injection for this commit."
        ),
    )

    model_config = {"extra": "forbid"}


class ExtractionMetadataRequest(BaseModel):
    """Per-memory-type extraction overrides for a single commit."""

    event: Optional[EventExtractionMetadataRequest] = None

    model_config = {"extra": "forbid"}


class CommitRequest(BaseModel):
    """Commit request body.

    WM v2: ``keep_recent_count`` allows the plugin to retain a tail of recent
    messages in the live session after commit so the next turn still has
    immediate context. Default 0 preserves the pre-v2 "archive everything"
    behavior.
    """

    enable_working_memory: Optional[StrictBool] = Field(
        default=None,
        description="Override only Working Memory generation for this commit; null inherits policy.",
    )
    reset_context: bool = Field(
        default=False,
        strict=True,
        description="Append an empty archive boundary after archiving all messages; keep session ID.",
    )
    keep_recent_count: int = Field(
        default=0,
        ge=0,
        le=10_000,
        description=(
            "Number of most-recent messages to keep live after commit. "
            "Plugin's afterTurn path typically passes its configured value "
            "(default 10); compact path passes 0 to archive everything."
        ),
    )
    retention_mode: Optional[Literal["turn_budget"]] = Field(
        default=None,
        description=(
            "Opt in to logical Turn retention. Omit to preserve keep_recent_count semantics."
        ),
    )
    keep_recent_turn_count: Optional[int] = Field(
        default=None,
        ge=0,
        le=10_000,
        description="Maximum number of newest logical user Turns to retain.",
    )
    retained_message_token_budget: Optional[int] = Field(
        default=None,
        ge=1,
        description="Token budget for retained raw messages and checkpoint.",
    )
    min_raw_tail_steps: Optional[int] = Field(
        default=None,
        ge=0,
        le=10_000,
        description="Minimum number of latest atomic assistant Steps kept raw.",
    )
    extraction_metadata: Optional[ExtractionMetadataRequest] = Field(
        default=None,
        description=(
            "Per-commit memory extraction overrides. ``event.tags`` sets the "
            "custom scalar tags for event memories produced by this commit, "
            "overriding the session default."
        ),
    )
    telemetry: TelemetryRequest = False

    @model_validator(mode="after")
    def validate_turn_retention_opt_in(self) -> "CommitRequest":
        if self.reset_context and (self.keep_recent_count != 0 or self.retention_mode is not None):
            raise ValueError("reset_context requires keep_recent_count=0 and no retention_mode")
        if self.retention_mode is None and any(
            value is not None
            for value in (
                self.keep_recent_turn_count,
                self.retained_message_token_budget,
                self.min_raw_tail_steps,
            )
        ):
            raise ValueError(
                "retention_mode='turn_budget' is required when Turn retention fields are set"
            )
        return self


@router.post("/{session_id}/commit")
async def commit_session(
    session_id: str = Path(..., description="Session ID"),
    body: CommitRequest = Body(default_factory=CommitRequest),
    _ctx: RequestContext = Depends(get_session_request_context),
):
    """Commit a session (archive and extract memories).

    Archive (Phase 1) completes before returning.  Memory extraction
    (Phase 2) runs in the background.  A ``task_id`` is returned for
    polling progress via ``GET /tasks/{task_id}``.
    """
    service = get_service()
    commit_kwargs: Dict[str, Any] = {"keep_recent_count": body.keep_recent_count}
    optional_retention = {
        "enable_working_memory": body.enable_working_memory,
        "retention_mode": body.retention_mode,
        "keep_recent_turn_count": body.keep_recent_turn_count,
        "retained_message_token_budget": body.retained_message_token_budget,
        "min_raw_tail_steps": body.min_raw_tail_steps,
    }
    commit_kwargs.update(
        {key: value for key, value in optional_retention.items() if value is not None}
    )
    if body.reset_context:
        commit_kwargs["reset_context"] = True
    event_tags = _commit_event_tags(body.extraction_metadata)
    if event_tags is not None:
        commit_kwargs["event_tags"] = event_tags
    execution = await run_operation(
        operation="session.commit",
        telemetry=body.telemetry,
        fn=lambda: service.sessions.commit_async(
            session_id,
            _ctx,
            **commit_kwargs,
        ),
    )
    return Response(
        status="ok",
        result=execution.result,
        telemetry=execution.telemetry,
    ).model_dump(exclude_none=True)


@router.post("/{session_id}/messages")
async def add_message(
    request: AddMessageRequest,
    session_id: str = Path(..., description="Session ID"),
    _ctx: RequestContext = Depends(get_session_request_context),
):
    """Add a message to a session.

    Supports two modes:
    1. Simple mode: provide `content` string (backward compatible)
       Example: {"role": "user", "content": "Hello"}

    2. Parts mode: provide `parts` array for full Part support
       Example: {"role": "assistant", "parts": [
           {"type": "text", "text": "Here's the answer"},
           {"type": "context", "uri": "viking://resources/doc.md", "abstract": "..."}
       ]}

    If both `content` and `parts` are provided, `parts` takes precedence.
    Missing sessions are auto-created on first add.
    """
    service = get_service()

    async def _add() -> dict[str, Any]:
        session = await service.sessions.open(session_id, _ctx, auto_create=True)
        parts = _resolve_message_parts(request, _ctx)

        specs = [
            {
                "role": request.role,
                "parts": parts,
                "peer_id": request.peer_id,
                "created_at": request.created_at,
                "turn_id": request.turn_id,
                "message_kind": request.message_kind,
                "source_message_ids": request.source_message_ids,
            }
        ]
        add_many_async = getattr(session, "add_messages_async", None)
        if callable(add_many_async):
            await add_many_async(specs)
        else:
            session.add_messages(specs)
        await service.sessions.maybe_schedule_auto_commit(
            session_id,
            _ctx,
            reason_hint="message_write",
            session=session,
        )
        return {
            "session_id": session_id,
            "message_count": len(session.messages),
            # Post-write value so a commit policy can decide without a
            # follow-up get_session round trip.
            "pending_tokens": _session_pending_tokens(session),
        }

    execution = await run_operation(
        operation="session.add_message",
        telemetry=request.telemetry,
        fn=_add,
    )
    return Response(status="ok", result=execution.result, telemetry=execution.telemetry)


@router.post("/{session_id}/messages/batch")
async def batch_add_messages(
    request: BatchAddMessageRequest,
    session_id: str = Path(..., description="Session ID"),
    _ctx: RequestContext = Depends(get_session_request_context),
):
    """Add multiple messages to a session in a single request.

    Accepts a list of messages, each following the same format as AddMessageRequest.
    Missing sessions are auto-created on first add.
    """
    service = get_service()

    async def _batch_add() -> dict[str, Any]:
        session = await service.sessions.open(session_id, _ctx, auto_create=True)
        specs = []
        for msg_request in request.messages:
            parts = _resolve_message_parts(msg_request, _ctx)
            specs.append(
                {
                    "role": msg_request.role,
                    "parts": parts,
                    "peer_id": msg_request.peer_id,
                    "created_at": msg_request.created_at,
                    "turn_id": msg_request.turn_id,
                    "message_kind": msg_request.message_kind,
                    "source_message_ids": msg_request.source_message_ids,
                }
            )
        add_many_async = getattr(session, "add_messages_async", None)
        if callable(add_many_async):
            msgs = await add_many_async(specs)
        else:
            msgs = session.add_messages(specs)
        await service.sessions.maybe_schedule_auto_commit(
            session_id,
            _ctx,
            reason_hint="message_write",
            session=session,
        )
        return {
            "session_id": session_id,
            "message_count": len(session.messages),
            "added": len(msgs),
            # Post-write value so a commit policy can decide without a
            # follow-up get_session round trip.
            "pending_tokens": _session_pending_tokens(session),
        }

    execution = await run_operation(
        operation="session.batch_add_messages",
        telemetry=request.telemetry,
        fn=_batch_add,
    )
    return Response(status="ok", result=execution.result, telemetry=execution.telemetry)