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.

24.4 KB
Raw Blame
"""Avibe caller-context contract for Agent-initiated Harness calls."""

from __future__ import annotations

from dataclasses import dataclass, replace
import json
import os
from typing import Any, Mapping, Optional

AVIBE_SESSION_ID_ENV = "AVIBE_SESSION_ID"
AVIBE_RUN_ID_ENV = "AVIBE_RUN_ID"
AVIBE_CALLER_SOURCE_ENV = "AVIBE_CALLER_SOURCE"
AVIBE_CALLER_BACKEND_ENV = "AVIBE_CALLER_BACKEND"
AVIBE_NATIVE_SESSION_ID_ENV = "AVIBE_NATIVE_SESSION_ID"
#: The CREATION ORIGIN half of the contract. Everything below travels the same
#: subprocess hop as the ids above, because an IM-created definition is created by an
#: Agent run executing ``vibe task add`` — the env is the only channel between the
#: conversation that asked for the definition and the row that records who asked.
AVIBE_CALLER_PLATFORM_ENV = "AVIBE_CALLER_PLATFORM"
AVIBE_CALLER_USER_ID_ENV = "AVIBE_CALLER_USER_ID"
AVIBE_CALLER_CHANNEL_ID_ENV = "AVIBE_CALLER_CHANNEL_ID"
AVIBE_CALLER_SESSION_KEY_ENV = "AVIBE_CALLER_SESSION_KEY"
AVIBE_CALLER_MESSAGE_ID_ENV = "AVIBE_CALLER_MESSAGE_ID"
AVIBE_CALLER_WORKSPACE_ID_ENV = "AVIBE_CALLER_WORKSPACE_ID"
AVIBE_CALLER_REMOTE_ENV = "AVIBE_CALLER_REMOTE"
AVIBE_CALLER_RESOURCE_CONTEXT_ENV = "AVIBE_CALLER_RESOURCE_CONTEXT"

CALLER_CONTEXT_ENV_NAMES = frozenset(
    {
        AVIBE_SESSION_ID_ENV,
        AVIBE_RUN_ID_ENV,
        AVIBE_CALLER_SOURCE_ENV,
        AVIBE_CALLER_BACKEND_ENV,
        AVIBE_NATIVE_SESSION_ID_ENV,
        AVIBE_CALLER_PLATFORM_ENV,
        AVIBE_CALLER_USER_ID_ENV,
        AVIBE_CALLER_CHANNEL_ID_ENV,
        AVIBE_CALLER_SESSION_KEY_ENV,
        AVIBE_CALLER_MESSAGE_ID_ENV,
        AVIBE_CALLER_WORKSPACE_ID_ENV,
        AVIBE_CALLER_REMOTE_ENV,
        AVIBE_CALLER_RESOURCE_CONTEXT_ENV,
    }
)

_RESOURCE_USER_CONTEXT_METADATA_KEY = "resource_user_context"


