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.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
"""One admission entry for every input that reaches an Avibe Session.
Every input source (the Web composer, IM, Harness triggers, Show annotations, a
failure retry, and an agent-initiated Turn) normalizes its input into one
``InputEnvelope`` and admits it here. The entry asks the admission policy for
the input's priority, records which policy decided and why on the Delivery's
admission history event, and persists the reserved Delivery.
Everything after that is unchanged and owned elsewhere: P0/P1/P3 admission in
``SessionTurnManager.deliver``, steering, the FIFO, segment merging, and the
dedupe identity each source supplies.
The policy is the seam for an agent-owned input firewall and a mailbox. Only the
default policy exists; it holds each source's released priority. Another policy
replaces it by implementing ``AdmissionPolicy``, or composes with it by
delegating to it.
"""
from __future__ import annotations
from dataclasses import dataclass
from typing import Any, Literal, Mapping, Protocol
from sqlalchemy.engine import Connection
from core.message_priority import (
DeliveryIntent,
DeliveryPriority,
delivery_intent_for_trigger,
normalize_delivery_intent,
priority_for_delivery_intent,
)
from storage import message_deliveries
InputSource = Literal[
"web_composer",
"im",
"harness",
"show_annotation",
"failure_retry",
"agent_initiated",
]
@dataclass(frozen=True)
class InputSender:
"""Who sent the input.
``kind`` is the transcript author (``user`` or ``harness``); ``id`` and
``name`` are the identity the transcript shows for it.
"""
kind: str
id: str | None = None
name: str | None = None
@dataclass(frozen=True)
class InputProvenance:
"""Where the input came from."""
source: InputSource
platform: str = "avibe"
#: The transcript ``source`` column (``user`` or ``harness``).
origin: str = "user"
native_message_id: str | None = None
parent_native_message_id: str | None = None
#: The Harness trigger kind (``scheduled``, ``watch``, ``agent_run``, ...).
trigger: str | None = None
@dataclass(frozen=True)
class InputEnvelope:
"""One input, normalized, before any admission decision."""
session_id: str
scope_id: str | None
sender: InputSender
#: The Message type the input is recorded as (``user``, ``harness``,
#: ``annotation``, ``agent_initiated``).
kind: str
provenance: InputProvenance
#: The prompt the agent receives.
dispatch_text: str = ""
#: The text the transcript shows.
text: str | None = None
#: The Message content, attachments included.
content: dict[str, Any] | None = None
metadata: dict[str, Any] | None = None
#: How a person produced it (``original``, ``quick_reply``, ...).
message_kind: str | None = None
#: An explicit request from the sender (``queue``, ``steer``, legacy
#: ``send_now``), or ``None`` to take the source's default.
requested_intent: str | None = None
#: The backend the input is routed to, and the native subagent an IM input
#: named with an explicit prefix.
backend: str | None = None
subagent: str | None = None
@property
def attachments(self) -> list[dict[str, Any]]:
return list((self.content or {}).get("attachments") or [])
def snapshot(self) -> dict[str, Any]:
"""The immutable Message candidate the Delivery holds."""
return message_deliveries.message_snapshot(
scope_id=self.scope_id,
session_id=self.session_id,
platform=self.provenance.platform,
author=self.sender.kind,
source=self.provenance.origin,
message_type=self.kind,
text=self.text,
content=self.content,
metadata=self.metadata,
author_id=self.sender.id,
author_name=self.sender.name,
native_message_id=self.provenance.native_message_id,
parent_native_message_id=self.provenance.parent_native_message_id,
message_kind=self.message_kind,
)
@dataclass(frozen=True)
class AdmissionDecision:
intent: DeliveryIntent
policy: str
reason: str
@property
def priority(self) -> DeliveryPriority:
return priority_for_delivery_intent(self.intent)
def record(self) -> dict[str, str]:
"""Who decided and why, as recorded in the Delivery history."""
return {"id": self.policy, "reason": self.reason}
class AdmissionPolicy(Protocol):
def decide(self, envelope: InputEnvelope) -> AdmissionDecision: ...
class DefaultAdmissionPolicy:
"""Each source's released priority."""
id = "default"
def decide(self, envelope: InputEnvelope) -> AdmissionDecision:
source = envelope.provenance.source
if source == "harness":
return self._decide_harness(envelope)
if source == "im":
if envelope.backend == "opencode" and envelope.subagent:
# OpenCode subagents share the main Session anchor. They need a
# fresh Turn so the persisted route can select the requested
# native subagent instead of text-steering the active main Turn.
return self._decision("queue", "opencode_subagent")
return self._decision(delivery_intent_for_trigger("im"), "source:im")
if source == "show_annotation":
return self._decision(
delivery_intent_for_trigger("show_annotation"),
"source:show_annotation",
)
if source in {"web_composer", "failure_retry", "agent_initiated"}:
return self._decision("queue", f"source:{source}")
raise ValueError(f"unsupported input source: {source}")
def _decide_harness(self, envelope: InputEnvelope) -> AdmissionDecision:
requested = envelope.requested_intent
if requested is not None:
return self._decision(
normalize_delivery_intent(requested),
f"requested:{requested.strip().lower()}",
)
trigger = str(envelope.provenance.trigger or "").strip()
if trigger:
return self._decision(delivery_intent_for_trigger(trigger), f"trigger:{trigger}")
return self._decision("steer", "harness_default")
def _decision(self, intent: DeliveryIntent, reason: str) -> AdmissionDecision:
return AdmissionDecision(intent=intent, policy=self.id, reason=reason)
DEFAULT_ADMISSION_POLICY: AdmissionPolicy = DefaultAdmissionPolicy()
@dataclass(frozen=True)
class AdmittedInput:
delivery: dict[str, Any]
decision: AdmissionDecision
def existing_delivery(
conn: Connection,
*,
session_id: str,
delivery_id: str,
platform: str,
native_message_id: str | None,
scope_id: str | None,
) -> dict[str, Any] | None:
"""The Delivery an input already has: its own id, then its native identity.
A Delivery that belongs to another Session is refused, never reused.
"""
existing = message_deliveries.get_delivery(conn, delivery_id)
if existing is not None:
if existing["session_id"] != session_id:
raise ValueError("Delivery does not belong to the target Session")
return existing
if not message_deliveries.native_dedupe_key(
platform, native_message_id, scope_id=scope_id
):
return None
existing = message_deliveries.get_delivery_by_native_identity(
conn,
platform=platform,
native_message_id=str(native_message_id or ""),
scope_id=scope_id,
session_id=session_id,
normalize_legacy=True,
)
if existing is not None and existing["session_id"] != session_id:
raise ValueError("Delivery dedupe identity belongs to another Session")
return existing
def decide_admission(
envelope: InputEnvelope,
*,
policy: AdmissionPolicy = DEFAULT_ADMISSION_POLICY,
) -> AdmissionDecision:
return policy.decide(envelope)
def reserve_input(
conn: Connection,
envelope: InputEnvelope,
decision: AdmissionDecision,
*,
delivery_id: str,
dedupe_key: str | None = None,
admission_context: Mapping[str, Any] | None = None,
history: Mapping[str, Any] | None = None,
) -> dict[str, Any]:
"""Persist the reserved Delivery for a decided input in the caller's transaction.
``history`` replaces the admission event for a source that records its own
(a failure retry's binding, an agent-initiated Turn's start); the decision's
record is added to whichever event admits the Delivery.
"""
event = (
dict(history)
if history is not None
else {
"kind": "admission",
"priority": decision.priority,
"state": "reserved",
**({"context": dict(admission_context)} if admission_context else {}),
}
)
event["policy"] = decision.record()
return message_deliveries.insert_delivery(
conn,
delivery_id=delivery_id,
session_id=envelope.session_id,
priority=decision.priority,
state="reserved",
snapshot=envelope.snapshot(),
dispatch_text=envelope.dispatch_text,
dedupe_key=dedupe_key,
history_event=event,
)
def admit_input(
conn: Connection,
envelope: InputEnvelope,
*,
delivery_id: str,
dedupe_key: str | None = None,
admission_context: Mapping[str, Any] | None = None,
history: Mapping[str, Any] | None = None,
reuse_existing: bool = False,
policy: AdmissionPolicy = DEFAULT_ADMISSION_POLICY,
) -> AdmittedInput:
"""Decide one input's priority and reserve its Delivery.
With ``reuse_existing`` an input that already has a Delivery, by id or by
its native identity (``existing_delivery``), gets that Delivery back and
nothing is written.
"""
decision = decide_admission(envelope, policy=policy)
if reuse_existing:
existing = existing_delivery(
conn,
session_id=envelope.session_id,
delivery_id=delivery_id,
platform=envelope.provenance.platform,
native_message_id=envelope.provenance.native_message_id,
scope_id=envelope.scope_id,
)
if existing is not None:
return AdmittedInput(delivery=existing, decision=decision)
delivery = reserve_input(
conn,
envelope,
decision,
delivery_id=delivery_id,
dedupe_key=dedupe_key,
admission_context=admission_context,
history=history,
)
return AdmittedInput(delivery=delivery, decision=decision)