DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
"""Partners management API.
A partner is an IM-connected companion driven by the chat agent loop.
This router owns: partner CRUD + lifecycle, the soul library, channel
config (schema-driven), asset provisioning (KB / skills / notebooks copied
into the partner workspace), tool configuration, history, and the web chat
entry points (HTTP / SSE / WebSocket).
"""
from __future__ import annotations
import asyncio
import base64
import binascii
from contextlib import nullcontext
from datetime import datetime
import json
import logging
from typing import Any, AsyncGenerator, Literal
from uuid import uuid4
from fastapi import APIRouter, Depends, HTTPException, Query, WebSocket, WebSocketDisconnect
from fastapi.responses import StreamingResponse
from pydantic import BaseModel, ConfigDict, Field, ValidationError
from deeptutor.api.routers.auth import require_admin
from deeptutor.app.container import get_application_container
from deeptutor.multi_user.context import get_current_user
from deeptutor.multi_user.partner_access import (
assert_partner_manageable,
can_manage_partner,
can_use_partner,
identity_card,
visible_partners,
)
from deeptutor.partners.config.paths import get_partner_media_dir
from deeptutor.partners.helpers import safe_filename
from deeptutor.runtime.coordination import BackgroundCommandKind
from deeptutor.services.i18n import t
from deeptutor.services.partners import (
get_partner_manager,
slugify_partner_id,
slugify_soul_id,
)
from deeptutor.services.partners.channel_onboarding import (
ChannelOnboardingError,
get_channel_onboarding_manager,
)
from deeptutor.services.partners.drafts import PartnerDraftStore
from deeptutor.services.partners.manager import (
LEGACY_GLOBAL_DELIVERY_KEYS,
PartnerConfig,
PartnerInstance,
PartnerStaleSessionError,
PartnerTurnBusyError,
mask_channel_secrets,
strip_legacy_global_delivery,
)
from deeptutor.services.partners.runtime_status import (
get_partner_runtime_status_repository,
)
from deeptutor.services.partners.web_continuity import (
fresh_web_session_key,
get_web_continuity,
move_active_web_session,
set_web_continuity,
validate_session_key,
)
from deeptutor.services.partners.workspace import (
list_assets,
provision_assets,
read_soul,
remove_asset,
strip_frontmatter,
write_soul,
)
logger = logging.getLogger(__name__)
router = APIRouter()
ws_router = APIRouter()
# ── Access guards ──────────────────────────────────────────────
#
# The router is merely authenticated; each route declares what it needs of the
# caller. Two levels, matching ``multi_user.partner_access``: *use* (hold a
# conversation) and *manage* (configure, provision, delete). A partner the
# caller may not use reads as absent rather than forbidden, so nobody can
# enumerate other people's partners by probing ids.
def usable_partner(partner_id: str) -> str:
"""Path dependency: the partner exists and the caller may talk to it."""
if not get_partner_manager().partner_exists(partner_id) or not can_use_partner(partner_id):
raise HTTPException(status_code=404, detail=t("api.partner_not_found"))
return partner_id
def manageable_partner(partner_id: str = Depends(usable_partner)) -> str:
"""Path dependency: the caller owns the partner (or is an admin)."""
assert_partner_manageable(partner_id)
return partner_id
_USABLE = [Depends(usable_partner)]
_MANAGEABLE = [Depends(manageable_partner)]
# Per-partner async locks used to dedupe concurrent WebSocket-driven
# auto-starts (start_partner short-circuits when running, but that check is
# not async-safe under concurrent connections).
_start_locks: dict[str, asyncio.Lock] = {}
_start_locks_mutex = asyncio.Lock()
_draft_confirm_locks: dict[tuple[str, str], asyncio.Lock] = {}
_draft_confirm_locks_mutex = asyncio.Lock()
async def _get_start_lock(partner_id: str) -> asyncio.Lock:
async with _start_locks_mutex:
lock = _start_locks.get(partner_id)
if lock is None:
lock = asyncio.Lock()
_start_locks[partner_id] = lock
return lock
async def _get_draft_confirm_lock(draft_id: str) -> asyncio.Lock:
key = (get_current_user().id, draft_id)
async with _draft_confirm_locks_mutex:
lock = _draft_confirm_locks.get(key)
if lock is None:
lock = asyncio.Lock()
_draft_confirm_locks[key] = lock
return lock
async def _request_partner_control(
kind: BackgroundCommandKind,
partner_id: str,
**payload: Any,
) -> dict[str, Any] | None:
"""Send lifecycle work to the leader in multi-worker mode.
``None`` means this process may execute the operation locally. Otherwise
the returned shared status was written by the leader after the command.
"""
container = get_application_container()
if container.settings.backend_workers <= 1:
return None
if await container.coordinator.leader_id() == container.worker_id:
return None
command = await container.coordinator.submit_background_command(
kind,
{"partner_id": partner_id, **payload},
)
if command is None:
raise HTTPException(status_code=409, detail="Duplicate Partner lifecycle command")
deadline = asyncio.get_running_loop().time() + 20.0
repository = get_partner_runtime_status_repository()
while asyncio.get_running_loop().time() < deadline:
status = repository.get(partner_id)
if status and float(status.get("runtime_updated_at") or 0) >= command.created_at:
state = str(status.get("runtime_state") or "")
if kind == BackgroundCommandKind.PARTNER_START and status.get("running"):
return status
if kind == BackgroundCommandKind.PARTNER_STOP and not status.get("running"):
return status
if kind == BackgroundCommandKind.PARTNER_RELOAD and state in {
"running",
"reload_failed",
}:
if state == "reload_failed":
raise HTTPException(
status_code=500,
detail=f"Failed to reload channels: {status.get('last_reload_error')}",
)
return status
await asyncio.sleep(0.05)
raise HTTPException(status_code=503, detail="Partner leader did not process the command")
async def _ensure_running_partner(
partner_id: str,
*,
allow_stopped: bool = False,
) -> PartnerInstance:
mgr = get_partner_manager()
instance = mgr.get_partner(partner_id)
if instance and instance.running:
return instance
config = mgr.load_config(partner_id)
if config is None:
raise HTTPException(status_code=404, detail=t("api.partner_not_found"))
if not allow_stopped and not mgr.auto_start_enabled(partner_id, default=False):
raise HTTPException(status_code=409, detail=t("api.partner_stopped_start_required"))
lock = await _get_start_lock(partner_id)
async with lock:
instance = mgr.get_partner(partner_id)
if instance and instance.running:
return instance
if not allow_stopped and not mgr.auto_start_enabled(partner_id, default=False):
raise HTTPException(status_code=409, detail=t("api.partner_stopped_start_required"))
try:
return await mgr.start_partner(partner_id, config)
except RuntimeError as exc:
raise HTTPException(status_code=500, detail=str(exc)) from None
except Exception as exc:
logger.exception("Failed to auto-start partner '%s'", partner_id)
raise HTTPException(status_code=500, detail="Failed to start partner") from exc
# ── Request models ─────────────────────────────────────────────
class SoulSpec(BaseModel):
"""Where a new partner's soul comes from."""
source: Literal["default", "library", "persona", "custom"] = "default"
id: str | None = None # library soul id, or persona name
content: str | None = None # custom markdown
class AssetSpec(BaseModel):
knowledge_bases: list[str] = Field(default_factory=list)
skills: list[str] = Field(default_factory=list)
notebooks: list[str] = Field(default_factory=list)
class CreatePartnerRequest(BaseModel):
workspace_id: str = ""
partner_id: str | None = None
name: str = Field(..., min_length=1)
description: str | None = None
soul: SoulSpec | None = None
channels: dict | None = None
llm_selection: dict[str, str] | None = None
backup_llm_selection: dict[str, str] | None = None
language: str | None = None
emoji: str | None = None
color: str | None = None
avatar: str | None = None
enabled_tools: list[str] | None = None
builtin_tools: list[str] | None = None
# Omitting ``mcp_tools`` creates the partner with MCP off (the config
# default); ``null`` is the deliberate opt-in to every configured MCP tool.
mcp_tools: list[str] | None = []
assets: AssetSpec | None = None
start: bool = True
class ConfirmPartnerDraftRequest(BaseModel):
"""Editable fields accepted by the explicit draft-confirmation step."""
name: str | None = Field(default=None, min_length=1)
description: str | None = None
soul: str | None = None
language: str | None = None
emoji: str | None = None
color: str | None = None
start: bool = True
class UpdatePartnerRequest(BaseModel):
workspace_id: str | None = None
name: str | None = None
description: str | None = None
channels: dict | None = None
llm_selection: dict[str, str] | None = None
backup_llm_selection: dict[str, str] | None = None
language: str | None = None
emoji: str | None = None
color: str | None = None
avatar: str | None = None
enabled_tools: list[str] | None = None
builtin_tools: list[str] | None = None
mcp_tools: list[str] | None = None
class SoulUpdateBody(BaseModel):
content: str
class AssetAddRequest(AssetSpec):
pass
class ChatAttachmentRequest(BaseModel):
type: str = "file"
url: str = ""
base64: str = ""
filename: str = ""
mime_type: str = ""
class ChatMessageRequest(BaseModel):
model_config = ConfigDict(populate_by_name=True)
content: str = ""
session_id: str | None = None
session_key: str | None = None
chat_id: str | None = None
attachments: list[ChatAttachmentRequest] = Field(default_factory=list)
llm_selection: dict[str, str] | None = Field(default=None, alias="llmSelection")
class SessionKeyBody(BaseModel):
session_key: str = Field(..., min_length=1)
class SessionBranchBody(BaseModel):
source_key: str = Field(..., min_length=1)
new_key: str = Field(..., min_length=1)
class WebContinuityBody(BaseModel):
enabled: bool
session_key: str | None = None
class SoulCreateRequest(BaseModel):
id: str
name: str
content: str
class SoulTemplateUpdateRequest(BaseModel):
name: str | None = None
content: str | None = None
class ChannelOnboardingStartRequest(BaseModel):
channel: Literal["feishu", "wecom"]
# ── Validation helpers ─────────────────────────────────────────
def _validate_channels_payload(channels: dict) -> None:
"""Reject malformed channel configs at the API boundary (422).
``ChannelsConfig`` intentionally allows plugin-shaped extras, so it only
validates the top-level container. Every discovered channel must also be
checked with its own Pydantic config model; otherwise a bad field type is
saved successfully and the listener merely disappears during reload.
"""
from deeptutor.partners.config.schema import ChannelsConfig
legacy_keys = sorted(k for k in channels if k in LEGACY_GLOBAL_DELIVERY_KEYS)
if legacy_keys:
raise HTTPException(
status_code=422,
detail={
"message": (
"Delivery flags are configured per channel; remove top-level "
f"channel keys: {', '.join(legacy_keys)}"
)
},
)
try:
ChannelsConfig(**channels)
except ValidationError as exc:
raise HTTPException(
status_code=422,
detail={"message": t("api.invalid_channels_config"), "errors": exc.errors()},
) from None
except TypeError as exc:
raise HTTPException(
status_code=422,
detail=f"{t('api.invalid_channels_config')}: {exc}",
) from None
from deeptutor.api.routers._partners_channel_schema import resolve_config_model
from deeptutor.partners.channels.registry import discover_all
nested_errors: list[dict[str, Any]] = []
discovered = discover_all()
for name, section in channels.items():
channel_cls = discovered.get(name)
if channel_cls is None:
# Preserve configs for optional/external channels that are not
# installed in this process. Their runtime status explains that
# the implementation is unavailable.
continue
model = resolve_config_model(channel_cls)
if model is None:
continue
try:
model.model_validate(section)
except ValidationError as exc:
for error in exc.errors(include_url=False):
nested_errors.append(
{
**error,
"loc": (name, *error.get("loc", ())),
}
)
if nested_errors:
raise HTTPException(
status_code=422,
detail={
"message": t("api.invalid_channels_config"),
"errors": nested_errors,
},
)
empty_allow_lists = sorted(
name
for name, section in channels.items()
if isinstance(section, dict)
and section.get("enabled") is True
and section.get("allow_from", section.get("allowFrom")) == []
)
if empty_allow_lists:
raise HTTPException(
status_code=422,
detail={
"message": (
"Enabled channels require at least one allowed sender: "
+ ", ".join(empty_allow_lists)
),
"channels": empty_allow_lists,
},
)
# Inline avatars are client-resized to ~128px before upload; this cap is a
# server-side backstop so config.yaml can't be bloated with raw photos.
_AVATAR_MAX_CHARS = 200_000
def _validate_avatar_payload(value: str | None) -> str:
avatar = (value or "").strip()
if not avatar:
return ""
if not avatar.startswith("data:image/"):
raise HTTPException(status_code=422, detail="Avatar must be a data:image/* URL")
if len(avatar) > _AVATAR_MAX_CHARS:
raise HTTPException(
status_code=422,
detail="Avatar too large — resize the image before uploading",
)
return avatar
def _validate_llm_selection_payload(
value: dict[str, str] | None,
) -> dict[str, str] | None:
"""Validate a partner model selection against the shared LLM catalog."""
from deeptutor.multi_user.model_access import apply_allowed_llm_selection
from deeptutor.services.config import get_model_catalog_service
from deeptutor.services.model_selection import apply_llm_selection_to_catalog
from deeptutor.services.partners.model_runtime import normalize_partner_llm_selection
try:
selection = normalize_partner_llm_selection(value)
if selection:
apply_llm_selection_to_catalog(get_model_catalog_service().load(), selection)
# A partner must not reach a model its creator cannot: the runtime
# executes in the partner's synthetic scope, where the owner's grants
# are no longer visible, so the check has to land here.
return apply_allowed_llm_selection(selection)
except ValueError as exc:
raise HTTPException(status_code=422, detail=str(exc)) from None
def _caller_tool_reach() -> tuple[set[str] | None, set[str] | None]:
"""``(optional, mcp)`` tool whitelists for the caller; ``None`` = unrestricted."""
from deeptutor.multi_user.tool_access import allowed_mcp_tools, allowed_optional_tools
if get_current_user().is_admin:
return None, None
return allowed_optional_tools(), allowed_mcp_tools()
def _clamp(chosen: list[str] | None, allowed: set[str] | None) -> list[str] | None:
"""Narrow a partner's tool whitelist to *allowed*.
``chosen is None`` means "every tool" in partner config, so an actual
restriction has to spell the permitted set out rather than stay open.
"""
if allowed is None:
return chosen
if chosen is None:
return sorted(allowed)
return [name for name in chosen if name in allowed]
def clamp_to_caller_reach(config: PartnerConfig) -> None:
"""Hold a partner's tool surface inside its creator's own permissions.
Ordinary chat enforces per-user tool grants at turn time, but a partner
turn runs as the partner — by then nothing recalls whose partner it is. So
the grant is applied once, here, where the human is still on the request.
"""
optional, mcp = _caller_tool_reach()
config.enabled_tools = _clamp(config.enabled_tools, optional)
config.mcp_tools = _clamp(config.mcp_tools, mcp)
def _resolve_soul_content(soul: SoulSpec | None) -> tuple[str, dict[str, str]]:
"""Resolve a SoulSpec into (markdown content, origin record)."""
from deeptutor.services.partners.workspace import DEFAULT_SOUL
if soul is None or soul.source == "default":
return DEFAULT_SOUL, {"type": "default", "id": ""}
if soul.source == "custom":
content = (soul.content or "").strip()
if not content:
raise HTTPException(status_code=422, detail=t("api.soul_content_empty"))
return content, {"type": "custom", "id": ""}
if soul.source == "library":
entry = get_partner_manager().get_soul(str(soul.id or ""))
if not entry:
raise HTTPException(
status_code=404,
detail=t("api.soul_library_not_found", name=str(soul.id)),
)
return str(entry.get("content") or ""), {"type": "library", "id": str(soul.id)}
# source == "persona": clone from the chat persona workspace (the
# requesting user's personas first; non-admins fall back to admin
# presets, mirroring chat's resolution).
name = str(soul.id or "").strip()
if not name:
raise HTTPException(status_code=422, detail=t("api.persona_name_required"))
content = _load_persona_markdown(name)
if not content:
raise HTTPException(status_code=404, detail=t("api.persona_not_found", name=name))
return content, {"type": "persona", "id": name}
def _load_persona_markdown(name: str) -> str:
from deeptutor.multi_user.paths import get_admin_path_service
from deeptutor.services.persona import PersonaService, get_persona_service
try:
detail = get_persona_service().get_detail(name)
return strip_frontmatter(detail.content)
except Exception:
pass
try:
admin_service = PersonaService(
root=get_admin_path_service().get_workspace_dir() / "personas"
)
return strip_frontmatter(admin_service.get_detail(name).content)
except Exception:
pass
return ""
# ── Soul template library (before /{partner_id} routes) ───────
@router.get("/souls")
async def list_souls():
return get_partner_manager().list_souls()
@router.post("/souls", dependencies=[Depends(require_admin)])
async def create_soul(payload: SoulCreateRequest):
mgr = get_partner_manager()
# Slug the id server-side (authoritative): soul ids ride in ``/souls/<id>``
# URLs, so a raw CJK / path-unsafe id (e.g. ``我的灵魂`` or ``a/b``) would be
# unreachable or mis-routed. The client uses the returned ``id``.
soul_id = slugify_soul_id(payload.id or payload.name)
if mgr.get_soul(soul_id):
raise HTTPException(status_code=409, detail=t("api.soul_already_exists", name=soul_id))
return mgr.create_soul(soul_id, payload.name, payload.content)
@router.get("/souls/{soul_id}")
async def get_soul(soul_id: str):
soul = get_partner_manager().get_soul(soul_id)
if not soul:
raise HTTPException(status_code=404, detail=t("api.soul_not_found"))
return soul
@router.put("/souls/{soul_id}", dependencies=[Depends(require_admin)])
async def update_soul(soul_id: str, payload: SoulTemplateUpdateRequest):
result = get_partner_manager().update_soul(soul_id, payload.name, payload.content)
if not result:
raise HTTPException(status_code=404, detail=t("api.soul_not_found"))
return result
@router.delete("/souls/{soul_id}", dependencies=[Depends(require_admin)])
async def delete_soul(soul_id: str):
if not get_partner_manager().delete_soul(soul_id):
raise HTTPException(status_code=404, detail=t("api.soul_not_found"))
return {"id": soul_id, "deleted": True}
@router.get("/soul-sources")
async def soul_sources():
"""Everything the create-wizard's soul step can start from."""
from deeptutor.multi_user.paths import get_admin_path_service
from deeptutor.services.persona import PersonaService, get_persona_service
def _persona_entry(service: PersonaService, info: Any) -> dict[str, str]:
# Content rides along so the wizard can preview the clone; creation
# still re-resolves the persona server-side (_resolve_soul_content).
try:
content = strip_frontmatter(service.get_detail(info.name).content)
except Exception:
content = ""
return {"name": info.name, "description": info.description, "content": content}
personas: list[dict[str, str]] = []
seen: set[str] = set()
try:
service = get_persona_service()
for info in service.list_personas():
personas.append(_persona_entry(service, info))
seen.add(info.name)
except Exception:
logger.warning("Failed to list user personas", exc_info=True)
try:
admin_service = PersonaService(
root=get_admin_path_service().get_workspace_dir() / "personas"
)
for info in admin_service.list_personas():
if info.name not in seen:
personas.append(_persona_entry(admin_service, info))
except Exception:
logger.warning("Failed to list admin personas", exc_info=True)
return {"library": get_partner_manager().list_souls(), "personas": personas}
# ── Static catalog endpoints ───────────────────────────────────
@router.get("")
async def list_partners():
"""Partners the caller may talk to — theirs in full, assigned ones as cards."""
return visible_partners()
class NavigationSession(BaseModel):
kind: Literal["partner", "group"]
owner_id: str
owner_name: str
session_key: str
title: str
updated_at: float
class PartnerNavigation(BaseModel):
partners: list[dict[str, Any]]
groups: list[dict[str, Any]]
sessions: list[NavigationSession]
unavailable: list[str]
def _navigation_timestamp(value: Any) -> float:
try:
return float(value)
except (TypeError, ValueError):
try:
return datetime.fromisoformat(str(value).replace("Z", "+00:00")).timestamp()
except ValueError:
return 0.0
@router.get("/navigation", response_model=PartnerNavigation)
async def partner_navigation():
"""Read existing identities and actor-scoped sessions without moving data.
Never enumerate the manager's global partner directories or shared channel
history here. Visibility and transcript ownership match the detail APIs.
"""
from deeptutor.services.partner_groups import get_partner_group_manager
partners = [
{
key: row.get(key)
for key in (
"partner_id",
"name",
"description",
"emoji",
"color",
"avatar",
"can_manage",
"running",
)
}
for row in visible_partners()
]
group_manager = get_partner_group_manager()
groups = group_manager.list_groups()
sessions: list[NavigationSession] = []
unavailable: list[str] = []
manager = get_partner_manager()
for kind, owners in (("partner", partners), ("group", groups)):
for owner in owners:
owner_id = owner[f"{kind}_id"]
try:
rows = (
manager.session_store(owner_id).list_sessions()
if kind == "partner"
else group_manager.list_sessions(owner_id)
)
for row in rows:
if row.get("archived"):
continue
sessions.append(
NavigationSession(
kind=kind,
owner_id=owner_id,
owner_name=owner["name"],
session_key=row["session_key"],
title=str(row.get("title") or row.get("last_message") or "")[:160],
updated_at=_navigation_timestamp(row.get("updated_at")),
)
)
except Exception:
logger.warning(
"Partner navigation unavailable: %s/%s", kind, owner_id, exc_info=True
)
unavailable.append(f"{kind}:{owner_id}")
sessions.sort(key=lambda row: (-row.updated_at, row.kind, row.owner_id, row.session_key))
return PartnerNavigation(
partners=partners, groups=groups, sessions=sessions, unavailable=unavailable
)
@router.get("/consultation-session")
async def get_partner_consultation_session(chat_session_id: str, partner_name: str):
"""Recover native identity for older consultation traces in this user's registry."""
from deeptutor.services.subagent.sessions import get_session, session_key
matches = []
for partner in visible_partners():
if partner.get("name") != partner_name:
continue
partner_id = str(partner["partner_id"])
native_key = get_session(session_key(chat_session_id, f"partner:{partner_id}"))
if native_key:
matches.append({"partner_id": partner_id, "session_key": native_key})
# Never open a different conversation when names are ambiguous.
return matches[0] if len(matches) == 1 else None
@router.get("/recent")
async def recent_partners(limit: int = 3):
recent = get_partner_manager().get_recent_active_partners(limit=limit)
return [item for item in recent if can_use_partner(str(item.get("partner_id") or ""))]
@router.get("/channels/schema")
async def list_channel_schemas():
"""JSON-Schema metadata for every available channel (schema-driven UI)."""
from deeptutor.api.routers._partners_channel_schema import all_channel_schemas
return {"channels": all_channel_schemas()}
# ── WeChat QR onboarding ───────────────────────────────────────
#
# The personal-WeChat channel authenticates by scanning a QR code, and until now
# it only ever drew that code on the server's stdout — unreachable on any
# container deployment (#951). These two endpoints run the same exchange for the
# browser. The bot token is written into the partner's channel config server-side
# and is never part of a response.
@router.post("/{partner_id}/channels/weixin/qr", dependencies=_MANAGEABLE)
async def start_weixin_qr(partner_id: str):
"""Issue a QR code for this partner and return what to render."""
from deeptutor.services.partners import weixin_onboarding
try:
return await weixin_onboarding.start_login(partner_id)
except Exception as exc:
logger.warning("weixin QR start failed for %s", partner_id, exc_info=True)
raise HTTPException(status_code=502, detail=str(exc)) from exc
@router.get("/{partner_id}/channels/weixin/qr/{session_id}", dependencies=_MANAGEABLE)
async def poll_weixin_qr(partner_id: str, session_id: str):
"""Advance the scan and report its state (never the token)."""
from deeptutor.services.partners import weixin_onboarding
return await weixin_onboarding.poll_login(partner_id, session_id)
@router.get("/tool-options")
async def tool_options():
"""The configurable tool surface for a partner.
``tools`` mirrors the user-toggleable system tools (the same pool the
chat composer / settings expose); ``builtin_tools`` lists the auto-mounted
built-in tools (rag / web_fetch / …) the owner can allow or deny;
``mcp_tools`` lists every configured MCP tool the partner could be allowed
to load. ``read_memory`` / ``write_memory`` are excluded: partners use the
mandatory ``partner_read`` / ``partner_memorize`` / ``partner_search`` tools
instead, which are always on and not owner-configurable.
"""
from deeptutor.agents._shared.tool_composition import admin_enabled_optional_tools
from deeptutor.api.utils.tool_options import build_tool_options
from deeptutor.multi_user.tool_access import combine_whitelists
optional, mcp = _caller_tool_reach()
options = await build_tool_options(
exclude_builtin={"read_memory", "write_memory"},
optional_tools=sorted(
combine_whitelists(set(admin_enabled_optional_tools()), optional) or ()
),
)
if mcp is not None:
options["mcp_tools"] = [
tool for tool in options.get("mcp_tools", []) if _tool_name(tool) in mcp
]
return options
def _tool_name(tool: Any) -> str:
return str(tool.get("name") or "") if isinstance(tool, dict) else str(tool)
# ── Create / read / update / lifecycle ─────────────────────────
@router.post("")
async def create_partner(payload: CreatePartnerRequest):
"""Create a partner owned by the caller.
Anyone may build their own companion; the assets it is provisioned with are
resolved against the creator's own permissions (see ``provision_assets``),
so this hands nobody access they did not already have.
"""
return await _create_partner(payload)
async def _create_partner(payload: CreatePartnerRequest) -> dict[str, Any]:
"""Validated creation transaction shared by the wizard and chat drafts."""
mgr = get_partner_manager()
partner_id = slugify_partner_id(payload.partner_id or payload.name)
if mgr.partner_exists(partner_id):
raise HTTPException(
status_code=409,
detail=t("api.partner_already_exists", name=partner_id),
)
if payload.channels is not None:
_validate_channels_payload(payload.channels)
llm_selection = _validate_llm_selection_payload(payload.llm_selection)
backup_llm_selection = _validate_llm_selection_payload(payload.backup_llm_selection)
soul_content, soul_origin = _resolve_soul_content(payload.soul)
workspace_id = _validate_workspace(payload.workspace_id, get_current_user().id)
if workspace_id and payload.assets and any(payload.assets.model_dump().values()):
raise HTTPException(
status_code=400,
detail="Use the shared workspace resources or copy private assets, not both.",
)
config = PartnerConfig(
workspace_id=workspace_id,
name=payload.name.strip(),
description=(payload.description or "").strip(),
owner_id=get_current_user().id,
channels=payload.channels or {},
llm_selection=llm_selection,
backup_llm_selection=backup_llm_selection,
language=(payload.language or "").strip(),
emoji=(payload.emoji or "").strip(),
color=(payload.color or "").strip(),
avatar=_validate_avatar_payload(payload.avatar),
soul_origin=soul_origin,
enabled_tools=payload.enabled_tools,
builtin_tools=payload.builtin_tools,
mcp_tools=payload.mcp_tools,
)
clamp_to_caller_reach(config)
mgr.save_config(partner_id, config, auto_start=bool(payload.start))
write_soul(partner_id, soul_content)
provisioning: dict[str, Any] = {"copied": {}, "errors": []}
if payload.assets is not None:
provisioning = provision_assets(
partner_id,
knowledge_bases=payload.assets.knowledge_bases,
skills=payload.assets.skills,
notebooks=payload.assets.notebooks,
)
if payload.start:
remote = await _request_partner_control(
BackgroundCommandKind.PARTNER_START,
partner_id,
persist_auto_start=True,
)
if remote is not None:
result = _stopped_partner_dict(partner_id, config)
else:
try:
instance = await mgr.start_partner(partner_id, config)
result = instance.to_dict(mask_secrets=True)
except Exception:
logger.exception("Partner '%s' created but failed to start", partner_id)
result = _stopped_partner_dict(partner_id, config)
result["start_error"] = "Partner created but failed to start"
else:
result = _stopped_partner_dict(partner_id, config)
result["provisioning"] = provisioning
return result
@router.get("/drafts/{draft_id}")
async def get_partner_draft(draft_id: str):
"""Reload one pending/created draft for the authenticated user."""
try:
draft = PartnerDraftStore().get(draft_id)
except ValueError:
draft = None
if draft is None:
raise HTTPException(status_code=404, detail="Partner draft not found")
return draft.to_dict()
@router.post("/drafts/{draft_id}/confirm")
async def confirm_partner_draft(
draft_id: str,
payload: ConfirmPartnerDraftRequest,
):
"""Promote a reviewable Chat draft into a real Partner exactly once."""
lock = await _get_draft_confirm_lock(draft_id)
async with lock:
return await _confirm_partner_draft(draft_id, payload)
async def _confirm_partner_draft(
draft_id: str,
payload: ConfirmPartnerDraftRequest,
) -> dict[str, Any]:
store = PartnerDraftStore()
try:
draft = store.get(draft_id)
except ValueError:
draft = None
if draft is None:
raise HTTPException(status_code=404, detail="Partner draft not found")
if draft.status == "created" and draft.created_partner_id:
cfg = get_partner_manager().load_config(draft.created_partner_id)
if cfg is not None:
result = _stopped_partner_dict(draft.created_partner_id, cfg)
instance = get_partner_manager().get_partner(draft.created_partner_id)
if instance is not None:
result = instance.to_dict(mask_secrets=True)
result["draft_id"] = draft.draft_id
result["already_created"] = True
return result
data = payload.model_dump(exclude_none=True)
create_payload = CreatePartnerRequest(
name=str(data.get("name", draft.name)),
description=str(data.get("description", draft.description)),
soul=SoulSpec(source="custom", content=str(data.get("soul", draft.soul))),
language=str(data.get("language", draft.language)),
emoji=str(data.get("emoji", draft.emoji)),
color=str(data.get("color", draft.color)),
enabled_tools=draft.enabled_tools,
builtin_tools=draft.builtin_tools,
mcp_tools=draft.mcp_tools,
start=bool(data.get("start", True)),
)
result = await _create_partner(create_payload)
store.mark_created(draft, str(result["partner_id"]))
result["draft_id"] = draft.draft_id
result["already_created"] = False
return result
def _stopped_partner_dict(
partner_id: str,
cfg: PartnerConfig,
*,
include_secrets: bool = False,
) -> dict:
if include_secrets:
channels: object = strip_legacy_global_delivery(cfg.channels)
else:
channels = mask_channel_secrets(strip_legacy_global_delivery(cfg.channels))
result = {
"partner_id": partner_id,
"workspace_id": cfg.workspace_id,
"name": cfg.name,
"description": cfg.description,
"channels": channels,
"llm_selection": cfg.llm_selection,
"backup_llm_selection": cfg.backup_llm_selection,
"model": cfg.model,
"language": cfg.language,
"emoji": cfg.emoji,
"color": cfg.color,
"avatar": cfg.avatar,
"soul_origin": cfg.soul_origin,
"enabled_tools": cfg.enabled_tools,
"builtin_tools": cfg.builtin_tools,
"mcp_tools": cfg.mcp_tools,
"running": False,
"started_at": None,
"last_reload_error": None,
}
from deeptutor.services.partners.runtime_status import (
get_partner_runtime_status_repository,
)
status = get_partner_runtime_status_repository().get(partner_id)
if status:
result.update(
{
key: status[key]
for key in (
"running",
"started_at",
"last_reload_error",
"runtime_owner_id",
"runtime_state",
"runtime_updated_at",
)
if key in status
}
)
return result
@router.get("/{partner_id}", dependencies=_USABLE)
async def get_partner(
partner_id: str,
include_secrets: bool = Query(
False,
description=(
"Return raw channel secrets (tokens, passwords). Required by the "
"edit form; default response masks all secret-looking fields."
),
),
):
"""One partner, projected by what the caller may do with it.
Someone who merely *uses* the partner gets its identity card — enough to
render a conversation header — while its owner gets the configuration.
"""
mgr = get_partner_manager()
manageable = can_manage_partner(partner_id)
include_secrets = include_secrets and manageable
instance = mgr.get_partner(partner_id)
if instance:
full = instance.to_dict(
include_secrets=include_secrets,
mask_secrets=not include_secrets,
)
else:
cfg = mgr.load_config(partner_id)
if cfg is None:
raise HTTPException(status_code=404, detail=t("api.partner_not_found"))
full = _stopped_partner_dict(partner_id, cfg, include_secrets=include_secrets)
if not manageable:
return {**identity_card(full), "can_manage": False}
return {**full, "can_manage": True}
def _validate_workspace(workspace_id: str, owner_id: str) -> str:
from deeptutor.services.partners.workspace_binding import validate_partner_workspace
from deeptutor.services.workspace import WorkspaceError
try:
return validate_partner_workspace(workspace_id, owner_id)
except WorkspaceError as exc:
raise HTTPException(status_code=400, detail=str(exc)) from exc
def _apply_update(cfg: PartnerConfig, payload: UpdatePartnerRequest) -> None:
if "workspace_id" in payload.model_fields_set:
cfg.workspace_id = _validate_workspace(payload.workspace_id or "", cfg.owner_id)
if payload.name is not None:
cfg.name = payload.name
if payload.description is not None:
cfg.description = payload.description
if payload.channels is not None:
cfg.channels = payload.channels
if payload.language is not None:
cfg.language = payload.language
if payload.emoji is not None:
cfg.emoji = payload.emoji
if payload.color is not None:
cfg.color = payload.color
if payload.avatar is not None:
cfg.avatar = _validate_avatar_payload(payload.avatar)
if "llm_selection" in payload.model_fields_set:
cfg.llm_selection = _validate_llm_selection_payload(payload.llm_selection)
cfg.model = None # selection supersedes any legacy model string
if "backup_llm_selection" in payload.model_fields_set:
cfg.backup_llm_selection = _validate_llm_selection_payload(payload.backup_llm_selection)
if "enabled_tools" in payload.model_fields_set:
cfg.enabled_tools = payload.enabled_tools
if "builtin_tools" in payload.model_fields_set:
cfg.builtin_tools = payload.builtin_tools
if "mcp_tools" in payload.model_fields_set:
cfg.mcp_tools = payload.mcp_tools
clamp_to_caller_reach(cfg)
@router.patch("/{partner_id}", dependencies=_MANAGEABLE)
async def update_partner(partner_id: str, payload: UpdatePartnerRequest):
if payload.channels is not None:
_validate_channels_payload(payload.channels)
mgr = get_partner_manager()
instance = mgr.get_partner(partner_id)
if instance and instance.running:
_apply_update(instance.config, payload)
mgr.save_config(partner_id, instance.config)
if payload.channels is not None:
try:
await mgr.reload_channels(partner_id)
except Exception as exc:
logger.exception("reload_channels failed for partner '%s'", partner_id)
raise HTTPException(
status_code=500,
detail=(
"Channels saved but failed to restart listeners "
f"({type(exc).__name__}); try stopping and starting the partner."
),
) from None
# LLM / tool changes need no reload: the runner resolves
# llm_selection and tool config per turn from this same config object.
return instance.to_dict(mask_secrets=True)
cfg = mgr.load_config(partner_id)
if not cfg:
raise HTTPException(status_code=404, detail=t("api.partner_not_found"))
_apply_update(cfg, payload)
mgr.save_config(partner_id, cfg)
status = get_partner_runtime_status_repository().get(partner_id) or {}
if status.get("running"):
await _request_partner_control(
BackgroundCommandKind.PARTNER_RELOAD,
partner_id,
)
return _stopped_partner_dict(partner_id, cfg)
@router.post("/{partner_id}/start", dependencies=_MANAGEABLE)
async def start_partner(partner_id: str):
remote = await _request_partner_control(
BackgroundCommandKind.PARTNER_START,
partner_id,
persist_auto_start=True,
)
if remote is not None:
cfg = get_partner_manager().load_config(partner_id)
if cfg is None:
raise HTTPException(status_code=404, detail=t("api.partner_not_found"))
return _stopped_partner_dict(partner_id, cfg)
instance = await _ensure_running_partner(partner_id, allow_stopped=True)
# An explicit start is a persisted "run on boot" intent — so the partner
# comes back in this state after a DeepTutor restart (a manual /stop clears
# it; a lazy chat-driven start does NOT reach here, so it can't flip it).
get_partner_manager().save_config(partner_id, instance.config, auto_start=True)
return instance.to_dict(mask_secrets=True)
@router.post("/{partner_id}/stop", dependencies=_MANAGEABLE)
async def stop_partner(partner_id: str):
remote = await _request_partner_control(
BackgroundCommandKind.PARTNER_STOP,
partner_id,
preserve_auto_start=False,
)
if remote is not None:
return {"partner_id": partner_id, "stopped": True}
stopped = await get_partner_manager().stop_partner(partner_id)
if not stopped:
raise HTTPException(status_code=404, detail=t("api.partner_not_found_or_not_running"))
return {"partner_id": partner_id, "stopped": True}
@router.delete("/{partner_id}", dependencies=_MANAGEABLE)
async def destroy_partner(partner_id: str):
await _request_partner_control(
BackgroundCommandKind.PARTNER_STOP,
partner_id,
preserve_auto_start=False,
)
destroyed = await get_partner_manager().destroy_partner(partner_id)
if not destroyed:
raise HTTPException(status_code=404, detail=t("api.partner_not_found"))
return {"partner_id": partner_id, "destroyed": True}
@router.post("/{partner_id}/channels/reload", dependencies=_MANAGEABLE)
async def reload_partner_channels(partner_id: str):
mgr = get_partner_manager()
instance = mgr.get_partner(partner_id)
status = get_partner_runtime_status_repository().get(partner_id) or {}
if (not instance or not instance.running) and status.get("running"):
await _request_partner_control(
BackgroundCommandKind.PARTNER_RELOAD,
partner_id,
)
return {"partner_id": partner_id, "reloaded": True}
if not instance or not instance.running:
raise HTTPException(status_code=404, detail=t("api.partner_not_running"))
try:
await mgr.reload_channels(partner_id)
except Exception as exc:
raise HTTPException(
status_code=500,
detail=f"Failed to reload channels: {type(exc).__name__}",
) from None
return {"partner_id": partner_id, "reloaded": True}
@router.get("/{partner_id}/channels/status", dependencies=_MANAGEABLE)
async def get_partner_channel_status(partner_id: str):
"""User-facing listener/setup state, including QR output when available."""
mgr = get_partner_manager()
instance = mgr.get_partner(partner_id)
config = instance.config if instance else mgr.load_config(partner_id)
if config is None:
raise HTTPException(status_code=404, detail=t("api.partner_not_found"))
source = config.channels if isinstance(config.channels, dict) else {}
channels = {
name: {
"enabled": bool(value.get("enabled")) if isinstance(value, dict) else False,
"running": False,
"setup": {},
}
for name, value in source.items()
}
if instance and instance.channel_manager:
# Merge instead of replacing so an enabled channel that could not be
# constructed (missing dependency, invalid allowlist, plugin absent)
# remains visible alongside live listeners.
channels.update(instance.channel_manager.get_status())
# QR rendering is intentionally server-side: it keeps channel bridges and
# the web bundle dependency-free while ensuring their interactive output is
# visible on the page rather than only in a terminal.
from deeptutor.services.partners.channel_onboarding import _qr_data_url
for state in channels.values():
setup = state.get("setup") if isinstance(state, dict) else None
payload = setup.get("qr_payload") if isinstance(setup, dict) else ""
if payload:
setup["qr_data_url"] = _qr_data_url(str(payload))
return {
"partner_id": partner_id,
"running": bool(instance and instance.running),
"channels": channels,
}
def _onboarding_manager_and_partner(partner_id: str):
mgr = get_partner_manager()
if not mgr.partner_exists(partner_id):
raise HTTPException(status_code=404, detail=t("api.partner_not_found"))
return get_channel_onboarding_manager(), mgr
@router.post("/{partner_id}/channel-onboarding/start", dependencies=_MANAGEABLE)
async def start_partner_channel_onboarding(partner_id: str, payload: ChannelOnboardingStartRequest):
onboarding, _ = _onboarding_manager_and_partner(partner_id)
try:
return await onboarding.start(partner_id, payload.channel)
except ChannelOnboardingError as exc:
raise HTTPException(status_code=exc.status_code, detail=str(exc)) from None
except Exception as exc:
logger.exception("Failed to start channel onboarding for '%s'", partner_id)
raise HTTPException(
status_code=502,
detail=f"Channel onboarding provider request failed ({type(exc).__name__})",
) from exc
@router.get("/{partner_id}/channel-onboarding/{session_id}", dependencies=_MANAGEABLE)
async def get_partner_channel_onboarding(partner_id: str, session_id: str):
onboarding, _ = _onboarding_manager_and_partner(partner_id)
try:
return await onboarding.status(partner_id, session_id)
except ChannelOnboardingError as exc:
raise HTTPException(status_code=exc.status_code, detail=str(exc)) from None
except Exception as exc:
logger.exception("Failed to poll channel onboarding for '%s'", partner_id)
raise HTTPException(
status_code=502,
detail=f"Channel onboarding provider request failed ({type(exc).__name__})",
) from exc
@router.delete("/{partner_id}/channel-onboarding/{session_id}", dependencies=_MANAGEABLE)
async def cancel_partner_channel_onboarding(partner_id: str, session_id: str):
onboarding, _ = _onboarding_manager_and_partner(partner_id)
try:
return await onboarding.cancel(partner_id, session_id)
except ChannelOnboardingError as exc:
raise HTTPException(status_code=exc.status_code, detail=str(exc)) from None
@router.post("/{partner_id}/channel-onboarding/{session_id}/apply", dependencies=_MANAGEABLE)
async def apply_partner_channel_onboarding(partner_id: str, session_id: str):
onboarding, mgr = _onboarding_manager_and_partner(partner_id)
try:
return await onboarding.apply(partner_id, session_id, mgr)
except ChannelOnboardingError as exc:
raise HTTPException(status_code=exc.status_code, detail=str(exc)) from None
except Exception as exc:
logger.exception("Failed to apply channel onboarding for '%s'", partner_id)
raise HTTPException(
status_code=500,
detail=(
"Channel config saved but failed to restart listeners "
f"({type(exc).__name__}); try stopping and starting the partner."
),
) from exc
# ── Soul (the partner's own SOUL.md) ───────────────────────────
@router.get("/{partner_id}/soul", dependencies=_MANAGEABLE)
async def get_partner_soul(partner_id: str):
return {"partner_id": partner_id, "content": read_soul(partner_id)}
@router.put("/{partner_id}/soul", dependencies=_MANAGEABLE)
async def put_partner_soul(partner_id: str, payload: SoulUpdateBody):
write_soul(partner_id, payload.content)
return {"partner_id": partner_id, "saved": True}
# ── Assets ─────────────────────────────────────────────────────
@router.get("/{partner_id}/workspaces", dependencies=_MANAGEABLE)
async def get_partner_workspaces(partner_id: str):
"""Configuration choices belong to the Partner owner, including admin edits."""
from deeptutor.multi_user.paths import user_context
from deeptutor.services.partners.workspace_binding import workspace_owner
from deeptutor.services.workspace import WorkspaceError, get_content_workspace_service
from deeptutor.services.workspace.context import workspace_context
config = get_partner_manager().load_config(partner_id)
if config is None:
raise HTTPException(status_code=404, detail=t("api.partner_not_found"))
try:
with user_context(workspace_owner(config.owner_id)), workspace_context(""):
return {"workspaces": get_content_workspace_service().list_workspaces()}
except WorkspaceError as exc:
raise HTTPException(status_code=400, detail=str(exc)) from exc
@router.get("/{partner_id}/assets", dependencies=_MANAGEABLE)
async def get_partner_assets(partner_id: str):
return list_assets(partner_id)
@router.post("/{partner_id}/assets", dependencies=_MANAGEABLE)
async def add_partner_assets(partner_id: str, payload: AssetAddRequest):
config = get_partner_manager().load_config(partner_id)
if config and config.workspace_id:
raise HTTPException(
status_code=400,
detail="This partner uses shared workspace resources. Add resources to that workspace.",
)
report = provision_assets(
partner_id,
knowledge_bases=payload.knowledge_bases,
skills=payload.skills,
notebooks=payload.notebooks,
)
return {"partner_id": partner_id, **report, "assets": list_assets(partner_id)}
@router.delete("/{partner_id}/assets/{asset_type}/{name}", dependencies=_MANAGEABLE)
async def delete_partner_asset(partner_id: str, asset_type: str, name: str):
try:
removed = remove_asset(partner_id, asset_type, name)
except ValueError as exc:
raise HTTPException(status_code=422, detail=str(exc)) from None
if not removed:
raise HTTPException(status_code=404, detail="Asset not found")
return {"partner_id": partner_id, "removed": True, "assets": list_assets(partner_id)}
# ── Channel account links ──────────────────────────────────────
@router.post("/{partner_id}/links/code", dependencies=_USABLE)
async def create_partner_link_code(partner_id: str):
"""Mint a code for connecting one of your chat accounts to this partner.
Send ``/link <code>`` to the partner as a direct message from the chat
account you want connected; that account then speaks as you.
"""
from deeptutor.services.partners.links import issue_link_code
issued = issue_link_code(partner_id, get_current_user().id)
return {
"partner_id": partner_id,
"code": issued.code,
"expires_at": issued.expires_at,
"command": f"/link {issued.code}",
}
@router.get("/{partner_id}/links", dependencies=_USABLE)
async def list_partner_links(partner_id: str):
"""Your own linked chat accounts for this partner — never anyone else's."""
from deeptutor.services.partners.links import list_links
return {"partner_id": partner_id, "links": list_links(partner_id, get_current_user().id)}
@router.delete("/{partner_id}/links/{key:path}", dependencies=_USABLE)
async def delete_partner_link(partner_id: str, key: str):
"""Disconnect one of your chat accounts; its past messages stay yours."""
from deeptutor.services.partners.links import remove_link
if not remove_link(partner_id, get_current_user().id, key):
raise HTTPException(status_code=404, detail="No such linked account")
return {"partner_id": partner_id, "removed": True, "key": key}
# ── History ────────────────────────────────────────────────────
@router.get("/{partner_id}/history", dependencies=_USABLE)
async def get_partner_history(
partner_id: str,
session_key: str | None = None,
session_id: str | None = None,
limit: int = 100,
):
"""Conversation history. Pass ``session_key`` for an exact key, or
``session_id`` for a web session (mapped through ``web_session_key``);
with neither, all non-archived sessions are merged."""
mgr = get_partner_manager()
if session_id and not session_key:
session_key = mgr.web_session_key(partner_id, session_id=session_id)
return mgr.get_history(
partner_id,
session_key=session_key,
limit=limit,
# Owners/admins can observe unlinked channel traffic in the Partner's
# shared store; assigned users still see only their own linked account.
include_shared=not session_key and can_manage_partner(partner_id),
)
@router.get("/{partner_id}/history/page", dependencies=_USABLE)
async def get_partner_history_page(
partner_id: str,
session_key: str,
before: int | None = Query(default=None, ge=0),
limit: int = Query(default=60, ge=1, le=200),
):
"""Read older turns of one actor-scoped conversation in bounded pages."""
return (
get_partner_manager()
.session_store(partner_id)
.messages_page(session_key, before=before, limit=limit)
)
@router.get("/{partner_id}/web-continuity", dependencies=_USABLE)
async def get_partner_web_continuity(partner_id: str):
return get_web_continuity(partner_id, get_current_user().id)
@router.put("/{partner_id}/web-continuity", dependencies=_USABLE)
async def put_partner_web_continuity(partner_id: str, payload: WebContinuityBody):
mgr = get_partner_manager()
try:
return set_web_continuity(
partner_id,
get_current_user().id,
enabled=payload.enabled,
session_key=payload.session_key,
idle_lock=lambda key: mgr.web_session_idle_lock(partner_id, key),
)
except ValueError as exc:
raise HTTPException(status_code=422, detail=str(exc)) from None
except PartnerTurnBusyError as exc:
raise HTTPException(status_code=409, detail=str(exc)) from None
@router.get("/{partner_id}/sessions", dependencies=_USABLE)
async def get_partner_sessions(partner_id: str):
mgr = get_partner_manager()
return mgr.session_store(partner_id).list_sessions()
@router.post("/{partner_id}/sessions/archive", dependencies=_USABLE)
async def archive_partner_session(partner_id: str, payload: SessionKeyBody):
"""Soft-archive a session (web /new) — it stays resumable, file untouched."""
mgr = get_partner_manager()
try:
with mgr.web_session_idle_lock(partner_id, payload.session_key):
if not mgr.archive_session(partner_id, payload.session_key):
raise HTTPException(status_code=404, detail="Session not found")
active_key = move_active_web_session(
partner_id,
get_current_user().id,
session_key=payload.session_key,
new_session_key=fresh_web_session_key(),
)
except PartnerTurnBusyError as exc:
raise HTTPException(status_code=409, detail=str(exc)) from None
return {
"partner_id": partner_id,
"archived": True,
"session_key": payload.session_key,
"active_session_key": active_key,
}
@router.post("/{partner_id}/sessions/resume", dependencies=_USABLE)
async def resume_partner_session(partner_id: str, payload: SessionKeyBody):
"""Clear a session's archived flag so the web app can continue it."""
mgr = get_partner_manager()
try:
session_key = validate_session_key(payload.session_key)
except ValueError as exc:
raise HTTPException(status_code=422, detail=str(exc)) from None
try:
with mgr.web_session_idle_lock(partner_id, session_key):
summary = mgr.resume_session(partner_id, session_key)
if summary is None:
raise HTTPException(status_code=404, detail="Session not found")
active_key = move_active_web_session(
partner_id,
get_current_user().id,
session_key=session_key,
new_session_key=session_key,
only_if_current=False,
idle_lock=lambda key: mgr.web_session_idle_lock(partner_id, key),
)
except PartnerTurnBusyError as exc:
raise HTTPException(status_code=409, detail=str(exc)) from None
return {
"partner_id": partner_id,
"resumed": True,
"session": summary,
"active_session_key": active_key,
}
@router.post("/{partner_id}/sessions/delete", dependencies=_USABLE)
async def delete_partner_session(partner_id: str, payload: SessionKeyBody):
mgr = get_partner_manager()
try:
with mgr.web_session_idle_lock(partner_id, payload.session_key):
removed = mgr.delete_session(partner_id, payload.session_key)
if not removed:
raise HTTPException(status_code=404, detail="Session not found")
active_key = move_active_web_session(
partner_id,
get_current_user().id,
session_key=payload.session_key,
new_session_key=fresh_web_session_key(),
)
except PartnerTurnBusyError as exc:
raise HTTPException(status_code=409, detail=str(exc)) from None
return {
"partner_id": partner_id,
"deleted": True,
"session_key": payload.session_key,
"active_session_key": active_key,
}
@router.post("/{partner_id}/sessions/branch", dependencies=_USABLE)
async def branch_partner_session(partner_id: str, payload: SessionBranchBody):
"""Copy a session's full history into a new key and archive the source."""
mgr = get_partner_manager()
try:
target_key = validate_session_key(payload.new_key)
except ValueError as exc:
raise HTTPException(status_code=422, detail=str(exc)) from None
if mgr.session_store(partner_id)._stem(payload.source_key) == target_key:
raise HTTPException(status_code=400, detail="Branch needs a different session key")
try:
with mgr.web_session_idle_lock(partner_id, payload.source_key):
with mgr.web_session_idle_lock(partner_id, target_key):
summary = mgr.branch_session(partner_id, payload.source_key, target_key)
if summary is None:
raise HTTPException(
status_code=400, detail="Nothing to branch (source is empty)"
)
active_key = move_active_web_session(
partner_id,
get_current_user().id,
session_key=payload.source_key,
new_session_key=target_key,
)
except PartnerTurnBusyError as exc:
raise HTTPException(status_code=409, detail=str(exc)) from None
return {
"partner_id": partner_id,
"branched": True,
"session": summary,
"active_session_key": active_key,
}
@router.get("/commands/palette")
async def partner_command_palette():
from deeptutor.services.partners.commands import partner_command_palette
return {"commands": partner_command_palette()}
# ── Chat (HTTP / SSE / WebSocket) ──────────────────────────────
def _sse(event: str, payload: dict[str, Any]) -> str:
return f"event: {event}\ndata: {json.dumps(payload, ensure_ascii=False, default=str)}\n\n"
def _resolve_http_session(payload: ChatMessageRequest) -> tuple[str, str]:
explicit_session = (payload.session_id or "").strip()
explicit_chat = (payload.chat_id or "").strip()
if explicit_session:
return explicit_session, explicit_chat or explicit_session
if explicit_chat:
return explicit_chat, explicit_chat
session_id = uuid4().hex
return session_id, session_id
def _assert_selected_web_session(partner_id: str, account_id: str, session_key: str) -> None:
state = get_web_continuity(partner_id, account_id)
if state["enabled"] and state["session_key"] != validate_session_key(session_key):
raise PartnerStaleSessionError(str(state["session_key"]))
# Fallback caps when the settings layer is unavailable; the effective values
# come from the shared chat-attachment policy (data/user/settings/system.json,
# editable at /settings/attachments).
_PARTNER_UPLOAD_MAX_BYTES = 20 * 1024 * 1024
_PARTNER_UPLOAD_MAX_TOTAL_BYTES = 25 * 1024 * 1024
def _partner_upload_caps() -> tuple[int, int]:
try:
from deeptutor.services.config.runtime_settings import get_chat_attachment_limits
limits = get_chat_attachment_limits()
return limits.max_file_bytes, limits.max_total_bytes
except Exception: # pragma: no cover - defensive fallback
return _PARTNER_UPLOAD_MAX_BYTES, _PARTNER_UPLOAD_MAX_TOTAL_BYTES
def _clean_attachment_base64(value: str) -> str:
text = str(value or "").strip()
if text.startswith("data:") and "," in text:
return text.split(",", 1)[1]
return text
def _default_attachment_prompt(attachments: list[ChatAttachmentRequest]) -> str:
if attachments and all(str(item.type).lower() == "image" for item in attachments):
return t("Please analyze the attached image(s).")
return t("Please use the attached file(s).")
def _materialize_partner_attachments(
partner_id: str,
attachments: list[ChatAttachmentRequest],
) -> list[str]:
"""Persist browser-sent attachment bytes into the partner media tree."""
if not attachments:
return []
media_dir = get_partner_media_dir(partner_id, "web")
max_file_bytes, max_total_bytes = _partner_upload_caps()
total_bytes = 0
media_paths: list[str] = []
for item in attachments:
raw_b64 = _clean_attachment_base64(item.base64)
if not raw_b64:
# Partner web chat accepts uploaded bytes only. URL-only
# attachments are ignored rather than fetched server-side.
continue
try:
data = base64.b64decode(raw_b64, validate=False)
except (binascii.Error, ValueError) as exc:
raise HTTPException(
status_code=422,
detail=f"Invalid attachment data for {item.filename or 'file'}",
) from exc
if len(data) > max_file_bytes:
raise HTTPException(
status_code=413,
detail=f"Attachment too large: {item.filename or 'file'}",
)
if total_bytes + len(data) > max_total_bytes:
raise HTTPException(status_code=413, detail="Attachment batch too large")
total_bytes += len(data)
filename = safe_filename(item.filename or "attachment") or "attachment"
path = media_dir / f"{uuid4().hex[:12]}_{filename}"
path.write_bytes(data)
media_paths.append(str(path))
return media_paths
@router.post("/{partner_id}/chat", dependencies=_USABLE)
async def partner_chat_http(partner_id: str, payload: ChatMessageRequest) -> dict[str, Any]:
"""Send one HTTP message to a partner with persistent session context."""
content = payload.content.strip()
if not content and not payload.attachments:
raise HTTPException(status_code=400, detail=t("api.content_required"))
# Web chat is a first-class entry point. Start the partner runtime on
# demand even when external channel listeners are not configured for boot;
# ``auto_start`` controls restart persistence, not chat access.
await _ensure_running_partner(partner_id, allow_stopped=True)
media_paths = _materialize_partner_attachments(partner_id, payload.attachments)
if not content and media_paths:
content = _default_attachment_prompt(payload.attachments)
mgr = get_partner_manager()
session_id, chat_id = _resolve_http_session(payload)
try:
lock = (
mgr.web_session_idle_lock(partner_id, payload.session_key)
if payload.session_key
else nullcontext()
)
with lock:
if payload.session_key:
_assert_selected_web_session(partner_id, get_current_user().id, payload.session_key)
response = await mgr.send_message(
partner_id,
content,
chat_id=chat_id,
session_id=session_id,
media=media_paths,
session_key=payload.session_key,
)
except PartnerStaleSessionError as exc:
raise HTTPException(
status_code=409,
detail={"message": str(exc), "active_session_key": exc.active_session_key},
) from None
except PartnerTurnBusyError as exc:
raise HTTPException(status_code=409, detail=str(exc)) from None
except RuntimeError as exc:
raise HTTPException(status_code=400, detail=str(exc)) from None
return {
"partner_id": partner_id,
"session_id": session_id,
"content": response,
}
async def _partner_chat_stream(
partner_id: str,
payload: ChatMessageRequest,
account_id: str,
) -> AsyncGenerator[str, None]:
from deeptutor.core.stream import StreamEventType
mgr = get_partner_manager()
content = payload.content.strip()
if not content and not payload.attachments:
yield _sse("error", {"detail": t("api.content_required")})
return
media_paths = _materialize_partner_attachments(partner_id, payload.attachments)
if not content and media_paths:
content = _default_attachment_prompt(payload.attachments)
session_id, chat_id = _resolve_http_session(payload)
queue: asyncio.Queue[dict[str, Any]] = asyncio.Queue()
done = asyncio.Event()
holder: dict[str, Any] = {}
async def on_event(event: Any) -> None:
if event.type == StreamEventType.THINKING and event.content:
await queue.put({"event": "thinking", "payload": {"content": event.content}})
async def run() -> None:
try:
lock = (
mgr.web_session_idle_lock(partner_id, payload.session_key)
if payload.session_key
else nullcontext()
)
with lock:
if payload.session_key:
_assert_selected_web_session(partner_id, account_id, payload.session_key)
holder["content"] = await mgr.send_message(
partner_id,
content,
chat_id=chat_id,
session_id=session_id,
media=media_paths,
on_event=on_event,
session_key=payload.session_key,
)
except Exception as exc: # noqa: BLE001
holder["error"] = str(exc)
finally:
done.set()
yield _sse("session", {"partner_id": partner_id, "session_id": session_id})
task = asyncio.create_task(run())
try:
while not done.is_set():
try:
item = await asyncio.wait_for(queue.get(), timeout=0.15)
except asyncio.TimeoutError:
continue
yield _sse(item["event"], item["payload"])
while not queue.empty():
item = queue.get_nowait()
yield _sse(item["event"], item["payload"])
if holder.get("error"):
yield _sse("error", {"detail": holder["error"]})
return
yield _sse("content", {"content": holder.get("content", "")})
yield _sse("done", {"partner_id": partner_id, "session_id": session_id})
finally:
if not task.done():
task.cancel()
@router.post("/{partner_id}/chat/execute-stream", dependencies=_USABLE)
async def partner_chat_http_stream(partner_id: str, payload: ChatMessageRequest):
"""Stream one HTTP message to a partner as server-sent events."""
if not payload.content.strip() and not payload.attachments:
raise HTTPException(status_code=400, detail=t("api.content_required"))
await _ensure_running_partner(partner_id, allow_stopped=True)
return StreamingResponse(
_partner_chat_stream(partner_id, payload, get_current_user().id),
media_type="text/event-stream",
headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
)
@ws_router.websocket("/{partner_id}")
async def partner_chat_ws(ws: WebSocket, partner_id: str):
"""Web chat socket.
Client → server: ``{"content": str, "session_id"?: str, "chat_id"?: str,
"attachments"?: [{"type", "filename", "mime_type", "base64"}]}``.
Server → client frames:
* ``{"type": "stream_event", "event": {...}}`` — every chat-loop
StreamEvent (content/thinking/tool_call/progress/sources/result),
letting the UI render the same live trace as product chat;
* ``{"type": "content", "content": str}`` — the final reply;
* ``{"type": "ready"}`` — the runtime is ready to accept a web turn;
* ``{"type": "done"}`` / ``{"type": "error"}`` / ``{"type": "proactive"}``.
"""
from deeptutor.api.routers.auth import ws_auth_failed, ws_require_auth
from deeptutor.multi_user.context import get_current_user_or_none, reset_current_user
from deeptutor.services.partners.interaction import personal_actor_id
user_token = await ws_require_auth(ws)
if user_token is ws_auth_failed:
return
mgr = get_partner_manager()
# The HTTP path dependencies can't run on a socket, so the same check is
# made by hand: an unknown partner and one the caller may not talk to close
# identically. ``ws_require_auth`` has already bound the current user, so
# the token has to be released on this early exit too.
if not mgr.partner_exists(partner_id) or not can_use_partner(partner_id):
if user_token is not None:
reset_current_user(user_token)
await ws.close(code=4404)
return
disconnected = asyncio.Event()
async def _safe_send(payload: dict) -> bool:
try:
await ws.send_json(payload)
return True
except (WebSocketDisconnect, RuntimeError):
disconnected.set()
return False
await ws.accept()
try:
instance = await _ensure_running_partner(partner_id, allow_stopped=True)
except HTTPException as exc:
message = str(exc.detail)
await _safe_send({"type": "error", "content": message})
code = 4004 if exc.status_code == 404 else 4003
await ws.close(code=code, reason=message[:120])
return
if not await _safe_send({"type": "ready"}):
return
logger.info("WebSocket connected for partner '%s'", partner_id)
activity_actor_id = personal_actor_id(get_current_user_or_none())
activity_actor_ids = (
(activity_actor_id, None)
if activity_actor_id is not None and can_manage_partner(partner_id)
else (activity_actor_id,)
)
# Web turns run on the partner instance (see LiveTurn), NOT tied to this
# socket — so a refresh reattaches and replays instead of killing the turn.
# The socket just drains a subscriber queue; the receive loop stays free to
# process stop / attach frames concurrently.
drain: dict[str, asyncio.Task | None] = {"task": None}
activity: dict[str, asyncio.Queue | None] = {"queue": None}
activity_attached = asyncio.Event()
async def _drain(queue: asyncio.Queue) -> None:
while True:
frame = await queue.get()
if not await _safe_send(frame):
return
if frame.get("type") in {"done", "stopped"}:
return
def _start_drain(queue: asyncio.Queue) -> None:
prev = drain["task"]
if prev is not None and not prev.done():
prev.cancel()
drain["task"] = asyncio.create_task(_drain(queue))
def _resolve_key(data: dict[str, Any]) -> str:
return str(
data.get("session_key")
or mgr.web_session_key(
partner_id,
chat_id=data.get("chat_id", "web"),
session_id=data.get("session_id"),
)
)
async def _handle_user_messages():
while not disconnected.is_set():
try:
raw = await ws.receive_text()
except WebSocketDisconnect:
disconnected.set()
break
try:
data = json.loads(raw)
except json.JSONDecodeError:
if not await _safe_send({"type": "error", "content": "Invalid JSON"}):
break
continue
action = data.get("action")
if action == "stop":
mgr.stop_web_turn(partner_id, _resolve_key(data))
continue
if action == "attach":
# The same attachment that follows the history request also
# starts the cross-channel activity feed. The feed replays a
# bounded recent window, and persisted activity ids let the
# client remove any overlap with the history snapshot.
if activity["queue"] is None and data.get("include_activity", True):
activity["queue"] = instance.activity_feed.subscribe_many(activity_actor_ids)
activity_attached.set()
# Reconnect (a page refresh) — replay an in-flight turn so the
# streaming answer the user was watching survives the reload.
turn = mgr.subscribe_web_turn(partner_id, _resolve_key(data))
if turn is not None:
await _safe_send({"type": "resuming"})
if turn.user_content:
await _safe_send({"type": "user_echo", "content": turn.user_content})
_start_drain(turn.subscribe())
else:
key = _resolve_key(data)
frame_type = (
"attach_busy" if mgr.web_session_is_busy(partner_id, key) else "attach_idle"
)
await _safe_send({"type": frame_type, "session_key": key})
continue
content = data.get("content", "").strip()
try:
attachments = [
ChatAttachmentRequest.model_validate(item)
for item in (data.get("attachments") or [])
if isinstance(item, dict)
]
except ValidationError:
if not await _safe_send({"type": "error", "content": "Invalid attachments"}):
break
continue
if not content and not attachments:
continue
try:
media_paths = _materialize_partner_attachments(partner_id, attachments)
except HTTPException as exc:
if not await _safe_send({"type": "error", "content": str(exc.detail)}):
break
continue
if not content and media_paths:
content = _default_attachment_prompt(attachments)
try:
session_key = _resolve_key(data)
turn = mgr.start_web_turn(
partner_id,
session_key,
content,
media_paths,
account_id=get_current_user_or_none().id
if get_current_user_or_none()
else None,
)
except PartnerStaleSessionError as exc:
if not await _safe_send(
{
"type": "stale_session",
"content": str(exc),
"active_session_key": exc.active_session_key,
}
):
break
continue
except PartnerTurnBusyError as exc:
if not await _safe_send({"type": "turn_busy", "content": str(exc)}):
break
continue
except ValueError as exc:
if not await _safe_send({"type": "error", "content": str(exc)}):
break
continue
except RuntimeError as exc:
if not await _safe_send({"type": "error", "content": str(exc)}):
break
continue
# Admission is distinct from execution: a later error can happen
# after the question was persisted, so clients must not restore it
# as a rejected draft and accidentally submit it twice.
if not await _safe_send({"type": "accepted", "session_key": session_key}):
break
_start_drain(turn.subscribe())
async def _handle_channel_activity():
await activity_attached.wait()
while not disconnected.is_set():
queue = activity["queue"]
if queue is None:
return
get_task = asyncio.create_task(queue.get())
wait_task = asyncio.create_task(disconnected.wait())
done, pending = await asyncio.wait(
{get_task, wait_task},
return_when=asyncio.FIRST_COMPLETED,
)
for t in pending:
t.cancel()
if get_task not in done:
break
if not await _safe_send(get_task.result()):
break
user_task = asyncio.create_task(_handle_user_messages())
activity_task = asyncio.create_task(_handle_channel_activity())
try:
done, pending = await asyncio.wait(
[user_task, activity_task],
return_when=asyncio.FIRST_COMPLETED,
)
disconnected.set()
for t in pending:
t.cancel()
for t in done:
if t.exception() and not isinstance(t.exception(), WebSocketDisconnect):
logger.exception(
"WebSocket task error for partner '%s'",
partner_id,
exc_info=t.exception(),
)
except Exception:
disconnected.set()
user_task.cancel()
activity_task.cancel()
finally:
# Detach from the stream only — the turn keeps running on the instance
# so a reconnecting client can reattach and replay it.
d = drain["task"]
if d is not None and not d.done():
d.cancel()
activity_queue = activity["queue"]
if activity_queue is not None:
instance.activity_feed.unsubscribe_many(activity_actor_ids, activity_queue)
if user_token is not None:
try:
reset_current_user(user_token)
except Exception:
pass
logger.info("WebSocket closed for partner '%s'", partner_id)