@dataclass(frozen=True)
class CallerContext:
    """Caller identity resolved from Avibe-owned execution context.

    The identity fields answer "which Avibe Session, Turn, and Run made this
    call". The ORIGIN fields below answer "where in the user's world was it
    made", which is a different question and has to be captured separately: a
    failure notice is context-free by construction (it may be delivered to an
    owner DM or to the workspace inbox hours later), so it can only name the
    channel and thread the definition came from if the creating turn wrote them
    down.

    ``session_key`` and ``channel_id`` are BOTH kept, and are not redundant:

    * ``session_key`` is the ADDRESS — the
      ``<platform>::<channel|user>::<id>[::thread::<ts>]`` grammar
      ``parse_session_key`` speaks, and the one a notice rung can be delivered to;
    * ``channel_id`` is the LOCATION — what a message permalink needs. For a DM the
      session key's scope id is the USER id, and a permalink built from it would be
      fabricated (Slack DM permalinks are keyed by the ``D…`` conversation).

    ``workspace_id`` is one generic field rather than one per platform: it holds a
    Slack team id or a Discord guild id, both of which are the enclosing tenant a
    deep link must name.
    """

    session_id: str
    run_id: Optional[str] = None
    turn_id: Optional[str] = None
    source: Optional[str] = None
    backend: Optional[str] = None
    native_session_id: Optional[str] = None
    platform: Optional[str] = None
    user_id: Optional[str] = None
    channel_id: Optional[str] = None
    session_key: Optional[str] = None
    message_id: Optional[str] = None
    workspace_id: Optional[str] = None
    is_remote: bool = False
    resource_user_context: Optional[Mapping[str, Any]] = None

    def session_stable(self) -> "CallerContext":
        """This context minus every origin field that changes from turn to turn.

        For a backend whose caller env is written ONCE — the Claude SDK client is spawned
        per session and its environment cannot be refreshed afterwards — the per-message
        fields are not merely useless, they are dangerous:

        * ``turn_id`` changes on every Turn and is kept in the in-process context
          only; it is never exported as a subprocess credential;
        * ``message_id`` changes on every message, so keeping it in the comparison that
          decides whether a cached client is still valid would tear down and respawn the
          Agent on EVERY turn;
        * ``user_id`` changes with the author, and a shared channel session is
          deliberately shared across participants (pinned by
          ``test_session_handler_reuses_cached_claude_client_when_system_prompt_is_unchanged``,
          which also asserts the per-user id never reaches the system prompt). A baked-in
          author id would attribute a definition created by one participant to whoever
          happened to speak first — and the owner-DM rung would then notify the wrong
          person, which is worse than not notifying anybody.

        What survives is what the SESSION owns: platform, channel, session key,
        workspace. A trusted remote Workbench authorization snapshot also survives:
        unlike an IM author id, it is required to authorize any CLI resource write.
        When that snapshot changes the Claude cache comparison deliberately recreates
        the client, so one remote user's ACL can never be reused for another. Thus a
        Claude-created definition still names its conversation and remote authority,
        while ordinary IM sessions get no owner-DM rung or deep link. Codex and
        OpenCode rewrite their caller env per turn and keep the full origin.

        A DM is the case where nothing is lost: its session key is
        ``<platform>::user::<id>``, so the person is carried by the scope itself.
        """

        if not self.user_id and not self.message_id and not self.turn_id:
            return self
        return replace(self, turn_id=None, user_id=None, message_id=None)

    def to_env(self) -> dict[str, str]:
        env = {AVIBE_SESSION_ID_ENV: self.session_id}
        if self.run_id:
            env[AVIBE_RUN_ID_ENV] = self.run_id
        if self.source:
            env[AVIBE_CALLER_SOURCE_ENV] = self.source
        if self.backend:
            env[AVIBE_CALLER_BACKEND_ENV] = self.backend
        if self.native_session_id:
            env[AVIBE_NATIVE_SESSION_ID_ENV] = self.native_session_id
        if self.platform:
            env[AVIBE_CALLER_PLATFORM_ENV] = self.platform
        if self.user_id:
            env[AVIBE_CALLER_USER_ID_ENV] = self.user_id
        if self.channel_id:
            env[AVIBE_CALLER_CHANNEL_ID_ENV] = self.channel_id
        if self.session_key:
            env[AVIBE_CALLER_SESSION_KEY_ENV] = self.session_key
        if self.message_id:
            env[AVIBE_CALLER_MESSAGE_ID_ENV] = self.message_id
        if self.workspace_id:
            env[AVIBE_CALLER_WORKSPACE_ID_ENV] = self.workspace_id
        if self.is_remote:
            env[AVIBE_CALLER_REMOTE_ENV] = "1"
            if self.resource_user_context is not None:
                env[AVIBE_CALLER_RESOURCE_CONTEXT_ENV] = json.dumps(
                    dict(self.resource_user_context),
                    separators=(",", ":"),
                    sort_keys=True,
                )
        return env

    def to_metadata(self) -> dict[str, str]:
        """The ``created_by.caller`` shape persisted with a definition.

        The origin key NAMES are load-bearing: ``core/scheduled_tasks.py``'s failure
        ladder has always read ``caller["session_key"]`` / ``caller["scope_id"]``
        (rung 3) and ``caller["platform"]`` / ``caller["user_id"]`` (rung 4, the owner
        DM) — fields nothing had ever written, so both rungs were dormant. Writing
        them under any other name would leave them dormant.
        """

        metadata = {"session_id": self.session_id}
        if self.run_id:
            metadata["run_id"] = self.run_id
        if self.source:
            metadata["source"] = self.source
        if self.backend:
            metadata["backend"] = self.backend
        if self.native_session_id:
            metadata["native_session_id"] = self.native_session_id
        if self.platform:
            metadata["platform"] = self.platform
        if self.user_id:
            metadata["user_id"] = self.user_id
        if self.channel_id:
            metadata["channel_id"] = self.channel_id
        if self.session_key:
            metadata["session_key"] = self.session_key
            # ``scope_id`` only when it says something the session key does not: rung 3
            # reads ``session_key or scope_id``, so a copy of the same value would be
            # dead weight. A THREAD key's parent scope is the exception — it is the
            # coarser address a consumer that cannot deliver into a thread still wants,
            # and ``parse_scope_id`` cannot express the five-part form.
            scope_id = _scope_id_from_session_key(self.session_key)
            if scope_id:
                metadata["scope_id"] = scope_id
        if self.message_id:
            metadata["message_id"] = self.message_id
        if self.workspace_id:
            metadata["workspace_id"] = self.workspace_id
        return metadata


