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
"""Backend-native insertion into the currently active Avibe Turn."""
from __future__ import annotations
import asyncio
from dataclasses import dataclass, field
from enum import Enum
from typing import TYPE_CHECKING, Any, Mapping
from core.agent_input import AgentInputMetadata
if TYPE_CHECKING:
from modules.agents.base import AgentRequest
from modules.im.base import FileAttachment
AGENT_TURN_TOKEN = "turn_token"
AGENT_RUNTIME_TURN_TOKEN = "agent_runtime_turn_token"
class SteerOutcome(str, Enum):
"""Exhaustive result of one backend-native steering attempt."""
ACCEPTED = "accepted"
NOT_ACTIVE = "not_active"
REFUSED = "refused"
UNKNOWN = "unknown"
@dataclass(frozen=True)
class SteerRequest:
"""One guarded insertion with original text and session-resolved attachments."""
target_session_id: str
expected_logical_turn_id: str
expected_native_turn_id: str
text: str
attempt_id: str = ""
input_metadata: AgentInputMetadata | None = None
files: tuple[FileAttachment, ...] = ()
@dataclass(frozen=True)
class SteerReconcileRequest:
"""One read-only query for exact evidence about a prior steer attempt."""
target_session_id: str
expected_logical_turn_id: str
expected_native_turn_id: str
attempt_id: str
@dataclass(frozen=True)
class SteerResult:
"""Typed receipt; backend diagnostics remain subordinate to ``outcome``."""
outcome: SteerOutcome
reason: str | None = None
details: Mapping[str, Any] = field(default_factory=dict)
@dataclass(frozen=True)
class ActiveSteerTarget:
"""Live AgentService gate state passed to a backend adapter."""
runtime_key: str
logical_turn_id: str
context: Any
agent_request: AgentRequest | None
agent: Any
def result(
outcome: SteerOutcome,
*,
reason: str | None = None,
**details: Any,
) -> SteerResult:
return SteerResult(outcome=outcome, reason=reason, details=details)
def _context_session_ids(context: Any) -> set[str]:
payload = getattr(context, "platform_specific", None) or {}
target = payload.get("agent_session_target") if isinstance(payload, dict) else None
if isinstance(target, dict):
target_id = str(target.get("id") or "").strip()
if target_id:
return {target_id}
if isinstance(payload, dict):
legacy_id = str(payload.get("agent_session_id") or "").strip()
if legacy_id:
return {legacy_id}
return set()
def _active_targets(controller: Any, backend: str, session_id: str) -> list[ActiveSteerTarget]:
service = getattr(controller, "agent_service", None)
gates = getattr(service, "_turn_gates", None)
if not isinstance(gates, dict):
gates = {}
matches: list[ActiveSteerTarget] = []
for runtime_key, gate in list(gates.items()):
if str(getattr(gate, "backend", "") or "") != backend:
continue
if not str(getattr(gate, "token", "") or "") or not bool(
getattr(gate, "runtime_started", False)
):
continue
agent_request = getattr(gate, "request", None)
context = getattr(gate, "context", None) or getattr(agent_request, "context", None)
if context is None or session_id not in _context_session_ids(context):
continue
payload = getattr(context, "platform_specific", None) or {}
runtime_turn_id = str(payload.get(AGENT_RUNTIME_TURN_TOKEN) or "").strip()
if runtime_turn_id != str(getattr(gate, "token", "") or ""):
continue
logical_turn_id = str(payload.get(AGENT_TURN_TOKEN) or "").strip()
if not logical_turn_id:
continue
agent = getattr(gate, "agent", None)
if agent is None:
continue
matches.append(
ActiveSteerTarget(
runtime_key=str(runtime_key),
logical_turn_id=logical_turn_id,
context=context,
agent_request=agent_request,
agent=agent,
)
)
backend_agent = getattr(service, "agents", {}).get(backend)
additional_targets = getattr(backend_agent, "additional_steer_targets", None)
if callable(additional_targets):
for target in additional_targets(session_id):
if isinstance(target, ActiveSteerTarget) and all(
target.runtime_key != existing.runtime_key for existing in matches
):
matches.append(target)
return matches
def active_steer_identity(
controller: Any,
backend: str,
session_id: str,
*,
expected_logical_turn_id: str | None = None,
) -> tuple[str, str] | None:
"""Return the current logical/native identity pair for a steerable Turn."""
targets = _active_targets(controller, backend, session_id)
if expected_logical_turn_id is not None:
targets = [target for target in targets if target.logical_turn_id == expected_logical_turn_id]
if len(targets) != 1:
return None
target = targets[0]
native_identity = getattr(target.agent, "steering_native_turn_id", None)
if not callable(native_identity):
return None
native_turn_id = str(native_identity(target) or "").strip()
if not native_turn_id:
return None
return target.logical_turn_id, native_turn_id
async def steer_active_turn(
controller: Any,
backend: str,
request: SteerRequest,
) -> SteerResult:
"""Insert text through a registered backend without entering normal dispatch."""
targets = _active_targets(controller, backend, request.target_session_id)
if not targets:
service = getattr(controller, "agent_service", None)
if getattr(service, "agents", {}).get(backend) is None:
return result(
SteerOutcome.REFUSED,
reason="runtime_unavailable",
backend=backend,
)
return result(SteerOutcome.NOT_ACTIVE, reason="no_matching_active_turn", backend=backend)
logical_matches = [
target for target in targets if target.logical_turn_id == request.expected_logical_turn_id
]
if not logical_matches:
return result(SteerOutcome.NOT_ACTIVE, reason="stale_logical_turn", backend=backend)
native_matches: list[ActiveSteerTarget] = []
for target in logical_matches:
native_identity = getattr(target.agent, "steering_native_turn_id", None)
if callable(native_identity) and str(native_identity(target) or "").strip() == request.expected_native_turn_id:
native_matches.append(target)
if len(native_matches) == 1:
target = native_matches[0]
elif not native_matches and len(logical_matches) == 1:
# Let the sole backend generation distinguish a stale native identity
# from a runtime that disappeared after the shared gate was observed.
target = logical_matches[0]
else:
return result(SteerOutcome.NOT_ACTIVE, reason="stale_native_turn", backend=backend)
steer = getattr(target.agent, "steer_active_turn", None)
if not callable(steer):
return result(SteerOutcome.REFUSED, reason="unsupported", backend=backend)
attempt = asyncio.create_task(steer(request, target))
try:
receipt = await asyncio.shield(attempt)
except asyncio.CancelledError:
# Cancellation of the surface caller must not cancel an adapter after
# its native write may have started. Let it establish terminal
# ownership/reconciliation, then preserve the caller's cancellation.
while not attempt.done():
try:
await asyncio.shield(attempt)
except asyncio.CancelledError:
continue
except BaseException:
break
if attempt.done() and not attempt.cancelled():
try:
attempt.result()
except BaseException:
pass
raise
if not isinstance(receipt, SteerResult):
return result(SteerOutcome.UNKNOWN, reason="invalid_adapter_receipt", backend=backend)
return receipt
async def reconcile_steer_attempt(
controller: Any,
backend: str,
request: SteerReconcileRequest,
) -> SteerResult:
"""Read exact backend evidence without repeating the native write."""
service = getattr(controller, "agent_service", None)
backend_agent = getattr(service, "agents", {}).get(backend)
retained_target = getattr(backend_agent, "reconciliation_steer_target", None)
target = retained_target(request) if callable(retained_target) else None
if isinstance(target, ActiveSteerTarget):
targets = [target]
else:
targets = [
target
for target in _active_targets(controller, backend, request.target_session_id)
if target.logical_turn_id == request.expected_logical_turn_id
]
if len(targets) != 1:
return result(
SteerOutcome.UNKNOWN,
reason="reconciliation_target_unavailable",
backend=backend,
)
reconcile = getattr(targets[0].agent, "reconcile_steer_attempt", None)
if not callable(reconcile):
return result(
SteerOutcome.UNKNOWN,
reason="reconciliation_unsupported",
backend=backend,
)
receipt = await reconcile(request, targets[0])
if not isinstance(receipt, SteerResult):
return result(
SteerOutcome.UNKNOWN,
reason="invalid_reconciliation_receipt",
backend=backend,
)
return receipt