Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

12.5 KB
Raw Blame
"""Partner backend — consult one of the user's own partners as a subagent.

Unlike the local-CLI backends (Claude Code / Codex) this drives no subprocess:
it puts the question to a running partner through the partner manager's web
entry point, exactly as if the user opened a new session on the partner page.
The partner answers with its own chat loop — its soul, library and skills — and
uses the same live web turn as the native partner chat. The sidebar subscribes
to that turn directly; coarse events remain available to the outer chat trace.

Session continuity is the whole point of the design. ``session_id`` here IS the
*partner session key*. The first consult of a DeepTutor chat session has none,
so we mint a fresh ``dt-…`` key and return it; the cross-turn registry
(:mod:`deeptutor.services.subagent.sessions`) remembers it against
(chat session, connection), so every later consult in the same DeepTutor chat —
within one turn or across turns — resumes the SAME partner session. The partner
page then sees one complete history session per DeepTutor chat, titled from the
first consult's question.
"""

from __future__ import annotations

import asyncio
from contextlib import suppress
import logging
from typing import TYPE_CHECKING
import uuid

from deeptutor.services.subagent.base import OnEvent, SubagentBackend
from deeptutor.services.subagent.config import BackendConfig
from deeptutor.services.subagent.types import (
    EVENT_ERROR,
    EVENT_REASONING,
    EVENT_TEXT,
    EVENT_TOOL,
    EVENT_TOOL_RESULT,
    ConsultResult,
    DetectResult,
    SubagentEvent,
)

if TYPE_CHECKING:  # avoid importing the core/partner packages at module load
    from deeptutor.core.stream import StreamEvent

logger = logging.getLogger(__name__)

PARTNER_BACKEND_KIND = "partner"

# Cap on how much of a tool-call's args / a tool result we echo into the trace
# line — keeps the sidebar readable without dropping the event.
_MAX_LINE_CHARS = 600


class PartnerBackend(SubagentBackend):
    """Consult one of the user's partners as a delegate, in-process."""

    kind = PARTNER_BACKEND_KIND
    display_name = "Partner"
    cli_command = ""
    local_cli = False

    async def detect(self) -> DetectResult:
        # Partners are a built-in feature, not a machine-local CLI: ``available``
        # only gates the connect-CLI modal, which this backend deliberately sits
        # out (partners are connected from the partner list instead).
        return DetectResult(
            kind=self.kind,
            display_name=self.display_name,
            available=False,
            detail="Partners are connected from your partner list, not detected on this machine.",
        )

    async def consult(
        self,
        question: str,
        *,
        on_event: OnEvent,
        cwd: str | None = None,  # noqa: ARG002 — CLI-only; partners have no cwd
        session_id: str | None = None,
        config: BackendConfig | None = None,  # noqa: ARG002 — partner runs its own soul
        images: list[str] | None = None,
        partner_id: str | None = None,
    ) -> ConsultResult:
        pid = str(partner_id or "").strip()
        if not pid:
            return ConsultResult(success=False, error="No partner is bound to this connection.")

        # Re-check on every consult: a connection may outlive the grant that
        # created it, and stale metadata must never remain an authorization path.
        from deeptutor.multi_user.partner_access import assert_partner_allowed

        try:
            assert_partner_allowed(pid)
        except Exception as exc:
            detail = getattr(exc, "detail", None) or str(exc)
            return ConsultResult(success=False, error=str(detail))

        from deeptutor.services.partners import get_partner_manager

        manager = get_partner_manager()
        if not manager.partner_exists(pid):
            return ConsultResult(success=False, error=f"Partner '{pid}' no longer exists.")

        # Bring the partner online if it isn't already (auto-start partners are).
        instance = manager.get_partner(pid)
        if instance is None or not instance.running:
            try:
                await manager.start_partner(pid)
            except Exception as exc:  # pragma: no cover - defensive
                logger.warning("Failed to start partner %s for consult: %s", pid, exc)
                return ConsultResult(success=False, error=f"Could not start partner '{pid}': {exc}")

        # ``session_id`` is the partner session key. None on the first consult of
        # a DeepTutor chat → mint a stable, colon-free key; the registry threads
        # it through every later consult so they all land in one partner session.
        session_key = str(session_id or "").strip() or f"dt-{uuid.uuid4().hex[:12]}"

        events = 0
        # Per-stream state shared across the loop's events:
        # - text/reason: the chat loop streams CONTENT/THINKING as *incremental*
        #   deltas; we accumulate per call_id and emit the running full text (the
        #   CLI backends do the same) so the row grows instead of being wiped by
        #   each chunk.
        # - pending_tools: the loop dispatches tools in PARALLEL — all TOOL_CALL
        #   events, then all TOOL_RESULT events — so a call and its result aren't
        #   adjacent. We hold each call (keyed by its call_id, shared with its
        #   result) and emit it back-to-back with its result, so the trace reads
        #   as call → result pairs.
        state: dict[str, dict[str, str]] = {
            "text": {},
            "reason": {},
            "pending_tools": {},
        }

        async def relay(event: "StreamEvent") -> None:
            nonlocal events
            for out in _to_subagent_events(event, state):
                events += 1
                await on_event(out)

        # A user may still be finishing a sidebar follow-up. Do not mistake
        # that response for the answer to this new consultation question.
        existing = manager.subscribe_web_turn(pid, session_key)
        if existing is not None and existing.task is not None:
            with suppress(asyncio.CancelledError):
                # Shield the user's turn from cancellation of this waiter.
                await asyncio.shield(existing.task)
            if asyncio.current_task().cancelling():
                raise asyncio.CancelledError

        live = manager.start_web_turn(pid, session_key, question, media=list(images or []))
        queue = live.subscribe()
        identity = {"partner_id": pid, "partner_session_key": session_key}
        reply = ""
        failure = ""
        try:
            # Publish only after the native turn exists so the sidebar can
            # attach immediately, replay its backlog and restore after refresh.
            await on_event(SubagentEvent("log", pid, meta=identity))
            while True:
                frame = await queue.get()
                kind = frame.get("type")
                if kind == "stream_event":
                    from deeptutor.core.stream import StreamEvent, StreamEventType

                    raw = frame["event"]
                    await relay(
                        StreamEvent(
                            type=StreamEventType(raw["type"]),
                            content=raw.get("content", ""),
                            metadata=raw.get("metadata") or {},
                        )
                    )
                elif kind == "content":
                    reply = str(frame.get("content") or "")
                elif kind == "error":
                    failure = str(frame.get("content") or "Partner request failed.")
                elif kind == "stopped":
                    failure = "Partner response stopped."
                    break
                elif kind == "done":
                    break
        except asyncio.CancelledError:
            if live.task is not None and not live.task.done():
                live.task.cancel()
                with suppress(asyncio.CancelledError):
                    await live.task
            raise
        finally:
            live.subscribers.discard(queue)
        if failure:
            return ConsultResult(
                session_id=session_key, success=False, error=failure, event_count=events
            )

        # Defensive: surface any tool call that never produced a result event so
        # it isn't silently lost (every tool normally emits one).
        for label in state["pending_tools"].values():
            events += 1
            await on_event(SubagentEvent(EVENT_TOOL, label))

        reply = (reply or "").strip()
        return ConsultResult(
            final_text=reply,
            session_id=session_key,
            success=bool(reply),
            event_count=events,
            error="" if reply else "the partner produced no reply",
        )