def _clean(value: object) -> str:
    return str(value or "").strip()


def _resource_context_from_env(source: Mapping[str, str]) -> Optional[dict[str, Any]]:
    raw = _clean(source.get(AVIBE_CALLER_RESOURCE_CONTEXT_ENV))
    if not raw:
        return None
    try:
        parsed = json.loads(raw)
    except (TypeError, ValueError, json.JSONDecodeError):
        return None
    return dict(parsed) if isinstance(parsed, dict) else None


def env_declares_remote_caller(env: Mapping[str, str] | None = None) -> bool:
    """True when the invocation env declares a remote caller.

    Read on its own because :func:`caller_context_from_env` answers ``None`` for a
    missing session id, before it ever looks at this flag. An entry point that has
    to tell a genuinely local invocation from a declared-remote one whose
    provenance is incomplete needs the declaration itself.
    """

    source = env if env is not None else os.environ
    return _clean(source.get(AVIBE_CALLER_REMOTE_ENV)).lower() in {"1", "true"}


def caller_resource_user_context(context: Optional[CallerContext]) -> Optional[Mapping[str, Any]]:
    """Return explicit remote ACL context for a CLI write.

    ``None`` is reserved for a genuinely local caller. A remote Agent invocation
    with missing or malformed authorization provenance returns an empty mapping,
    which resource services parse as an anonymous remote context and reject.
    """

    if context is None or not context.is_remote:
        return None
    return dict(context.resource_user_context or {})


def caller_resource_user_context_from_env(
    env: Mapping[str, str] | None = None,
) -> Optional[Mapping[str, Any]]:
    """Read remote authority independently of a callback Session binding.

    A scheduled command can carry remote authorization without an Agent Session.
    Missing or malformed declared-remote provenance still fails closed.
    """

    source = os.environ if env is None else env
    if not env_declares_remote_caller(source):
        return None
    return _resource_context_from_env(source) or {}


def environment_without_caller_context(env: Optional[Mapping[str, str]] = None) -> dict[str, str]:
    """Return ``env`` with this invocation's caller provenance removed.

    Avibe hands a caller's identity to a subprocess it runs ON that caller's
    behalf — an Agent turn, a backend, a Harness call — and that hop is the whole
    point of the contract above. A process Avibe itself owns is the opposite
    case: the restart supervisor, a deferred activation, the service and the UI
    server outlive the call that scheduled them and act as the installation, not
    as whoever pressed the button. Inheriting the scheduling caller there would
    make an independently owned process run under an authority nobody granted it
    — and its own entry point, which is Owner work, would refuse it.

    Strip at the boundary where the independent process is created, after the
    scheduling operation has already been admitted on its own merits. ``None``
    means "the current environment", and is materialized rather than passed on:
    a spawn that inherits implicitly would inherit the caller too.
    """

    source = os.environ if env is None else env
    return {
        key: value for key, value in source.items()
        if key not in CALLER_CONTEXT_ENV_NAMES
    }


