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
"""Best-effort mirror of inbound + outbound IM traffic into ``messages``.
This is the cross-platform write path that feeds the workbench: every
non-avibe IM event (Slack DM, Discord channel reply, Telegram private
chat, Lark/Feishu group ping, WeChat push) lands a row in the same
``messages`` table that avibe sessions write to. Downstream views — the
Inbox feed, per-session transcript, future cross-platform search — read
from one shape regardless of origin.
Hooks live in two places:
* ``core/handlers/message_handler.py`` calls :func:`mirror_inbound` once
per human-originated turn, after session resolution.
* ``core/message_dispatcher.py`` calls :func:`persist_agent_message` once per
agent ``emit_agent_message`` — for every type, on every platform incl. avibe,
BEFORE the IM mute filter. Chat outputs land in ``messages``; tool-call trace
events land in ``agent_events``.
Failures are swallowed and logged. A bad mirror write must never break
the live IM reply path.
"""
from __future__ import annotations
import logging
import os
import time
from datetime import datetime, timezone
from pathlib import Path
from typing import Any, Optional
from sqlalchemy.exc import IntegrityError
from core.citations import CitationBundle, finalize_citations, materialize_citations
from core.presentation import PRESENTATION_METADATA_KEY, PresentationDecision, presentation_metadata
from core.run_settlement import NON_COMPLETING_TURN_SETTLEMENTS
from core.services import sessions as workbench_sessions_service
from modules.im.base import MessageContext
from storage import agent_events_service, message_deliveries, messages_service, settings_service
from storage.db import get_cached_sqlite_engine
from vibe.message_types import activity_role_for, spec_for
logger = logging.getLogger(__name__)
# Non-avibe IM scopes are stored as channel rows. Platforms whose DM chat id is
# literally the user id (Telegram/WeChat style) would otherwise collide with a
# user scope for the same native id, so those DMs are stored as user rows.
# avibe projects are 'project' typed and pre-created via ``/api/projects``; this
# module never touches those.
DEFAULT_SCOPE_TYPE = "channel"
def _now() -> str:
return datetime.now(timezone.utc).isoformat()
def _scope_identity_for_context(context: MessageContext) -> tuple[str, str, str] | None:
platform = (context.platform or "").strip()
is_dm = bool((context.platform_specific or {}).get("is_dm", False))
use_user_scope = bool(
is_dm
and context.channel_id
and context.user_id
and context.channel_id == context.user_id
)
scope_type = "user" if use_user_scope else DEFAULT_SCOPE_TYPE
native_id = ((context.user_id if use_user_scope else context.channel_id) or "").strip()
if not platform or not native_id:
return None
return platform, scope_type, native_id
def scope_id_for_context(context: MessageContext) -> Optional[str]:
"""Return the stable native conversation identity without writing storage."""
identity = _scope_identity_for_context(context)
if identity is None:
return None
return settings_service.make_scope_id(*identity)
def _agent_message_scope_id(conn, context: MessageContext) -> Optional[str]:
"""Resolve the same scope used when an accepted agent Message is persisted."""
if context.platform == "avibe":
session_id = (context.platform_specific or {}).get("agent_session_id")
session_row = _session_row(conn, session_id) if session_id else None
return session_row["scope_id"] if session_row else None
return scope_id_for_context(context)
def _resolve_scope_id(conn, context: MessageContext) -> Optional[str]:
identity = _scope_identity_for_context(context)
if identity is None:
return None
platform, scope_type, native_id = identity
try:
return settings_service.upsert_scope(
conn,
platform=platform,
scope_type=scope_type,
native_id=native_id,
now=_now(),
supports_threads=bool(context.thread_id),
)
except Exception:
logger.exception("mirror: failed to upsert scope for %s::%s", platform, native_id)
return None
def _append_quietly(conn, **kwargs) -> Optional[dict]:
"""Insert one row and return its payload, swallowing the unique-constraint
clash that fires when the same native message id is delivered twice (rare
retry path). Returns ``None`` on the swallowed duplicate so callers can skip
the realtime ``message.new`` publish for a row that didn't materialize.
"""
try:
# Internal publication retains this snapshot; each browser recipient is
# projected by the SSE boundary, independently of transcript reads.
return messages_service.append(conn, include_local_error_detail=True, **kwargs)
except IntegrityError:
logger.debug(
"mirror: skipped duplicate native_message_id %s on platform %s",
kwargs.get("native_message_id"),
kwargs.get("platform"),
)
return None
def _publish_session_message(row: Optional[dict]) -> None:
"""Publish a session-scoped ``message.new`` for a freshly persisted row.
The Controller process persists agent + harness rows; this fans the row out
over ``inbox_events.bus`` → ``/internal/events`` → ``inbox_bridge`` →
browser ``SSEBroker`` (the #359 path), so an open Chat page appends it live —
the session/page-scoped stream that replaces per-turn SSE. Scoped to rows
that carry a ``session_id`` (avibe sessions); IM rows are scope-keyed and the
workbench Chat is avibe-only, so they have no live consumer.
"""
if not row or not row.get("session_id"):
return
try:
from core.inbox_events import bus
bus.publish("message.new", row)
except Exception:
logger.debug("message_mirror: message.new publish failed", exc_info=True)
# Streaming intermediate activity (interim ``assistant`` messages + ``tool_call``
# trace) to an open Chat page is gated on ``config.ui.show_agent_activity`` (default
# off). Reading the config parses a file, and this path runs once per agent emit —
# many times per turn — so the flag is cached briefly, keyed by config path so a
# fresh AVIBE_HOME (e.g. per-test) never reads a stale value. On any error the flag
# is OFF: a config glitch degrades to today's strict no-op (no extra stream).
_ACTIVITY_FLAG_TTL_SECONDS = 3.0
_activity_flag_cache: dict[str, tuple[float, bool]] = {}
def reset_activity_flag_cache() -> None:
"""Drop the cached ``show_agent_activity`` flag (test hook / config-change)."""
_activity_flag_cache.clear()
def _activity_streaming_enabled() -> bool:
try:
from config import paths
key = str(paths.get_config_path())
except Exception:
key = ""
now = time.monotonic()
cached = _activity_flag_cache.get(key)
if cached is not None and (now - cached[0]) < _ACTIVITY_FLAG_TTL_SECONDS:
return cached[1]
enabled = False
try:
from core.services import settings as settings_svc
enabled = bool(settings_svc.load_config_or_default().ui.show_agent_activity)
except Exception:
logger.debug("message_mirror: activity flag read failed", exc_info=True)
enabled = False
_activity_flag_cache[key] = (now, enabled)
return enabled
def _publish_activity_event(event_row: Optional[dict]) -> None:
"""Publish a session-scoped ``message.new`` for a ``tool_call`` trace event.
Tool-call rows live in ``agent_events`` (never in ``messages`` / the transcript),
so synthesize a ``messages``-shaped payload the Chat activity group can render
live. Called only when ``show_agent_activity`` is on; the payload carries its own
display data (no read-after-announce), so the browser never re-queries the row.
"""
if not event_row or not event_row.get("session_id"):
return
payload = {
"id": event_row.get("id"),
"scope_id": event_row.get("scope_id"),
"session_id": event_row.get("session_id"),
"platform": event_row.get("platform") or "avibe",
"author": "agent",
"type": "tool_call",
"source": "agent",
"author_id": None,
"author_name": event_row.get("agent_name"),
"native_message_id": None,
"parent_native_message_id": None,
"text": event_row.get("text") or "",
"content": event_row.get("content") or {},
"metadata": event_row.get("metadata") or {},
"created_at": event_row.get("created_at"),
"updated_at": event_row.get("updated_at") or event_row.get("created_at"),
"delivered_at": None,
"read_at": None,
}
try:
from core.inbox_events import bus
bus.publish("message.new", payload)
except Exception:
logger.debug("message_mirror: activity tool_call publish failed", exc_info=True)
def _hosted_card(conn, context: MessageContext, hosted: dict, *, scope_id, session_id) -> dict:
"""A hosted-tool card as the row stores it: on the Workbench, each image gains its media URL.
The card is a trace row, which never passes the transcript's media rewrite,
so its images are registered here, in the row's own transaction. The media
store reuses one token per (session, file), so the answer that links the
same file resolves to the same URL and the Web can join the two.
"""
images = hosted.get("images") if isinstance(hosted.get("images"), list) else []
if context.platform != "avibe" or not session_id or not images:
return hosted
from core.agent_core.messages import IMAGE_MIME_TYPES
from core.workbench_media import register_agent_reply_media
from storage import media_service
registered = []
for image in images:
path = image.get("path") if isinstance(image, dict) else None
if not isinstance(path, str) or not os.path.isabs(path):
registered.append(image)
continue
try:
# Canonical, as the transcript's rewrite registers it, so both share one token.
canonical = str(Path(path).resolve())
mime = image.get("mime")
token = register_agent_reply_media(
conn,
scope_id=scope_id,
session_id=session_id,
kind="image",
local_path=canonical,
file_name=os.path.basename(canonical),
# The record names the image's type; a path need not carry a suffix that says it.
content_type=mime if mime in IMAGE_MIME_TYPES else None,
)
row = media_service.get_by_token(conn, token) or {}
except Exception:
logger.exception("persist_agent_message: hosted image registration failed")
registered.append(image)
continue
url = f"/api/media/{token}"
width, height = row.get("width_px"), row.get("height_px")
if width and height:
url = f"{url}?w={width}&h={height}"
extra = {"media_url": url}
if row.get("size_bytes") is not None:
extra["bytes"] = row["size_bytes"]
registered.append({**image, **extra})
return {**hosted, "images": registered}
def _session_row(conn, session_id: str) -> Optional[dict]:
"""Resolve scope/provenance from an agent session."""
from sqlalchemy import select
from storage.models import agent_sessions
row = conn.execute(
select(
agent_sessions.c.scope_id,
agent_sessions.c.agent_id,
agent_sessions.c.agent_name,
agent_sessions.c.agent_backend,
agent_sessions.c.visibility,
).where(agent_sessions.c.id == session_id)
).mappings().first()
return dict(row) if row else None
def _scope_id_for_session(conn, session_id: str) -> Optional[str]:
"""Resolve a message's scope from its agent session (works for avibe +
IM once the session has been reserved)."""
row = _session_row(conn, session_id)
return row["scope_id"] if row else None
# Maps the dispatcher's canonical message type to the persisted ``messages.type``.
# ``system`` folds into ``assistant`` (a process-log message, not a user-facing
# reply): once terminal-failure ``notify`` rows became inbox-eligible, routine
# system/init logs stored as ``notify`` would have created an Inbox card with a
# junk preview before any real reply. As process log, ``system`` belongs with
# ``assistant`` / ``tool_call`` — out of the inbox and out of the transcript
# (Codex P2). Genuine terminal failures persist via canonical ``notify``.
_AGENT_TYPE_BY_CANONICAL = {
"result": "result",
# A terminal FAILED result — kept distinct from ``result`` so unread queries
# (result-only) don't count it, while it stays in the transcript/inbox.
"error": "error",
"notify": "notify",
"output": "output",
"assistant": "assistant",
"interim": "interim",
"system": "assistant",
}
def _is_tool_call_type(canonical_type: str | None) -> bool:
return (canonical_type or "") in {"toolcall", "tool_call"}
def _agent_provenance_from_context(context: MessageContext, session_row: Optional[dict] = None) -> tuple[Optional[str], Optional[str]]:
spec = context.platform_specific or {}
target = spec.get("agent_session_target") or {}
# The Agent that ran, when routing resolved one (a new chat-app session may name
# its Agent nowhere else).
resolved = spec.get("resolved_vibe_agent")
resolved = resolved if isinstance(resolved, dict) else {}
agent_name = (
spec.get("vibe_agent_name")
or resolved.get("name")
or target.get("agent_name")
or (session_row or {}).get("agent_name")
)
backend = spec.get("vibe_agent_backend") or target.get("agent_backend") or (session_row or {}).get("agent_backend")
return agent_name, backend
def _author_identity(context: MessageContext, session_row: Optional[dict] = None) -> dict[str, str]:
"""The Agent that wrote a reply, recorded with it (``metadata``): a session can
switch Agents, and its earlier replies keep the one that wrote them. The Agent that
ran (``resolved_vibe_agent``) is preferred over the session's routing."""
spec = context.platform_specific or {}
resolved = spec.get("resolved_vibe_agent")
resolved = resolved if isinstance(resolved, dict) else {}
target = spec.get("agent_session_target")
target = target if isinstance(target, dict) else {}
_name, routed_backend = _agent_provenance_from_context(context, session_row)
identity = {
"author_agent_id": resolved.get("id") or target.get("agent_id") or (session_row or {}).get("agent_id"),
"author_backend": resolved.get("backend") or routed_backend,
}
return {key: str(value) for key, value in identity.items() if isinstance(value, str) and value.strip()}
def _trace_ids_from_context(context: MessageContext) -> tuple[Optional[str], Optional[str]]:
spec = context.platform_specific or {}
trigger_kind = str(spec.get("task_trigger_kind") or "").strip()
run_id = str(spec.get("task_execution_id") or "").strip() or None
turn_token = str(spec.get("turn_token") or "").strip()
turn_id = turn_token or None
if trigger_kind == "agent_run" and run_id and not turn_id:
turn_id = run_id
return turn_id, run_id
def persist_agent_message(
context: MessageContext,
canonical_type: str,
text: str,
*,
quick_replies: Optional[list[str]] = None,
result_footer: Optional[str] = None,
citations: Optional[CitationBundle] = None,
metadata: Optional[dict[str, Any]] = None,
native_message_id: Optional[str] = None,
error_sink: Optional[list] = None,
existing_row_id: Optional[str] = None,
hosted: Optional[dict] = None,
turn_reply: Optional[tuple[str, str]] = None,
presentation: Optional["PresentationDecision"] = None,
) -> Optional[dict]:
"""Persist one agent output into the workbench ``messages`` store.
``turn_reply`` is ``(turn_id, run_copy)`` for a reply that does not end its live
Turn: the reply's Run copy is recorded as the Turn's last delivered reply
(``session_turn_replies``) in the same transaction that writes this receipt, so
the receipt exists exactly when the record does (docs/plans/reply-and-turn-end.md,
rule 5). A replayed output that finds its receipt already written records nothing.
``presentation`` is the dispatcher's decision for this output
(``core.presentation``): the row (a tool call's trace event too) records it under
``metadata["presentation"]``, it may decline the Web Push the catalog allows, and
an output it keeps local is not published to the Web, as with ``suppress_delivery``.
``existing_row_id`` names a row the backend already committed as its transcript
(the Avibe Agent): its display columns are written instead of inserting a
second row, and everything after the write (rank, ``message.new``, inbox) is
unchanged (``_write_committed_row``).
Unified across **all** platforms (including avibe, which has no IM mirror)
and called BEFORE any IM delivery/mute decision, so assistant messages and
tool-call trace events land even when a channel hides them. Each ``emit_agent_message``
call is a distinct logical message — the consolidated IM "log" message only
merges them for display — so one row per emit is correct, not fragments.
``context`` is the **post-routing delivery target** (see
``emit_agent_message``): IM rows are attributed to the channel that actually
received the reply, so routed / ``post_to`` / thread replies are recorded
under their delivery scope rather than the source session's — keeping
cross-platform history/search pointed at the right conversation. avibe rows
instead use the session's project scope (``agent_session_id`` from
``context.platform_specific``), which is what the per-session inbox groups on.
"""
if not text or not text.strip():
return
if not context.platform:
return
metadata = presentation_metadata(presentation, metadata)
# ``system`` messages are generated by us (init banners, status lines), not the
# agent — don't persist them at all (they have no place in the transcript and
# would only be noise in history) (user request).
if (canonical_type or "") == "system":
return
session_id = (context.platform_specific or {}).get("agent_session_id")
# A decision that keeps the output local suppresses Web publication for any
# context, exactly as a background Session's ``suppress_delivery`` does.
suppress_delivery = bool((context.platform_specific or {}).get("suppress_delivery")) or (
presentation is not None and not presentation.outward
)
try:
engine = get_cached_sqlite_engine()
inbox_row = None
appended_row = None
tool_event_row = None
message_type = None
activity_ranked = False
is_tool_call = _is_tool_call_type(canonical_type)
with engine.begin() as conn:
if context.platform == "avibe":
# Inbox groups by the avibe session's project scope; never invent
# a 'channel' scope for avibe (projects are pre-created via
# /api/projects). Skip if the session row isn't visible yet.
session_row = _session_row(conn, session_id) if session_id else None
scope_id = session_row["scope_id"] if session_row else None
row_session_id = session_id
else:
# IM: the row stays SCOPE-keyed to the delivery channel (this
# ``context`` is the routed target, matching where the reply was
# sent), but it now ALSO carries the SOURCE session_id (already
# resolved into ``agent_session_id``) so a session's full transcript
# is queryable by ``session_id`` on every platform. ``scope_id`` and
# ``session_id`` can legitimately differ under routing / ``post_to``:
# the session join answers "what did this session say", the scope
# grouping answers "what happened in this channel".
session_row = None
scope_id = _resolve_scope_id(conn, context)
row_session_id = session_id
if scope_id is None and session_row is None:
return
# Provenance: every agent reply is source='agent'; name = the
# session's agent (from the dispatch context). source_id (author_id)
# is left to the agent-id wiring later; the session already carries it.
agent_name, backend = _agent_provenance_from_context(context, session_row)
if is_tool_call:
turn_id, run_id = _trace_ids_from_context(context)
# Captured for the (gated) live activity publish after commit; the
# row itself is trace data in ``agent_events`` (never in ``messages``).
tool_event_row = agent_events_service.append(
conn,
scope_id=scope_id,
session_id=row_session_id,
platform=context.platform,
event_type="tool_call",
visibility="trace",
# A trace row carries text and no sidecar, so its copy is
# written here rather than finalized with spans.
text=materialize_citations(text, citations) or text,
content={
"kind": canonical_type or "tool_call",
**(
{"hosted": _hosted_card(conn, context, hosted, scope_id=scope_id, session_id=row_session_id)}
if hosted
else {}
),
},
metadata={
**(
{PRESENTATION_METADATA_KEY: presentation.to_metadata()}
if presentation is not None
else {}
),
"canonical_type": canonical_type or "tool_call",
# A native hosted call happened before the text of the response that
# carried it, though it is emitted after that row commits.
**(
{"precedes_message_id": hosted["response_id"]}
if hosted and isinstance(hosted.get("response_id"), str)
else {}
),
},
agent_name=agent_name,
backend=backend,
turn_id=turn_id,
run_id=run_id,
)
else:
message_type = _AGENT_TYPE_BY_CANONICAL.get(canonical_type or "", "assistant")
# Workbench Chat only: rewrite ``file://`` links in the persisted copy
# to same-origin media-proxy URLs so the browser renders agent images
# inline + files as download cards. IM rows keep the raw ``file://``
# (the dispatcher uploads those to the platform separately). Scoped to
# transcript-visible rows (result/notify/interim …) so we don't mint
# tokens for the hidden intermediate assistant stream.
if (
context.platform == "avibe"
and spec_for(message_type)["transcript"]
and row_session_id
):
try:
from core.workbench_media import rewrite_agent_media
text = rewrite_agent_media(
conn, scope_id=scope_id, session_id=row_session_id, text=text
)
except Exception:
logger.exception("persist_agent_message: media rewrite failed")
# The last transform this body will see has now run, so this is
# where the registered citations become links and the sidecar is
# measured. Doing it any earlier would bind spans to a body the
# reader never gets: the media rewrite above changes the text
# around them, and on IM the delivered copy was truncated or
# split from a different string altogether.
text, citation_rows = finalize_citations(text, citations)
content: Optional[dict] = {"kind": canonical_type} if canonical_type else None
# Quick-reply buttons (avibe result): the trailing ``---\n[label]…``
# block was already parsed + stripped upstream; carry the labels in
# ``content`` so the workbench renders the button group (IM channels
# render their own native buttons from the same parse).
if quick_replies:
content = {**(content or {}), "quick_replies": list(quick_replies)}
# Keep the generated duration/token summary as structured content.
# IM delivery may still fold it into ``text``, while the Web
# transcript can render it beside the timestamp without guessing.
if result_footer:
content = {**(content or {}), "result_footer": result_footer}
# Resolved citation sources. ``text`` already carries the links, so
# every surface reads correctly without this; the structured copy is
# what lets the Web transcript render compact source badges, and it
# survives reload because it lives on the row, not in the delivery.
if citation_rows:
content = {**(content or {}), "citations": citation_rows}
metadata = {**_author_identity(context, session_row), **(metadata or {})}
if existing_row_id:
appended_row = _write_committed_row(
conn,
existing_row_id,
session_id=row_session_id,
platform=context.platform,
scope_id=scope_id,
message_type=message_type,
text=text,
content=content,
metadata=metadata,
native_message_id=native_message_id,
parent_native_message_id=context.thread_id,
suppress_delivery=suppress_delivery,
)
else:
appended_row = _append_quietly(
conn,
scope_id=scope_id,
session_id=row_session_id,
platform=context.platform,
author="agent",
source="agent",
author_name=agent_name,
message_type=message_type,
text=text,
metadata=metadata,
native_message_id=native_message_id,
parent_native_message_id=context.thread_id,
content=content,
)
if turn_reply is not None and appended_row is not None:
# This write is the reply's receipt: the Turn's record commits
# with it, or neither does (a failure here fails the receipt).
message_deliveries.record_turn_reply(conn, *turn_reply)
if (
existing_row_id is None
and appended_row is None
and native_message_id
and not suppress_delivery
and spec_for(message_type)["inboxPreview"]
):
# The unique row may be local-only history from an earlier
# suppress_delivery attempt. This call occurs after the visible
# output send, so only now may that row become a receipt.
appended_row = messages_service.promote_suppressed_native_message(
conn,
platform=context.platform,
scope_id=scope_id,
session_id=row_session_id,
native_message_id=native_message_id,
message_type=message_type,
text=text,
content=content,
metadata=metadata,
include_local_error_detail=True,
)
# Recompute the session's inbox row so the realtime event can patch
# the browser without a refetch. avibe-only: the workbench inbox is
# scoped to avibe sessions (IM rows persist but aren't shown there).
if context.platform == "avibe" and session_id and not suppress_delivery:
inbox_row = messages_service.get_inbox_session(conn, session_id)
# Both branches rejoin here: a chat row and a tool-call trace event are
# equally proof the agent is working, and the session list ranked on
# input alone, so an unattended session sank while it worked. Rides the
# open transaction — no extra commit, no extra fsync.
#
# THE RANK ASSERTS ONE THING: this session's agent persisted output just
# now. So it is bounded by exactly the conditions that can make that
# claim false, and by nothing else:
# 1. a session row to rank (``row_session_id``);
# 2. output that actually materialized (below);
# 3. the row is not archived — archive is terminal, re-asserted inside
# the UPDATE because this write has no request boundary to guard it;
# 4. the throttle, also a predicate on the row (see the storage helper).
# Conditions of the surrounding DELIVERY path are deliberately absent,
# and borrowing one by proximity is what cost two review rounds.
# ``context.platform`` is not a condition: the rank is read by the Web
# list, ``vibe session list``, the run graph and the running-agents view
# alike, so output ranks on every platform. ``suppress_delivery`` is not
# one either — a hidden session is not an unread one. A background
# Session is out of the session list but is a first-class agent-graph
# node ordered by this very column (``agent_graph`` defaults
# ``include_background=True``), and visibility is a MUTABLE preference
# where the archive is terminal: the PATCH that restores a session to the
# foreground writes ``visibility`` and ``updated_at`` and never backfills
# ``last_active_at``. Holding the rank while hidden therefore saves no
# dead write; it leaves the row mis-ordered for every later reader.
#
# (2) is a row having materialized, not merely reaching this line:
# ``_append_quietly`` returns ``None`` when the same
# ``native_message_id`` arrives twice, and the promote path can decline
# too, so a retried terminal output persists nothing. Replaying one
# logical output must not lift a long-finished session back to the top of
# the list on nothing new. The tool-call branch always inserts, so this
# only ever excludes the deduplicated chat row.
if row_session_id and (appended_row is not None or tool_event_row is not None):
activity_ranked = workbench_sessions_service.touch_session_agent_activity(
conn, row_session_id
)
# A rank change means the list has to re-sort, so tell an open browser the
# same way an accepted user send does. Gated on the bump having actually
# landed, which bounds this to one event per minute per session — strictly
# cheaper than the per-message ``inbox.session.updated`` below. avibe-only
# for the reason the publishes below are: an IM session has no open Chat or
# sidebar consumer, so publishing it would be dead traffic.
#
# It follows the RANK, not delivery, so it fires for a hidden session too —
# which is right rather than merely consistent: the surface that orders
# background rows by this column is the agent graph, and that is the view
# whose consumer refetches on this event. The payload is
# ``{session_id, scope_id, event}`` with no content, so a reorder announces
# nothing a suppressed message body would have carried.
if activity_ranked and context.platform == "avibe":
from core.inbox_events import bus
bus.publish(
"session.activity",
{"session_id": row_session_id, "scope_id": scope_id, "event": "agent_activity"},
)
# tool_call rows never enter ``messages``/TRANSCRIPT_TYPES; when the Chat
# activity panel is enabled they fan out here as a synthesized
# ``message.new`` so an open Chat page shows the step live. Default off →
# no publish (strict no-op). Return None to preserve the tool_call contract.
if is_tool_call:
if context.platform == "avibe" and not suppress_delivery and _activity_streaming_enabled():
_publish_activity_event(tool_event_row)
return None
# Fan the row out to an open Chat page (session-scoped stream), then bump
# the inbox card. Both ride the controller→browser bridge. Only publish
# transcript-visible types so the live stream carries EXACTLY what the
# history fetch returns — EXCEPT interim ``assistant`` rows, which stream
# only when the Chat activity panel is enabled (they still stay out of the
# transcript + inbox; the activity group renders them separately).
# avibe-only: IM rows now carry a session_id too, but the workbench Chat is
# avibe-only, so keep the live fan-out scoped to avibe (an IM session has no
# open Chat consumer; publishing it would be dead traffic).
if context.platform == "avibe" and not suppress_delivery and (
message_type in messages_service.TRANSCRIPT_TYPES
or (
activity_role_for(message_type, metadata) == "activity"
and _activity_streaming_enabled()
)
):
_publish_session_message(appended_row)
if inbox_row is not None:
from core.inbox_events import bus
bus.publish("inbox.session.updated", inbox_row)
try:
from core.web_push_notifications import maybe_notify_inbox_message
if presentation is None or presentation.web_push:
maybe_notify_inbox_message(appended_row, inbox_row)
except Exception:
logger.debug("web push notification scheduling failed", exc_info=True)
return appended_row
except Exception as err:
logger.exception("persist_agent_message: failure on platform=%s", context.platform)
# Surfaced, not raised. A caller that owes a durable receipt needs to know
# WHY the row is missing — propagating only ``None`` says a receipt is
# absent and nothing about whether the message was delivered. Raising
# instead would be caught by the notify branch and discard the message id
# already in hand, which is the bug this channel exists to avoid.
# Optional so the eleven callers that ignore it are unaffected.
if error_sink is not None:
error_sink.append(err)
return None
# Display keys ``persist_agent_message`` owns in ``content_json``; ``model`` (the
# transcript payload of a committed row) is never among them.
_DISPLAY_CONTENT_KEYS = ("text", "kind", "quick_replies", "result_footer", "citations")
_FINAL_ROW_TYPES = ("result", "error")
def _write_committed_row(
conn,
row_id: str,
*,
session_id: Optional[str],
platform: str,
scope_id: Optional[str],
message_type: str,
text: str,
content: Optional[dict],
metadata: Optional[dict],
native_message_id: Optional[str],
parent_native_message_id: Optional[str],
suppress_delivery: bool,
) -> Optional[dict]:
"""Write the display columns of an agent row its backend committed; never insert one.
The same rules as an inserted row, applied to the committed one:
* the row is attributed to the delivery target (``platform``, ``scope_id``);
* a terminal write types the row ``result`` or ``error`` (the dispatcher's
failure classification), including a final the backend committed hidden
because it had nothing to show; any other write keeps the row's type;
* the row takes the output's ``native_message_id``, which is how the
dispatcher recognizes a retry of the same output, but never one another row
holds, so the unique index cannot break (a concurrent duplicate, which
``_append_quietly`` swallows for an inserted row);
* an outward send clears a ``delivery_suppressed`` marker, the promotion
``promote_suppressed_native_message`` performs for an inserted row.
The transcript payload (``content_json.model``), the row's place in the
transcript (``created_at``, ``delivered_at``), and its context identity stay as
committed.
"""
import json
from sqlalchemy import select, update
from storage.models import messages
row = conn.execute(
select(messages).where(messages.c.id == row_id, messages.c.author == "agent")
).mappings().first()
if row is None or (session_id is not None and row["session_id"] != session_id):
logger.warning("persist_agent_message: committed row %s is not an agent row of this Session", row_id)
return None
try:
body = json.loads(row["content_json"] or "{}")
old_metadata = json.loads(row["metadata_json"] or "{}")
except (TypeError, ValueError):
body, old_metadata = {}, {}
body = {key: value for key, value in body.items() if key not in _DISPLAY_CONTENT_KEYS}
body.update({key: value for key, value in (content or {}).items() if key != "model"})
body["text"] = text
merged_metadata = {key: value for key, value in old_metadata.items() if key != "delivery_suppressed"}
merged_metadata.update(metadata or {})
if suppress_delivery:
merged_metadata["delivery_suppressed"] = True
values: dict = {
"content_text": text,
"content_json": json.dumps(body),
"metadata_json": json.dumps(merged_metadata),
"updated_at": messages_service.canonical_message_timestamp(_now()),
}
if scope_id is not None:
values.update(platform=platform, scope_id=scope_id)
if message_type in _FINAL_ROW_TYPES:
values["type"] = message_type
if parent_native_message_id and not row["parent_native_message_id"]:
values["parent_native_message_id"] = parent_native_message_id
if native_message_id and native_message_id != row["native_message_id"]:
target_platform, target_scope = values.get("platform", row["platform"]), values.get("scope_id", row["scope_id"])
holder = messages_service.get_native_message(
conn, platform=target_platform, scope_id=target_scope, native_message_id=native_message_id
)
if holder is None:
values["native_message_id"] = native_message_id
else:
logger.warning("persist_agent_message: native id %s already belongs to row %s", native_message_id, holder["id"])
conn.execute(update(messages).where(messages.c.id == row_id).values(**values))
return messages_service.get_message(conn, row_id, include_local_error_detail=True)
def persist_silent_terminal(
context: MessageContext,
*,
is_error: bool,
settled_by: str | None = None,
) -> None:
"""Record reply-less IM terminal evidence outside the Message transcript.
Durable Workbench turns settle through ``session_turns``. IM turns do not have
that execution owner, so their empty/silent terminal result is retained as an
append-only trace event for activity grouping and fork-boundary recovery.
``settled_by`` names the release when the turn ended without the backend
producing a result, and it outranks ``is_error`` for the same reason it does on
a durable Turn: a runtime the service retired on purpose ended ``canceled``,
not ``failed``. Omitting the event entirely is NOT the alternative -- this row
IS the IM turn's boundary, so dropping it leaves the turn's tool activity
logically open, which ``list_turn_groups`` renders as a still-running card and
``_latest_source_message_anchor`` reads as no fork boundary at all.
"""
session_id = (context.platform_specific or {}).get("agent_session_id")
if not context.platform or not session_id:
return
try:
engine = get_cached_sqlite_engine()
with engine.begin() as conn:
if context.platform == "avibe":
session_row = _session_row(conn, session_id)
scope_id = session_row["scope_id"] if session_row else None
else:
session_row = None
scope_id = _resolve_scope_id(conn, context)
if scope_id is None and session_row is None:
return
agent_name, backend = _agent_provenance_from_context(context, session_row)
turn_id, run_id = _trace_ids_from_context(context)
agent_events_service.append(
conn,
scope_id=scope_id,
session_id=session_id,
platform=context.platform,
event_type="silent_terminal",
visibility="trace",
metadata={
"terminal_outcome": NON_COMPLETING_TURN_SETTLEMENTS.get(
settled_by or "",
"failed" if is_error else "completed",
),
},
agent_name=agent_name,
backend=backend,
turn_id=turn_id,
run_id=run_id,
)
except Exception:
logger.exception(
"persist_silent_terminal: failure on platform=%s",
context.platform,
)
def agent_message_exists(
context: MessageContext,
native_message_id: str | None,
) -> Optional[dict[str, Any]]:
"""Load the accepted Message receipt before external delivery.
The database unique constraint remains the final race guard. This early
read prevents retries from posting the same durable output twice and returns
the canonical text, footer, and provenance for local-only settlement.
"""
platform = str(context.platform or "").strip()
identity = str(native_message_id or "").strip()
if not platform or not identity:
return None
try:
engine = get_cached_sqlite_engine()
with engine.begin() as conn:
return messages_service.get_native_message(
conn,
platform=platform,
scope_id=_agent_message_scope_id(conn, context),
native_message_id=identity,
)
except Exception:
logger.debug("agent_message_exists: lookup failed open", exc_info=True)
return None
def delivered_committed_row(
context: MessageContext,
row_id: str | None,
*,
outward: bool,
) -> Optional[dict[str, Any]]:
"""The receipt of a backend-committed row an earlier emit already delivered to ``context``.
A row its backend committed (the Avibe Agent's) has no native id a repeated emit
could be recognized by, but its display is written only as its delivery: on the
Web that write is the delivery, and on IM it follows a send that returned an id
(``persist_agent_message``). A row written for this platform is therefore the
receipt a native id is for an inserted row, except local-only history for an
outward send. A repeat between a send and that write sends again.
"""
platform = str(context.platform or "").strip()
if not platform or not row_id:
return None
try:
engine = get_cached_sqlite_engine()
with engine.connect() as conn:
row = messages_service.get_message(conn, row_id, include_local_error_detail=True)
if row is None or row.get("author") != "agent" or row.get("platform") != platform:
return None
if row.get("scope_id") != _agent_message_scope_id(conn, context):
return None
except Exception:
logger.debug("delivered_committed_row: lookup failed open", exc_info=True)
return None
content, metadata = row.get("content"), row.get("metadata")
if not isinstance(content, dict) or "kind" not in content:
return None # as committed: never delivered
if outward and isinstance(metadata, dict) and metadata.get("delivery_suppressed") is True:
return None
return row
def mirror_harness_inbound(
context: MessageContext,
text: str,
*,
message_type: str = messages_service.HARNESS_TYPE,
) -> bool:
"""Record a harness-originated prompt (scheduled task / watch / webhook).
The backend consumes the prompt as turn input for the default harness type,
but the persisted row must not claim the human authored it. ``author``
therefore uses the first-class harness role while ``source='harness'``
preserves provenance. Callers that only need a transcript notification can
provide a non-input catalog type such as ``notify`` or ``vault``.
``author_name`` carries the trigger kind (scheduled / watch / webhook / ...)
and ``author_id`` the run-definition id, per the provenance spec.
Unlike :func:`mirror_inbound` this *does* cover avibe: no REST endpoint
writes the harness prompt, so without this the workbench transcript would
show an agent reply with no originating turn. Scope resolution mirrors
:func:`persist_agent_message` — avibe rows attach to the session's project
scope, IM rows to the delivery channel.
"""
if not text or not text.strip():
return False
if not context.platform:
return False
spec = context.platform_specific or {}
trigger_kind = spec.get("task_trigger_kind")
definition_id = spec.get("task_definition_id")
session_id = spec.get("agent_session_id")
suppress_delivery = bool(spec.get("suppress_delivery"))
provenance_metadata = {
key: value
for key in (
"source_kind",
"source_actor",
"vault_request_type",
"vault_request_status",
)
if (value := spec.get(key)) not in (None, "")
}
try:
engine = get_cached_sqlite_engine()
appended_row = None
inbox_row = None
with engine.begin() as conn:
if context.platform == "avibe":
session_row = _session_row(conn, session_id) if session_id else None
scope_id = session_row["scope_id"] if session_row else None
row_session_id = session_id
else:
# Attribute the prompt to the SAME scope the reply lands in. A
# scheduled/watch run with a delivery override (post_to / a
# different deliver-key) sends its result to the override channel
# (see ``emit_agent_message``); resolve the prompt there too so
# one turn isn't split across the source + delivery scopes (Codex
# P2). Falls back to the source context when there's no override.
deliver_ctx = context
override = spec.get("delivery_override") or {}
if override.get("channel_id"):
deliver_ctx = MessageContext(
user_id=override.get("user_id") or context.user_id,
channel_id=override["channel_id"],
platform=override.get("platform") or context.platform,
thread_id=override.get("thread_id"),
)
scope_id = _resolve_scope_id(conn, deliver_ctx)
# Scope-keyed to the delivery channel, but carry the source
# session_id too so the harness prompt joins to its session, the
# same way the agent reply does in ``persist_agent_message``.
row_session_id = session_id
session_row = None
if scope_id is None and session_row is None:
return False
appended_row = _append_quietly(
conn,
scope_id=scope_id,
session_id=row_session_id,
platform=context.platform,
author="harness",
source="harness",
author_name=trigger_kind,
author_id=definition_id,
message_type=message_type,
text=text,
metadata=provenance_metadata,
native_message_id=context.message_id,
parent_native_message_id=context.thread_id,
)
# Recompute the inbox card so the harness prompt re-ranks the session
# + flips its activity for other open views (avibe only; the inbox is
# avibe-scoped). No-op until the session has a result row.
if context.platform == "avibe" and row_session_id and not suppress_delivery:
inbox_row = messages_service.get_inbox_session(conn, row_session_id)
# Surface the harness-triggered prompt on an open Chat page immediately,
# so the upcoming agent reply isn't shown with no originating turn.
# avibe-only: IM rows carry a session_id now but have no open Chat consumer.
if context.platform == "avibe" and not suppress_delivery:
_publish_session_message(appended_row)
if inbox_row is not None:
from core.inbox_events import bus
bus.publish("inbox.session.updated", inbox_row)
return True
except Exception:
logger.exception("mirror_harness_inbound: unexpected failure on platform=%s", context.platform)
return False
def mirror_vault_waiter_outcome(
*,
session_id: str,
request_id: str,
request_type: str,
request_status: str,
message: str,
) -> bool:
"""Persist a Vault result already consumed by a synchronous CLI waiter.
The waiting Agent turn receives the result from the CLI command itself, so starting a callback
turn would deliver it twice. The transcript still needs the same first-class Vault provenance
as an asynchronous callback. A stable native identity makes the mirror idempotent if callback
bookkeeping is retried after the message commit.
"""
identity = str(session_id or "").strip()
vault_request_id = str(request_id or "").strip()
status = str(request_status or "").strip()
if not identity or not vault_request_id or not status:
return False
return mirror_harness_inbound(
MessageContext(
user_id="vault",
channel_id=identity,
platform="avibe",
message_id=f"vault:{vault_request_id}:{status}:waiter",
platform_specific={
"agent_session_id": identity,
"task_trigger_kind": "vault",
"source_kind": "callback",
"source_actor": f"vault:{vault_request_id}",
"vault_request_type": str(request_type or ""),
"vault_request_status": status,
},
),
message,
message_type=messages_service.VAULT_TYPE,
)
def mirror_inbound(context: MessageContext, text: str) -> None:
"""Record a human-originated IM message into the messages table.
Written scope-keyed with ``session_id=None``: the turn's agent session is not
bound until dispatch, which runs AFTER this inbound mirror. ``message_handler``
back-fills the session_id via :func:`link_inbound_message_session` once the
backend binds it, so the human prompt ends up queryable by ``session_id`` like
the agent reply and every other turn message — only the write order differs.
"""
if not text or not text.strip():
return
if not context.platform:
return
if context.platform == "avibe":
# avibe's REST endpoint already writes through ``messages_service``;
# mirroring here would double-count the row.
return
try:
engine = get_cached_sqlite_engine()
with engine.begin() as conn:
scope_id = _resolve_scope_id(conn, context)
if scope_id is None:
return
_append_quietly(
conn,
scope_id=scope_id,
# Back-filled post-dispatch by link_inbound_message_session — the
# session PK isn't known yet at inbound-mirror time.
session_id=None,
platform=context.platform,
author="user",
source="user",
message_type="user",
text=text,
author_id=context.user_id,
native_message_id=context.message_id,
parent_native_message_id=context.thread_id,
)
except Exception:
logger.exception("mirror_inbound: unexpected failure on platform=%s", context.platform)
def link_inbound_message_session(*, platform: str, native_message_id: str, session_id: str) -> None:
"""Back-fill ``session_id`` onto the IM inbound row written by :func:`mirror_inbound`.
``message_handler`` calls this once dispatch has bound the turn's session (the PK
is stamped on ``context.platform_specific['agent_session_id']`` — the same field
:func:`persist_agent_message` reads for the reply). Keyed by the unique
``(platform, native_message_id)``, so it stamps exactly this turn's human prompt
and only while still unlinked. No-op for avibe (its inbound is written
session-keyed via REST). Best-effort: a failure must never break the turn.
"""
if not (platform and native_message_id and session_id) or platform == "avibe":
return
try:
from sqlalchemy import update as _sa_update
from storage.models import messages as _messages
engine = get_cached_sqlite_engine()
with engine.begin() as conn:
conn.execute(
_sa_update(_messages)
.where(
_messages.c.platform == platform,
_messages.c.native_message_id == str(native_message_id),
_messages.c.session_id.is_(None),
)
.values(session_id=session_id)
)
except Exception:
logger.debug("link_inbound_message_session: back-fill failed", exc_info=True)