def _to_subagent_events(
    event: "StreamEvent",
    state: dict[str, dict[str, str]],
) -> list[SubagentEvent]:
    """Map a partner chat-loop ``StreamEvent`` to zero or more subagent events.

    Renders the partner's run like the CLI backends do — a tool call, its result,
    streamed thinking and the streamed answer — so the sidebar reads as a faithful
    transcript:

    * ``CONTENT`` / ``THINKING`` arrive as incremental deltas, so we accumulate
      per ``call_id`` (in ``state``) and emit the running full text under a
      per-stream ``merge_id`` (the row grows in place, never overwritten by a
      single chunk).
    * A ``TOOL_CALL`` (name + args/query) and its ``TOOL_RESULT`` share a
      ``call_id`` in the loop, but the loop dispatches tools in parallel, so the
      calls and results don't interleave. We hold each call in
      ``state["pending_tools"]`` and emit it immediately before its result, as
      two adjacent rows — so every result sits under the call it belongs to.
    * Pure status/bookkeeping (``PROGRESS`` call-status, ``RESULT`` marker,
      ``DONE``/``SESSION*``) carries no trace value and is dropped.
    """
    from deeptutor.core.stream import StreamEventType

    meta = event.metadata or {}
    call_id = str(meta.get("call_id") or "")
    text = event.content or ""
    etype = event.type
    pending = state["pending_tools"]

    if etype == StreamEventType.CONTENT:
        if not text:
            return []
        running = state["text"][call_id] = state["text"].get(call_id, "") + text
        merge = {"merge_id": f"text:{call_id}"} if call_id else {}
        return [SubagentEvent(EVENT_TEXT, running, meta=merge)]
    if etype == StreamEventType.THINKING:
        if not text.strip():
            return []
        running = state["reason"][call_id] = state["reason"].get(call_id, "") + text
        merge = {"merge_id": f"reason:{call_id}"} if call_id else {}
        return [SubagentEvent(EVENT_REASONING, running, meta=merge)]
    if etype == StreamEventType.TOOL_CALL:
        name = text.strip() or str(meta.get("tool_name") or "tool")
        args = _compact(meta.get("args"))
        label = f"{name} {args}" if args else name
        if call_id:
            # Defer: emit it right before its result so the pair stays adjacent.
            pending[call_id] = label
            return []
        return [SubagentEvent(EVENT_TOOL, label)]
    if etype == StreamEventType.TOOL_RESULT:
        out = _flush_pending_call(pending, call_id)
        body = text.strip()
        if body:
            out.append(SubagentEvent(EVENT_TOOL_RESULT, _truncate(body)))
        return out
    if etype == StreamEventType.ERROR:
        # An error can close out a pending tool call — surface the call first.
        out = _flush_pending_call(pending, call_id)
        if text.strip():
            out.append(SubagentEvent(EVENT_ERROR, text.strip()))
        return out
    # PROGRESS (call-status duplicates the tool rows), RESULT (final answer,
    # returned separately), SOURCES, DONE, SESSION* and WAIT_FOR_INPUT carry no
    # trace value here.
    return []


def _flush_pending_call(pending: dict[str, str], call_id: str) -> list[SubagentEvent]:
    """Emit (and clear) the buffered tool-call row for ``call_id``, if any."""
    label = pending.pop(call_id, "") if call_id else ""
    return [SubagentEvent(EVENT_TOOL, label)] if label else []


def _compact(args: object) -> str:
    if not args:
        return ""
    import json

    try:
        text = json.dumps(args, ensure_ascii=False) if not isinstance(args, str) else args
    except (TypeError, ValueError):
        text = str(args)
    return _truncate(text.strip())


def _truncate(text: str) -> str:
    return text if len(text) <= _MAX_LINE_CHARS else text[: _MAX_LINE_CHARS - 1] + "…"


__all__ = ["PARTNER_BACKEND_KIND", "PartnerBackend"]