def background_command_env(
    *,
    session_id: str | None,
    source: str,
    metadata: Mapping[str, Any],
    run_id: str | None = None,
) -> dict[str, str]:
    """Replace service caller provenance with this definition's execution facts.

    A command is not the human turn that created its definition. Its current
    binding owns CLI defaults and callbacks; creator metadata is not a fallback.
    Only the definition's resource snapshot carries remote authority, rechecked
    by runtime admission and the CLI.
    """

    env = environment_without_caller_context()
    env[AVIBE_CALLER_SOURCE_ENV] = source
    if session_id:
        env[AVIBE_SESSION_ID_ENV] = session_id
    if run_id:
        env[AVIBE_RUN_ID_ENV] = run_id
    snapshot = metadata.get(_RESOURCE_USER_CONTEXT_METADATA_KEY)
    if isinstance(snapshot, Mapping):
        env[AVIBE_CALLER_REMOTE_ENV] = "1"
        env[AVIBE_CALLER_RESOURCE_CONTEXT_ENV] = json.dumps(dict(snapshot), separators=(",", ":"), sort_keys=True)
    return env


def validated_caller_env_snapshot(source: object) -> dict[str, str]:
    """Return only caller-context fields from a persisted internal snapshot."""

    if not isinstance(source, Mapping):
        return {}
    return {
        str(key): value
        for key, value in source.items()
        if key in CALLER_CONTEXT_ENV_NAMES and isinstance(value, str) and value
    }


def _scope_id_from_session_key(session_key: str) -> Optional[str]:
    parts = _clean(session_key).split("::")
    if len(parts) != 5:
        return None
    return "::".join(parts[:3])


def _harness_resource_context(
    source: str, platform: str, user_id: str, message_metadata: object,
) -> Optional[dict[str, Any]]:
    """Recover durable remote authority for synthetic Harness turns.

    Avibe Harness authors are synthetic (normally ``scheduled``), so matching
    ``message.user_id`` cannot identify the Workbench editor who created the
    definition.  Only the persisted resource snapshot is an authority source;
    malformed snapshots become an anonymous remote caller and are rejected by
    the existing ACL checks rather than falling back to local Owner authority.
    """

    if (
        platform != "avibe"
        or user_id != "scheduled"
        or not isinstance(message_metadata, Mapping)
    ):
        return None
    if _RESOURCE_USER_CONTEXT_METADATA_KEY not in message_metadata:
        return None
    snapshot = message_metadata.get(_RESOURCE_USER_CONTEXT_METADATA_KEY)
    if not isinstance(snapshot, Mapping):
        return {}
    subject = _clean(snapshot.get("sub"))
    if not subject:
        return {}
    return dict(snapshot)


def _origin_thread_id(
    context_platform: str,
    payload: Mapping[str, object] | None,
    thread_id: object,
    *,
    is_dm: bool,
) -> Optional[str]:
    """The thread segment of the origin session key.

    Mirrors ``build_session_key_for_context(..., include_thread=True)`` —
    ``resolve_context_thread_id(context) or context.thread_id`` — which is pinned by
    ``test_the_captured_origin_session_key_matches_the_canonical_builder`` rather than
    imported, so this module keeps no dependency on ``modules.im`` and stays cheap
    enough for the CLI to import.

    *context_platform* is deliberately the platform WITHOUT the caller's fallback, which
    is the one asymmetry in that mirror: ``build_session_key_for_context`` passes its
    ``fallback_platform`` to ``resolve_context_platform`` for the key's prefix but calls
    ``resolve_context_thread_id`` with no fallback at all. Applying the fallback here
    would canonicalise a Telegram forum thread the canonical builder would have left
    off, i.e. address rung (3) at a conversation the rest of the system does not believe
    in. The asymmetry is invisible in production — the Telegram adapter always sets
    ``context.platform``, and only Slack leaves it unset — but it is the exact case
    ``test_the_captured_origin_session_key_matches_the_canonical_builder`` caught.
    """

    canonical: Optional[str] = None
    if context_platform == "telegram" and not is_dm:
        data = payload or {}
        if _clean(thread_id):
            canonical = _clean(thread_id)
        elif data.get("is_forum") or data.get("is_topic_message"):
            canonical = "1"
    return canonical or (_clean(thread_id) or None)


