Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

9.3 KB
Raw Blame
"""Business API for the ``agent_sessions`` table.

This module is the **only** import path that UI server / CLI / IM adapter
should use to read or write agent-session rows. Today it re-exports the
existing storage-level helpers; later phases will fold the per-caller
duplication (``storage.workbench_sessions_service`` vs
``storage.sessions_service.SQLiteSessionsService``) into a single set of
free functions here.

Why the early re-export shim:

* Lets callers move onto ``core.services.sessions`` immediately (UI server
  in C1, CLI in C2) without forcing a behavior-affecting rewrite in the
  same commit.
* Pins the public surface so future internal refactors don't ripple into
  every consumer.
* The contract tests in ``tests/test_core_services_sessions.py`` lock
  the shape so a future internal change cannot silently drift the API.

Conventions (see workbench-dispatch-architecture.md §6):

* Public functions take a SQLAlchemy ``Connection`` as their first
  argument. Never construct engines here.
* Return shapes are plain ``dict[str, Any]`` payloads (matching the
  existing ``workbench_sessions_service`` style).
* Errors raise ``LookupError`` / ``ValueError`` so callers can map them
  to HTTP status codes or CLI exit codes without leaking SQLAlchemy
  exceptions.
* No side effects. SSE publishes, audit logs, etc. belong in the calling
  layer (REST route, CLI command, controller handler).
"""

from __future__ import annotations

from pathlib import Path
from typing import Any, Optional

from config import paths
from storage.workbench_sessions_service import (
    ProjectAccessDeniedError,
    ReservedSessionError,
    SessionArchivedError,
    SessionBackendLockedError,
    archive_session,
    backfill_session_title,
    count_bound_resources,
    create_session,
    derive_backend_for_agent_name,
    get_active_session,
    get_session,
    is_session_archived,
    latest_session_turn_id,
    list_sessions,
    list_sessions_page,
    require_enabled_agent_backend,
    require_enabled_agent_identity,
    require_session_chat_access,
    require_session_turn_authority,
    set_agent_status,
    touch_session,
    touch_session_agent_activity,
    update_session,
)
from vibe.i18n import t as i18n_t

__all__ = [
    "ProjectAccessDeniedError",
    "SESSION_ARCHIVED_I18N_KEY",
    "ReservedSessionError",
    "SessionArchivedError",
    "SessionBackendLockedError",
    "archive_session",
    "backfill_session_title",
    "count_bound_resources",
    "create_session",
    "derive_backend_for_agent_name",
    "get_active_session",
    "get_session",
    "is_session_archived",
    "latest_session_turn_id",
    "list_sessions",
    "list_sessions_page",
    "require_session_chat_access",
    "require_session_placement_authority",
    "require_session_turn_authority",
    "set_agent_status",
    "session_archived_message",
    "touch_session",
    "touch_session_agent_activity",
    "update_session",
    "reserve_agent_session",
    "reserve_standalone_agent_session",
]


# --- Localized copy for the terminal-archive refusal ------------------
#
# ``SessionArchivedError`` carries a developer-facing sentence (it names the
# session id), but the ``message`` a route puts in its 409 body is USER-visible:
# direct API/CLI consumers read it verbatim, and a Web UI client that lacks the
# ``errors.session_archived`` translation renders it as the fallback. So it has to
# come from ``vibe/i18n`` rather than an English literal at the route (AGENTS.md
# §6). Shaped exactly like ``core.show_session_events.localized_show_event_error``:
# a module-level key constant beside the error it describes (so the parity guard in
# ``tests/test_i18n_backend_keys.py`` can pin it) plus a factory that resolves the
# user's configured language and degrades to English if the config is unreadable.
SESSION_ARCHIVED_I18N_KEY = "error.sessionArchived"


def session_archived_message(lang: Optional[str] = None) -> str:
    """User-facing copy for a write refused because the session is archived.

    ``lang`` defaults to the configured UI language; an unreadable/missing config
    (a brand-new install, a partially-written file) falls back to English rather
    than failing the response.
    """

    if not lang:
        from config.v2_config import V2Config

        try:
            lang = V2Config.load().language
        except Exception:
            lang = "en"
    return i18n_t(SESSION_ARCHIVED_I18N_KEY, lang)


# --- Reservation helpers (IM-style scope_key + session_anchor) --------
#
# These wrap the legacy ``SQLiteSessionsService`` methods so the CLI and
# scheduled-task / hook flows can move off the storage class without a
# behavior-change in the same commit. Each call opens its own short-lived
# service instance so the caller does not have to manage close().
#
# Later phases will fold the per-instance engine ownership into a shared
# connection lifecycle, but for now the public free-function shape is
# what callers commit to.


