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
"""Shared turn-dispatch entry point.
``dispatch_turn`` is the single business-level function for "run an agent
turn against a session". All three callers go through it so the IM
adapter, the CLI, and the upcoming Web UI / N3 socket path share one
implementation:
* **IM adapter** — same process as ``Controller``; calls ``await
dispatch_turn(controller, context, text)`` directly. Today wired in
``Controller._wire_im_callbacks`` so every Slack / Discord / Telegram
/ Lark / WeChat / avibe inbound message lands here.
* **CLI** (``vibe agent run --sync``, future N3 socket path) — separate
process; the internal HTTP endpoint built in ``core/internal_server.py``
(commit C4) will wrap this with SSE chunked output.
* **Scheduled / hook / watch runs** — already routed through
``MessageHandler.handle_scheduled_message`` by ``ScheduledTaskService``;
this layer just gives them a stable entry name.
The implementation today is a thin delegate so we can pin the public
shape now and keep behavior byte-identical with the existing
``MessageHandler._handle_turn`` path. Streaming (``on_chunk``) is
reserved for the N3 work — see ``docs/plans/workbench-dispatch-architecture.md``
§7. Until that lands the callback is silently unused, which is fine
because no caller passes it yet.
"""
from __future__ import annotations
import asyncio
import logging
import uuid
from dataclasses import dataclass
from typing import Awaitable, Callable, Optional, TYPE_CHECKING
from core.run_settlement import (
SETTLED_BY_NO_TERMINAL_RESULT,
SETTLED_BY_REFUSED_CONCURRENT_TURN,
)
from core.message_context import TERMINAL_COMMIT_KEY, resolve_turn_sink_key
from core.native_dispatch_phase import backend_dispatch_attempted
from modules.im import MessageContext
if TYPE_CHECKING: # pragma: no cover - typing-only
from core.controller import Controller
logger = logging.getLogger(__name__)
# Streaming hook for the N3 socket path. Receives one envelope per
# ``emit_agent_message`` notify/result emit for the turn, on the same loop.
ChunkCallback = Callable[[dict], Awaitable[None]]
SOURCE_HUMAN = "human"
SOURCE_SCHEDULED = "scheduled"
@dataclass(frozen=True)
class TurnDispatchOutcome:
"""What a dispatched turn produced, and how its waiter was released.
``settled_by`` is the settlement vocabulary from ``core.run_settlement``. It is
``None`` for exactly one case — a caller that passed no ``on_chunk``, so no sink
was ever registered and there was nothing to wait on. Every streaming caller
gets a real value, including the concurrent-turn refusal below which returns
before a sink exists.
A caller that owns a durable record of the turn (``ScheduledTaskService`` and
its ``agent_runs`` row) MUST branch on this: only
``SETTLED_BY_TERMINAL_RESULT`` means "the backend emitted a terminal result, so
the out-of-band writer will settle the record". Every other value means no
terminal result is coming and the caller has to settle it itself.
"""
error: Optional[str]
settled_by: Optional[str]
backend_dispatch_attempted: Optional[bool] = None
async def dispatch_turn(
controller: "Controller",
context: MessageContext,
text: str,
*,
source: str = SOURCE_HUMAN,
on_chunk: Optional[ChunkCallback] = None,
logical_turn_id: str | None = None,
lifecycle_snapshot: object | None = None,
) -> Optional[str]:
"""Run one agent turn for ``context`` and return the primary message id.
Thin wrapper over :func:`dispatch_turn_with_outcome` for the callers that only
need the error/message-id channel (IM, web Chat, CLI).
"""
outcome = await dispatch_turn_with_outcome(
controller,
context,
text,
source=source,
on_chunk=on_chunk,
logical_turn_id=logical_turn_id,
lifecycle_snapshot=lifecycle_snapshot,
)
return outcome.error
async def dispatch_turn_with_outcome(
controller: "Controller",
context: MessageContext,
text: str,
*,
source: str = SOURCE_HUMAN,
on_chunk: Optional[ChunkCallback] = None,
logical_turn_id: str | None = None,
lifecycle_snapshot: object | None = None,
) -> TurnDispatchOutcome:
"""Run one agent turn for ``context`` and report how its waiter was released.
``source`` selects between the human-initiated and scheduler-initiated
paths in ``MessageHandler``; today they only differ in source tagging.
``lifecycle_snapshot`` is a process-local capture token passed explicitly
to the handler; it never enters the JSON-oriented platform payload.
``on_chunk`` (the N3 socket / web Chat path) receives each notify/result
emit for this turn as it happens. Because the agent backends are
fire-and-forget — ``handle_user_message`` returns once the message is sent
and the reply streams in later on a background receiver task — we register
a per-session sink and hold here until the turn emits its REAL terminal
result, however long that takes, so the caller doesn't close the SSE stream
before any chunk arrives. There is NO turn-duration timeout: an agent turn
may legitimately run for hours, and the controller must never kill it on a
timer. A user Stop/cancel cancels the task, propagating ``CancelledError``
out of ``done.wait()``; the ``finally`` still pops the sink.
"""
handler = controller.message_handler
async def _run() -> Optional[str]:
nonlocal lifecycle_snapshot
snapshot = lifecycle_snapshot
lifecycle_snapshot = None
snapshot_options = (
{"lifecycle_snapshot": snapshot}
if snapshot is not None
else {}
)
if source == SOURCE_SCHEDULED:
return await handler.handle_scheduled_message(
context,
text,
**snapshot_options,
)
return await handler.handle_user_message(
context,
text,
**snapshot_options,
)
if on_chunk is None:
# IM / CLI: fire-and-forget; no live stream to hold open.
return TurnDispatchOutcome(
error=await _run(),
settled_by=None,
backend_dispatch_attempted=backend_dispatch_attempted(context),
)
# Thread-scoped, NOT ``_get_session_key`` (channel-scoped): this gate refuses
# a turn when the slot is taken, so a channel-wide key made one busy Telegram
# forum topic / Slack thread refuse every sibling thread's turn.
session_key = resolve_turn_sink_key(controller, context)
if controller.get_turn_sink(session_key) is not None:
# Serialize per session. A streaming turn is already in flight for
# this session (a second browser tab, or a resend before the first
# finishes). The session's single agent client can't run two turns at
# once, and two live sinks under one session key would cross-feed
# chunks and complete each other early. Refuse the concurrent turn
# with a terminal chunk instead of racing — the in-flight turn keeps
# streaming undisturbed.
await on_chunk({"kind": "error", "text": controller._t("error.streamTurnInProgress"), "message_id": None})
# No sink was registered for THIS turn, so there is no sink to carry the
# settlement — report it directly. A caller holding a durable record (an
# ``agent_runs`` row) must settle it: this turn never reached a backend, so
# no terminal result will ever arrive for it.
return TurnDispatchOutcome(
error=None,
settled_by=SETTLED_BY_REFUSED_CONCURRENT_TURN,
backend_dispatch_attempted=False,
)
# Tag this turn with a unique token, stamped into the context the agent
# receiver will carry. ``_stream_chunk`` only forwards an emit to the sink
# when the emit's context token matches the registered sink's token, so a
# late straggler emit from a PREVIOUS (stopped / timed-out) turn can't
# cross-feed into this turn's live stream or prematurely complete it.
# Fail-open: emits without a token still flow (byte-identical to before).
existing_turn_token = str(
(context.platform_specific or {}).get("turn_token") or ""
).strip()
turn_token = (
str(logical_turn_id or "").strip()
or existing_turn_token
or uuid.uuid4().hex
)
if context.platform_specific is None:
context.platform_specific = {}
context.platform_specific["turn_token"] = turn_token
# The backend may bind the concrete agent Session onto this context after
# dispatch starts. Preserve the slot selected before registration so every
# later receiver/terminal path resolves the same sink for this turn.
context.platform_specific["turn_sink_key"] = session_key
done = asyncio.Event()
controller.register_turn_sink(
session_key,
on_chunk=on_chunk,
done_event=done,
turn_token=turn_token,
context=context,
)
try:
result = await _run()
# Wait for the agent's REAL terminal result, however long it takes — a
# turn may legitimately run for hours, so there is NO timeout here. A
# user Stop/cancel cancels this task; the ``CancelledError`` propagates
# out of ``done.wait()`` and the ``finally`` below pops the sink.
await done.wait()
# Read the settlement off OUR sink before the ``finally`` pops it. A sink
# released without a terminal result (``mark_turn_complete`` / an external
# stop) leaves no other trace, so this is the only place the distinction
# survives. Default defensively to "no terminal result": an unexplained
# release must never be reported as a healthy turn.
sink = controller.get_turn_sink(session_key)
settled_by = SETTLED_BY_NO_TERMINAL_RESULT
if isinstance(sink, dict) and sink.get("done_event") is done:
settled_by = str(sink.get("settled_by") or SETTLED_BY_NO_TERMINAL_RESULT)
return TurnDispatchOutcome(
error=result,
settled_by=settled_by,
backend_dispatch_attempted=backend_dispatch_attempted(context),
)
finally:
# A terminal emit that reached its Turn write left that write's evidence
# on our sink. Hand it to the runner on every exit, cancellation included,
# since the sink goes away here.
sink = controller.get_turn_sink(session_key)
if isinstance(sink, dict) and sink.get("done_event") is done:
committed = sink.get(TERMINAL_COMMIT_KEY)
if isinstance(committed, dict):
if context.platform_specific is None:
context.platform_specific = {}
context.platform_specific[TERMINAL_COMMIT_KEY] = {
"settled_by": str(sink.get("settled_by") or ""),
"evidence": dict(committed),
}
# Pass our own done event so a turn that was superseded by a newer
# concurrent turn doesn't evict the newer turn's sink on cleanup.
controller.pop_turn_sink(session_key, done)