def _origin_session_key(
    platform: str,
    payload: Mapping[str, object] | None,
    *,
    context_platform: str,
    user_id: str,
    channel_id: str,
    thread_id: object,
) -> Optional[str]:
    if not platform:
        return None
    is_dm = bool((payload or {}).get("is_dm", False))
    scope_type = "user" if is_dm else "channel"
    scope_id = user_id if is_dm else channel_id
    if not scope_id:
        return None
    base = f"{platform}::{scope_type}::{scope_id}"
    thread = _origin_thread_id(context_platform, payload, thread_id, is_dm=is_dm)
    return f"{base}::thread::{thread}" if thread else base


def _origin_workspace_id(platform: str, payload: Mapping[str, object] | None) -> Optional[str]:
    """The enclosing tenant, read from whatever the adapter already put on the payload.

    Defensive by design, and deliberately read-only: no ``modules/im`` adapter is
    changed to feed this. Slack event payloads carry ``team_id``; a Discord payload
    carries either the raw ``discord.Message`` or ``discord.Interaction``; both expose
    ``guild``, which is ``None`` in a DM. Every other platform has no tenant id here,
    which is a MISSING id, not an empty one — the deep-link builder must refuse rather
    than invent one.
    """

    if not payload:
        return None
    if platform == "slack":
        return _clean(payload.get("team_id")) or None
    if platform == "discord":
        origin = payload.get("message")
        if origin is None:
            origin = payload.get("interaction")
        guild = getattr(origin, "guild", None)
        return _clean(getattr(guild, "id", None)) or None
    return None


def caller_context_from_env(env: Mapping[str, str] | None = None) -> Optional[CallerContext]:
    """Resolve caller context from process env.

    The raw session id is authoritative only when Avibe injected it into an
    Agent subprocess. If it is absent, callers should fail or require explicit
    flags instead of guessing from native backend ids.
    """

    source = env if env is not None else os.environ
    session_id = _clean(source.get(AVIBE_SESSION_ID_ENV))
    if not session_id:
        return None
    return CallerContext(
        session_id=session_id,
        run_id=_clean(source.get(AVIBE_RUN_ID_ENV)) or None,
        source=_clean(source.get(AVIBE_CALLER_SOURCE_ENV)) or None,
        backend=_clean(source.get(AVIBE_CALLER_BACKEND_ENV)) or None,
        native_session_id=_clean(source.get(AVIBE_NATIVE_SESSION_ID_ENV)) or None,
        platform=_clean(source.get(AVIBE_CALLER_PLATFORM_ENV)) or None,
        user_id=_clean(source.get(AVIBE_CALLER_USER_ID_ENV)) or None,
        channel_id=_clean(source.get(AVIBE_CALLER_CHANNEL_ID_ENV)) or None,
        session_key=_clean(source.get(AVIBE_CALLER_SESSION_KEY_ENV)) or None,
        message_id=_clean(source.get(AVIBE_CALLER_MESSAGE_ID_ENV)) or None,
        workspace_id=_clean(source.get(AVIBE_CALLER_WORKSPACE_ID_ENV)) or None,
        is_remote=env_declares_remote_caller(source),
        resource_user_context=_resource_context_from_env(source),
    )