def _ensure_cli_sqlite_state() -> None:
    """Make sure the SQLite database exists and is migrated.

    Mirrors ``vibe.cli._ensure_cli_sqlite_state`` so the service can be
    invoked from any process (CLI, controller, future internal RPC)
    without relying on a caller-side bootstrap. Safe to call repeatedly;
    ``ensure_sqlite_state`` is idempotent.
    """

    from storage.importer import ensure_sqlite_state, resolve_primary_platform_from_config

    ensure_sqlite_state(primary_platform=resolve_primary_platform_from_config(paths.get_state_dir()))


def _open_legacy_service(db_path: Optional[Path] = None):
    """Construct the engine-owning ``SQLiteSessionsService`` exactly once
    per call. Internal — never expose this class to callers.
    """

    from storage.sessions_service import SQLiteSessionsService

    _ensure_cli_sqlite_state()
    return SQLiteSessionsService(db_path or paths.get_sqlite_state_path())


def reserve_agent_session(
    *,
    scope_key: str,
    agent_backend: str,
    session_anchor: str,
    agent_id: Optional[str] = None,
    agent_name: Optional[str] = None,
    model: Optional[str] = None,
    reasoning_effort: Optional[str] = None,
    workdir: Optional[str] = None,
    visibility: str = "foreground",
    metadata: Optional[dict] = None,
    db_path: Optional[Path] = None,
    require_enabled_agent: bool = False,
    expected_reference_agent_id: Optional[str] = None,
    authorization_context: Any = None,
) -> Optional[str]:
    """Reserve a new ``agent_sessions`` row keyed by an IM-style scope.

    Returns the new session id or ``None`` if the underlying service
    refuses (e.g. scope key cannot be resolved). Matches the existing
    ``SQLiteSessionsService.reserve_agent_session`` contract.
    """

    service = _open_legacy_service(db_path)
    try:
        return service.reserve_agent_session(
            scope_key=scope_key,
            agent_backend=agent_backend,
            session_anchor=session_anchor,
            agent_id=agent_id,
            agent_name=agent_name,
            model=model,
            reasoning_effort=reasoning_effort,
            workdir=workdir,
            visibility=visibility,
            metadata=metadata,
            require_enabled_agent=require_enabled_agent,
            expected_reference_agent_id=expected_reference_agent_id,
            authorization_context=authorization_context,
        )
    finally:
        service.close()


def require_session_placement_authority(
    *,
    scope_key: str,
    agent_id: Optional[str] = None,
    agent_name: Optional[str] = None,
    db_path: Optional[Path] = None,
    authorization_context: Any = None,
) -> None:
    """Admit where a stored definition will put the Sessions it has not created yet.

    The reservation paths answer this as they reserve. A definition that creates one
    Session per run has no reservation to answer it at, so it asks here — before the
    row that would carry the placement into every future fire.
    """

    service = _open_legacy_service(db_path)
    try:
        service.require_placement_access(
            scope_key=scope_key,
            agent_id=agent_id,
            agent_name=agent_name,
            authorization_context=authorization_context,
        )
    finally:
        service.close()


def reserve_standalone_agent_session(
    *,
    agent_backend: str,
    session_anchor: str,
    agent_id: Optional[str] = None,
    agent_name: Optional[str] = None,
    model: Optional[str] = None,
    reasoning_effort: Optional[str] = None,
    workdir: Optional[str] = None,
    visibility: str = "background",
    metadata: Optional[dict] = None,
    db_path: Optional[Path] = None,
    require_enabled_agent: bool = False,
    expected_reference_agent_id: Optional[str] = None,
    authorization_context: Any = None,
) -> Optional[str]:
    """Reserve a background-capable session with no Scope."""

    service = _open_legacy_service(db_path)
    try:
        return service.reserve_standalone_agent_session(
            agent_backend=agent_backend,
            session_anchor=session_anchor,
            agent_id=agent_id,
            agent_name=agent_name,
            model=model,
            reasoning_effort=reasoning_effort,
            workdir=workdir,
            visibility=visibility,
            metadata=metadata,
            require_enabled_agent=require_enabled_agent,
            expected_reference_agent_id=expected_reference_agent_id,
            authorization_context=authorization_context,
        )
    finally:
        service.close()