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
"""Message-output semantics shared by every agent backend.
The visible Message and the lifecycle event it may cause are deliberately
separate. Live runtime paths carry explicit lifecycle authority; one quarantined
dispatcher fallback preserves older callers that still use terminal ``result``.
"""
from __future__ import annotations
import re
from dataclasses import dataclass, field, replace
from typing import Any, Mapping
from core.run_settlement import SETTLED_BY_BACKEND_REFRESH, SETTLED_BY_STOPPED
# Every trigger kind whose dispatch created an ``agent_runs`` row. Scheduled
# tasks, watches, webhooks, hooks and recovered Activities are all Harness runs
# and must reach the same result recorders as a direct ``vibe agent run``.
# Gating those recorders on ``agent_run`` alone is why every ``scheduled`` /
# ``watch`` row carries an empty ``result_text``.
HARNESS_TRIGGER_KINDS: frozenset[str] = frozenset(
{"agent_run", "scheduled", "watch", "webhook", "hook", "activity_recovery"}
)
# The subset whose ``task_execution_id`` *is* the run id. ``activity_recovery``
# is deliberately excluded: it builds its context with a synthetic
# ``activity:<backend>:<id>`` execution id, and its real run ids travel on the
# Activity completion output instead. Reading its ``task_execution_id`` as a run
# id addresses a write to a row that cannot exist.
HARNESS_RUN_ID_TRIGGER_KINDS: frozenset[str] = HARNESS_TRIGGER_KINDS - {"activity_recovery"}
# ``platform_specific`` key carrying the Harness prompt that should be echoed into
# the turn's IM conversation. The turn pipeline stages it; ``AgentService`` emits it
# once the runtime turn gate is acquired, so a turn queued behind another turn cannot
# announce its prompt while that other turn is still working.
HARNESS_PROMPT_ECHO_SPEC_KEY = "harness_prompt_echo_text"
# The echo is awaited WITH the runtime turn gate held, so a slow or unreachable IM
# API would delay the Harness turn itself plus every turn queued on that gate — an
# adapter's own budget is far longer than a turn start should ever wait (Telegram
# allows 60s per request). Bounded like the status-bubble post that follows it
# (``MessageDispatcher.begin_status_bubble``); the echo is optional, the turn is not.
HARNESS_PROMPT_ECHO_TIMEOUT_SECONDS = 5.0
@dataclass(frozen=True)
class MessageOutput:
"""Lifecycle and hidden provenance for one user-visible agent output."""
# This emit is its Turn's end event (``docs/plans/reply-and-turn-end.md``). It
# never decides the output's type: a reply is a ``result`` either way.
completes_turn: bool = False
completes_run: bool | None = None
detached: bool = False
idempotency_key: str | None = None
native_message_id_aliases: tuple[str, ...] = ()
activity_id: str | None = None
activity_ids: tuple[str, ...] = ()
activity_batch_id: str | None = None
causation_id: str | None = None
sequence: int | None = None
run_id: str | None = None
run_ids: tuple[str, ...] = ()
records_run_output: bool = True
requires_delivery_for_run_settlement: bool = False
settled_by: str | None = None
metadata: Mapping[str, Any] = field(default_factory=dict)
# ``messages.id`` of a row the backend already committed as its transcript (the
# Avibe Agent). Persistence then writes that row's display columns instead of
# inserting a second row; nothing else about delivery changes.
persisted_row_id: str | None = None
@property
def settles_run(self) -> bool:
"""Run completion defaults to legacy Turn completion unless separated."""
return self.completes_turn if self.completes_run is None else self.completes_run
def provenance(self, context: Any) -> dict[str, Any]:
spec = getattr(context, "platform_specific", None) or {}
trigger_kind = str(spec.get("task_trigger_kind") or "").strip()
inferred_run_id = (
str(spec.get("task_execution_id") or "").strip()
if trigger_kind in HARNESS_RUN_ID_TRIGGER_KINDS
else ""
)
values: dict[str, Any] = {
"turn_id": str(spec.get("turn_token") or "").strip() or None,
"activity_id": self.activity_id,
"activity_ids": list(self.activity_ids) or None,
"activity_batch_id": self.activity_batch_id,
"run_id": self.run_id or inferred_run_id or None,
"run_ids": list(self.run_ids) or None,
"causation_id": self.causation_id,
"sequence": self.sequence,
"output_id": self.idempotency_key,
"detached": self.detached,
}
values.update(dict(self.metadata))
return {key: value for key, value in values.items() if value is not None}
def native_message_id(self, context: Any) -> str | None:
"""Stable persistence identity without exposing protocol text to users."""
key = str(self.idempotency_key or "").strip()
if not key:
return None
spec = getattr(context, "platform_specific", None) or {}
target = spec.get("agent_session_target")
backend = str(
self.metadata.get("backend") or spec.get("vibe_agent_backend") or ""
).strip()
if not backend and isinstance(target, dict):
backend = str(target.get("agent_backend") or "").strip()
activity_lineage = (
f"activity-batch:{self.activity_batch_id}"
if self.activity_batch_id
else (f"activity:{self.activity_id}" if self.activity_id else "")
)
lineage = str(
activity_lineage
or self.run_id
or spec.get("task_execution_id")
or spec.get("agent_session_id")
or spec.get("agent_runtime_turn_key")
or "session"
).strip()
return f"agent-output:{backend or 'unknown'}:{lineage}:{key}"
# Mention neutralizers for text Avibe republishes into a channel on someone else's
# behalf (a Harness prompt echo, an upstream provider's error message). Quoting does
# not stop a renderer from resolving a broadcast, a username, or an id mention. The
# Discord client now resolves only user mentions (``USERS_ONLY_MENTIONS``), but other
# platforms have no such switch and a quoted ``<@user>`` would still ping that user,
# so the guard stays platform-agnostic. A zero-width space after the sigil keeps the text
# readable while leaving nothing for any renderer to resolve. Deliberately
# platform-agnostic: every adapter renders the same body, so ``@`` before a word
# character covers the Slack/Discord broadcasts AND a bare Telegram ``@username``
# (which ``TelegramFormatter.render`` HTML-escapes without defusing), and a new
# adapter inherits the guard instead of needing its own.
# A handle only at a word start, so ``[email protected]`` stays a usable address;
# a broadcast word anywhere, since a renderer may resolve ``x@everyone`` too.
_MENTION_SIGIL_PATTERN = re.compile(r"@(?=(?:everyone|here|channel)\b)|(?<![\w.+-])@(?=\w)", re.IGNORECASE)
_ID_MENTION_PATTERN = re.compile(r"<(?=[@!#&])")
_MENTION_BREAK = "\u200b"
def neutralize_mentions(text: str) -> str:
"""Make every mention in *text* inert without changing how it reads.
Covers every ``@`` sigil — the broadcast words (``@everyone`` / ``@here`` /
``@channel``) and a bare ``@username``, which Telegram resolves into a real
notification — plus the bracketed id forms both Slack (``<@U…>``, ``<!here>``,
``<#C…>``) and Discord (``<@id>``, ``<@&role>``) resolve.
"""
neutralized = _MENTION_SIGIL_PATTERN.sub("@" + _MENTION_BREAK, text or "")
return _ID_MENTION_PATTERN.sub("<" + _MENTION_BREAK, neutralized)
# Link defusers for text an untrusted party wrote but Avibe republishes under its own
# copy (an upstream provider's error message). A masked link lets the label dress an
# attacker-chosen URL as Avibe's own call to action: Markdown ``[label](url)`` on
# Discord, Telegram (``TelegramFormatter`` renders it to ``<a>``), and the Web UI, and
# Slack's ``<url|label>``. Parsing destinations is a losing game (balanced parens,
# escapes, angle-bracket forms), so the syntax itself is broken instead: a zero-width
# space between ``]`` and ``(`` and after every ``<`` leaves no renderer a link to
# build, and the text, destination included, still reads exactly as written.
_MARKDOWN_LINK_JOIN_PATTERN = re.compile(r"\](?=\s*\()")
# A lone surrogate (``\ud800`` in upstream JSON) survives parsing but cannot be
# encoded, so the notification would fail to persist; U+FFFD keeps the rest.
_LONE_SURROGATE_PATTERN = re.compile(r"[\ud800-\udfff]")
def plain_untrusted_text(text: str) -> str:
"""Make untrusted *text* render as the plain words it holds on every platform.
Mentions are neutralized, masked links defused, and unencodable code points
replaced, so the result can be sent and persisted under Avibe's own copy.
"""
text = _LONE_SURROGATE_PATTERN.sub("\ufffd", text or "")
text = _MARKDOWN_LINK_JOIN_PATTERN.sub("]" + _MENTION_BREAK, text)
text = _MENTION_SIGIL_PATTERN.sub("@" + _MENTION_BREAK, text)
# Every ``<``, not only the id-mention forms: Slack also builds ``<url|label>``.
return text.replace("<", "<" + _MENTION_BREAK)
def output_for_message(message_type: str, output: MessageOutput | None) -> MessageOutput:
"""Normalize output semantics at the legacy dispatcher boundary.
Live backend and shared-core paths provide explicit ``MessageOutput``. The
result fallback remains only as a compatibility adapter for external callers
while the visible Message role and lifecycle authority evolve separately.
"""
if output is not None:
return output
if message_type == "result":
return terminal_turn_output()
return MessageOutput(completes_turn=False, completes_run=False)
def terminal_turn_output() -> MessageOutput:
"""Explicitly grant one output authority to settle its Turn and Run."""
return MessageOutput(completes_turn=True, completes_run=True)
def terminal_output_for(request: Any) -> MessageOutput:
"""Use a request's explicit output policy or the terminal Turn default."""
output = getattr(request, "output", None)
return output if isinstance(output, MessageOutput) else terminal_turn_output()
def stop_output_for(request: Any) -> MessageOutput:
"""A user stop's synthetic terminal result: ends the Turn, does NOT own the Run.
Every backend answers an acknowledged stop with an empty silent ``result`` so the
dot settles to idle and the SSE waiter closes through the one outbound chokepoint.
That output is the *turn's* release, not the *run's* result: nobody produced an
answer, the user called the work off. Sending it with the terminal-turn default
(``completes_run=True``) made the dispatcher record the run ``succeeded`` from an
empty body — and, because the terminal write lands before the stop's own guarded
write, first-writer-wins meant a user-ended run was reported as a success.
So: ``completes_run=False`` keeps the empty result out of the run's terminal
state, while ``settled_by`` names the reason on the turn sink so the settlement
lanes reach the writer that already knows a stop is ``canceled`` with
``interrupt_reason=stopped`` (``SETTLEMENT_TERMINAL_STATUS``). Without the reason,
"does not settle the run" would read as ``turn_only_result`` — the Activity case,
where somebody else genuinely owns the row — and the run would sit ``running``
until the staleness sweep called it ``orphaned``.
Built with ``replace`` so a request carrying its own output policy (Activity
lineage, an explicit ``run_id``) keeps it; only the lifecycle is overridden.
"""
return replace(
terminal_output_for(request),
completes_turn=True,
completes_run=False,
settled_by=SETTLED_BY_STOPPED,
)
def contained_teardown_output_for(request: Any) -> MessageOutput:
"""A service-initiated backend teardown's terminal result: infrastructure, not fault.
The service killed this backend runtime itself -- idle eviction, duplicate reap,
a rolling ``agents.*`` reconciliation. #1202 taught the Claude paths to recognize
that signal and stop reporting it as a user-visible backend error or a Model Hub
source-health failure. It did not change what the emit that follows still says:
an ordinary ``result`` whose only lifecycle authority is the terminal-turn
default, so the dispatcher terminalized an ``agent_runs`` row from an empty body
and the durable Turn read ``failed`` -- indistinguishable from a backend that
actually broke, while the bubble said nothing at all.
Same shape as ``stop_output_for``, different reason. ``completes_run=False``
keeps the empty body out of ``_record_agent_run_terminal_result``, and
``settled_by`` routes the release through the settlement lane instead, where
``SETTLEMENT_TERMINAL_STATUS`` already maps ``backend_refresh`` to ``failed``
with ``interrupt_reason=backend_refresh``. That preserves invariant 2 of
``docs/plans/harness-run-reliability.md`` -- an infrastructure interruption is
``failed`` with a STRUCTURED cause, never silently swallowed -- while making the
cause distinguishable from a backend that actually broke.
``backend_refresh`` rather than ``interrupted`` because it already names this
exact boundary: a live Agent runtime retired inside an otherwise healthy
service. The same name also drives the TURN-level surfaces through
``NON_COMPLETING_TURN_SETTLEMENTS``, which record it as ``canceled`` -- the word
``release_for_backend_refresh`` already uses when it retires a live Turn
directly, so one teardown reads the same however it reached the row.
Nothing here is Claude-specific. Any backend whose cleanup can classify its own
teardown gets the same semantics by emitting through this factory.
"""
return replace(
terminal_output_for(request),
completes_turn=True,
completes_run=False,
settled_by=SETTLED_BY_BACKEND_REFRESH,
)