Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
# 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)