def caller_context_from_platform_payload(
    payload: Mapping[str, object] | None,
    *,
    message: object | None = None,
    fallback_platform: object | None = None,
) -> Optional[CallerContext]:
    """Resolve caller context from an Avibe message/turn payload.

    *message* is the turn's typed ``MessageContext`` (duck-typed here so this module
    stays importable by the CLI without pulling in ``modules.im``). Without it the
    context carries identity only and NO origin — which is exactly right for a caller
    that has no conversation behind it, and is why every existing caller keeps its
    previous env and metadata byte for byte.
    """

    if not payload and message is None:
        return None
    payload = payload or {}
    target = payload.get("agent_session_target")
    session_id = ""
    backend = ""
    native_session_id = ""
    if isinstance(target, Mapping):
        session_id = _clean(target.get("id"))
        backend = _clean(target.get("agent_backend") or target.get("backend"))
        native_session_id = _clean(target.get("native_session_id"))
    session_id = session_id or _clean(payload.get("agent_session_id"))
    if not session_id:
        return None
    run_id = _clean(payload.get("task_execution_id"))
    turn_id = _clean(payload.get("turn_token"))
    source_kind = _clean(payload.get("source_kind"))
    trigger_kind = _clean(payload.get("task_trigger_kind"))
    source = source_kind if source_kind == "callback" else trigger_kind or source_kind or "agent_turn"
    backend = backend or _clean(payload.get("vibe_agent_backend"))

    platform = ""
    user_id = ""
    channel_id = ""
    message_id = ""
    session_key: Optional[str] = None
    workspace_id: Optional[str] = None
    if message is not None:
        context_platform = _clean(getattr(message, "platform", None)) or _clean(payload.get("platform"))
        platform = context_platform or _clean(fallback_platform)
        user_id = _clean(getattr(message, "user_id", None))
        channel_id = _clean(getattr(message, "channel_id", None))
        message_id = _clean(getattr(message, "message_id", None))
        session_key = _origin_session_key(
            platform,
            payload,
            context_platform=context_platform,
            user_id=user_id,
            channel_id=channel_id,
            thread_id=getattr(message, "thread_id", None),
        )
        workspace_id = _origin_workspace_id(platform, payload)

    message_metadata = payload.get("message_metadata")
    authorization_user_id = user_id
    is_remote = platform == "avibe" and authorization_user_id.startswith("remote:")
    resource_user_context: Optional[dict[str, Any]] = None
    if is_remote and isinstance(message_metadata, Mapping):
        raw_resource_context = message_metadata.get(_RESOURCE_USER_CONTEXT_METADATA_KEY)
        if isinstance(raw_resource_context, Mapping):
            subject = _clean(raw_resource_context.get("sub"))
            if subject and authorization_user_id == f"remote:{subject}":
                resource_user_context = dict(raw_resource_context)

    harness_resource_context = _harness_resource_context(
        source, platform, user_id, message_metadata
    )
    if harness_resource_context is not None:
        # Keep ``is_remote`` true even for an invalid snapshot.  An empty remote
        # context fails closed in resource ACLs; treating it as local would grant
        # the installation Owner authority to a deferred command.
        is_remote = True
        resource_user_context = harness_resource_context

    return CallerContext(
        session_id=session_id,
        run_id=run_id or None,
        turn_id=turn_id or None,
        source=source or None,
        backend=backend or None,
        native_session_id=native_session_id or None,
        platform=platform or None,
        user_id=user_id or None,
        channel_id=channel_id or None,
        session_key=session_key,
        message_id=message_id or None,
        workspace_id=workspace_id,
        is_remote=is_remote,
        resource_user_context=resource_user_context,
    )


def caller_env_for_platform_payload(
    payload: Mapping[str, object] | None,
    *,
    message: object | None = None,
    fallback_platform: object | None = None,
    session_stable_only: bool = False,
) -> dict[str, str]:
    """The caller env for an Agent subprocess.

    Set *session_stable_only* when the env is written once for the whole session and
    cannot be refreshed per turn — see ``CallerContext.session_stable`` for what that
    drops and why keeping it would be worse than losing it.
    """

    context = caller_context_from_platform_payload(
        payload,
        message=message,
        fallback_platform=fallback_platform,
    )
    if context is None:
        return {}
    if session_stable_only:
        context = context.session_stable()
    return context.to_env()