@researai/deepscientist 1.5.0 → 1.5.1

package/src/deepscientist/bash_exec/service.py

@@ -8,6 +8,7 @@ import shutil
 import signal
 import subprocess
 import sys
+import tempfile
 import threading
 import time
 from pathlib import Path
@@ -15,6 +16,7 @@ from typing import Any
 
 from ..mcp.context import McpContext
 from ..shared import append_jsonl, ensure_dir, generate_id, read_json, read_jsonl, utc_now
+from .runtime import TerminalRuntimeManager
 
 BASH_STATUS_MARKER_PREFIX = "__DS_BASH_STATUS__"
 BASH_CARRIAGE_RETURN_PREFIX = "__DS_BASH_CR__"
@@ -29,11 +31,16 @@ INPUT_ESCAPE_SEQUENCE_RE = re.compile(r"\x1b\[[0-9;?]*[ -/]*[@-~]|\x1b[@-_]")
 
 def _atomic_write_json(path: Path, payload: Any) -> None:
     ensure_dir(path.parent)
-    temp_path = path.with_suffix(f"{path.suffix}.tmp")
-    temp_path.write_text(
-        json.dumps(payload, indent=2, ensure_ascii=False, sort_keys=False) + "\n",
+    with tempfile.NamedTemporaryFile(
+        "w",
         encoding="utf-8",
-    )
+        dir=path.parent,
+        prefix=f"{path.name}.",
+        suffix=".tmp",
+        delete=False,
+    ) as handle:
+        handle.write(json.dumps(payload, indent=2, ensure_ascii=False, sort_keys=False) + "\n")
+        temp_path = Path(handle.name)
     temp_path.replace(path)
 
 
@@ -87,6 +94,7 @@ class BashExecService:
         self.home = home
         self._summary_cache_lock = threading.Lock()
         self._summary_cache: dict[str, dict[str, Any]] = {}
+        self._terminal_runtime_manager = TerminalRuntimeManager(home)
 
     def _quest_root(self, quest_id: str) -> Path:
         return self.home / "quests" / quest_id
@@ -130,6 +138,9 @@ class BashExecService:
     def terminal_rc_path(self, quest_root: Path, bash_id: str) -> Path:
         return self.session_dir(quest_root, bash_id) / "terminal.rc"
 
+    def prompt_events_path(self, quest_root: Path, bash_id: str) -> Path:
+        return self.session_dir(quest_root, bash_id) / "prompt-events.log"
+
     def monitor_log_path(self, quest_root: Path, bash_id: str) -> Path:
         return self.session_dir(quest_root, bash_id) / "monitor.log"
 
@@ -358,9 +369,27 @@ class BashExecService:
         status = _coerce_session_status(meta.get("status"))
         if status in TERMINAL_STATUSES:
             return self._session_payload(quest_root, meta)
+        kind = _normalize_string(meta.get("kind")).lower()
+        if kind == "terminal":
+            runtime = self._terminal_runtime_manager.get_runtime(quest_root, bash_id)
+            if runtime is not None:
+                return self._session_payload(quest_root, read_json(meta_path, meta) or meta)
         monitor_pid = meta.get("monitor_pid")
         process_pid = meta.get("process_pid")
-        if _is_process_alive(process_pid) or _is_process_alive(monitor_pid):
+        if kind == "terminal" and _is_process_alive(process_pid):
+            process_group_id = meta.get("process_group_id")
+            if isinstance(process_group_id, int) and process_group_id > 0:
+                try:
+                    os.killpg(process_group_id, signal.SIGTERM)
+                except ProcessLookupError:
+                    pass
+            elif isinstance(process_pid, int) and process_pid > 0:
+                try:
+                    os.kill(process_pid, signal.SIGTERM)
+                except ProcessLookupError:
+                    pass
+            time.sleep(0.05)
+        if kind != "terminal" and (_is_process_alive(process_pid) or _is_process_alive(monitor_pid)):
             return self._session_payload(quest_root, meta)
         stop_reason = _normalize_string(meta.get("stop_reason"))
         meta["status"] = "terminated" if stop_reason else "failed"
@@ -509,12 +538,16 @@ class BashExecService:
         meta["stopped_by_user_id"] = request_payload["user_id"]
         meta["updated_at"] = utc_now()
         self._write_meta(quest_root, bash_id, meta)
-        process_group_id = meta.get("process_group_id")
-        if isinstance(process_group_id, int) and process_group_id > 0:
-            try:
-                os.killpg(process_group_id, signal.SIGTERM)
-            except ProcessLookupError:
-                pass
+        runtime = self._terminal_runtime_manager.get_runtime(quest_root, bash_id)
+        if runtime is not None:
+            runtime.stop(reason=request_payload["reason"], force=False)
+        else:
+            process_group_id = meta.get("process_group_id")
+            if isinstance(process_group_id, int) and process_group_id > 0:
+                try:
+                    os.killpg(process_group_id, signal.SIGTERM)
+                except ProcessLookupError:
+                    pass
         return self._session_payload(quest_root, meta)
 
     def _build_initial_meta(
@@ -724,7 +757,12 @@ class BashExecService:
         resolved_quest_id = _normalize_string(quest_id) or resolved_quest_root.name
         try:
             session = self.reconcile_session(resolved_quest_root, bash_id)
-            if _normalize_string(session.get("kind")).lower() == "terminal" and _normalize_string(session.get("status")).lower() not in TERMINAL_STATUSES:
+            runtime = self._terminal_runtime_manager.get_runtime(resolved_quest_root, bash_id)
+            if (
+                _normalize_string(session.get("kind")).lower() == "terminal"
+                and _normalize_string(session.get("status")).lower() not in TERMINAL_STATUSES
+                and runtime is not None
+            ):
                 return session
         except FileNotFoundError:
             session = None
@@ -747,6 +785,7 @@ class BashExecService:
         self.log_path(resolved_quest_root, bash_id).touch()
         self.input_path(resolved_quest_root, bash_id).touch()
         self.history_path(resolved_quest_root, bash_id).touch()
+        self.prompt_events_path(resolved_quest_root, bash_id).touch()
         _atomic_write_json(
             self.input_cursor_path(resolved_quest_root, bash_id),
             {"offset": len(read_jsonl(self.input_path(resolved_quest_root, bash_id))), "updated_at": utc_now()},
@@ -759,9 +798,9 @@ class BashExecService:
         terminal_rc_path.write_text(
             "\n".join(
                 [
-                    "PS1=''",
-                    "PS2=''",
-                    'PROMPT_COMMAND=\'printf "__DS_TERMINAL_PROMPT__ cwd=%q ts=%s\\\\n" "$PWD" "$(date -u +%FT%TZ)"\'',
+                    "PS1='\\w$ '",
+                    "PS2='> '",
+                    'PROMPT_COMMAND=\'printf "__DS_TERMINAL_PROMPT__ cwd=%q ts=%s\\n" "$PWD" "$(date -u +%FT%TZ)" >> "${DS_TERMINAL_PROMPT_PATH}"\'',
                     "bind 'set enable-bracketed-paste off' >/dev/null 2>&1 || true",
                     "",
                 ]
@@ -775,6 +814,7 @@ class BashExecService:
         env_payload = {
             "TERM": "xterm-256color",
             "COLORTERM": "truecolor",
+            "DS_TERMINAL_PROMPT_PATH": str(self.prompt_events_path(resolved_quest_root, bash_id)),
         }
         command = f"exec bash --noprofile --rcfile {shlex.quote(str(terminal_rc_path))} -i"
         resolved_label = _normalize_string(label) or previous_label
@@ -803,10 +843,16 @@ class BashExecService:
                 "started_at": meta["started_at"],
             },
         )
-        meta["monitor_pid"] = self._start_monitor_process(
+        meta = self._terminal_runtime_manager.ensure_runtime(
             quest_root=resolved_quest_root,
             bash_id=bash_id,
+            meta_path=self.meta_path(resolved_quest_root, bash_id),
+            log_path=self.log_path(resolved_quest_root, bash_id),
+            terminal_log_path=self.terminal_log_path(resolved_quest_root, bash_id),
+            prompt_events_path=self.prompt_events_path(resolved_quest_root, bash_id),
             env_payload=env_payload,
+            command=command,
+            cwd=target_cwd,
         )
         meta["updated_at"] = utc_now()
         self._write_meta(resolved_quest_root, bash_id, meta)
@@ -870,6 +916,10 @@ class BashExecService:
         status = _normalize_string(session.get("status")).lower()
         if status in TERMINAL_STATUSES:
             raise ValueError("terminal_session_inactive")
+        runtime = self._terminal_runtime_manager.get_runtime(quest_root, bash_id)
+        if runtime is None:
+            raise ValueError("terminal_runtime_inactive")
+        runtime.write_input(normalized_data)
 
         entry = {
             "input_id": generate_id("tin"),
@@ -909,6 +959,39 @@ class BashExecService:
             "completed_commands": completed,
         }
 
+    def resize_terminal_session(self, quest_root: Path, bash_id: str, *, cols: int, rows: int) -> bool:
+        runtime = self._terminal_runtime_manager.get_runtime(quest_root, bash_id)
+        if runtime is None:
+            return False
+        runtime.resize(cols, rows)
+        return True
+
+    def issue_terminal_attach_token(self, quest_root: Path, bash_id: str, *, ttl_seconds: int = 60) -> dict[str, Any]:
+        runtime = self._terminal_runtime_manager.get_runtime(quest_root, bash_id)
+        if runtime is None:
+            raise ValueError("terminal_runtime_inactive")
+        token = self._terminal_runtime_manager.issue_attach_token(
+            quest_root,
+            bash_id,
+            ttl_seconds=ttl_seconds,
+        )
+        return {
+            "token": token.token,
+            "expires_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(token.expires_at)),
+        }
+
+    def get_terminal_runtime(self, quest_root: Path, bash_id: str):
+        return self._terminal_runtime_manager.get_runtime(quest_root, bash_id)
+
+    def consume_terminal_attach_token(self, token: str):
+        return self._terminal_runtime_manager.consume_attach_token(token)
+
+    def resolve_terminal_attach_token(self, token: str):
+        return self._terminal_runtime_manager.resolve_attach_token(token)
+
+    def shutdown(self) -> None:
+        self._terminal_runtime_manager.shutdown()
+
     def terminal_restore_payload(
         self,
         quest_root: Path,

package/src/deepscientist/bridges/base.py

@@ -44,6 +44,7 @@ class BaseConnectorBridge:
             "message": self.render_text(payload.get("text"), payload.get("attachments")),
             "reply_to_message_id": payload.get("reply_to_message_id"),
             "attachments": payload.get("attachments") or [],
+            "connector_hints": payload.get("connector_hints") or {},
             "quest_id": payload.get("quest_id"),
             "quest_root": payload.get("quest_root"),
             "importance": payload.get("importance"),
@@ -96,6 +97,8 @@ class BaseConnectorBridge:
             if isinstance(item, str):
                 attachment_lines.append(f"- {item}")
             elif isinstance(item, dict):
+                if str(item.get("path_error") or "").strip():
+                    continue
                 candidate = item.get("label") or item.get("path") or item.get("url")
                 if candidate:
                     attachment_lines.append(f"- {candidate}")

package/src/deepscientist/bridges/connectors.py

@@ -1,11 +1,13 @@
 from __future__ import annotations
 
+import base64
 import json
 import time
 from hashlib import sha256
 from hmac import new as hmac_new
 from pathlib import Path
 from typing import Any
+from urllib.error import HTTPError
 from urllib.request import Request, urlopen
 
 from ..shared import append_jsonl, ensure_dir, utc_now
@@ -396,6 +398,8 @@ class DiscordConnectorBridge(BaseConnectorBridge):
 class QQConnectorBridge(BaseConnectorBridge):
     name = "qq"
     _token_cache: dict[str, dict[str, float | str]] = {}
+    _IMAGE_FILE_TYPE = 1
+    _FILE_FILE_TYPE = 4
 
     def parse_webhook(self, *, method: str, headers: dict[str, str], query: dict[str, list[str]], raw_body: bytes, body: dict[str, Any] | None, config: dict[str, Any]) -> BridgeWebhookResult:
         return BridgeWebhookResult(
@@ -412,18 +416,21 @@ class QQConnectorBridge(BaseConnectorBridge):
 
     def format_outbound(self, payload: dict[str, Any], config: dict[str, Any]) -> dict[str, Any]:
         target = self.extract_target(payload.get("conversation_id"))
-        message_body: dict[str, Any] = {
-            "content": self.render_text(payload.get("text"), payload.get("attachments")),
-            "msg_type": 0,
-        }
         reply_to = str(payload.get("reply_to_message_id") or "").strip()
-        if reply_to:
-            message_body["msg_id"] = reply_to
-            message_body["msg_seq"] = max(int(time.time() * 1000) % 65536, 1)
+        requested_render_mode = self._requested_render_mode(payload)
+        render_mode, render_mode_warning = self._effective_render_mode(requested_render_mode, config)
+        native_attachments, residual_attachments, attachment_issues = self._partition_native_attachments(payload.get("attachments"), config)
+        text = self.render_text(payload.get("text"), residual_attachments)
         return {
             "chat_type": target["chat_type"],
             "chat_id": target["chat_id"],
-            "body": message_body,
+            "reply_to_message_id": reply_to or None,
+            "requested_render_mode": requested_render_mode,
+            "render_mode": render_mode,
+            "render_mode_warning": render_mode_warning,
+            "text": text,
+            "native_attachments": native_attachments,
+            "attachment_issues": attachment_issues,
         }
 
     def deliver_direct(self, payload: dict[str, Any], config: dict[str, Any]) -> dict[str, Any] | None:
@@ -437,17 +444,289 @@ class QQConnectorBridge(BaseConnectorBridge):
         if chat_type not in {"direct", "group"} or not chat_id:
             return None
         access_token = self._access_token(app_id, app_secret)
-        endpoint = (
+        reply_to = str(formatted.get("reply_to_message_id") or "").strip() or None
+        text = str(formatted.get("text") or "").strip()
+        render_mode = str(formatted.get("render_mode") or "plain").strip().lower()
+        native_attachments = [dict(item) for item in (formatted.get("native_attachments") or []) if isinstance(item, dict)]
+        attachment_issues = [dict(item) for item in (formatted.get("attachment_issues") or []) if isinstance(item, dict)]
+        parts: list[dict[str, Any]] = []
+        warnings: list[str] = []
+        if str(formatted.get("render_mode_warning") or "").strip():
+            warnings.append(str(formatted.get("render_mode_warning")).strip())
+        for issue in attachment_issues:
+            error = str(issue.get("error") or "").strip()
+            if error:
+                warnings.append(error)
+        if text or not native_attachments:
+            text_result = self._send_text_message(
+                access_token=access_token,
+                chat_type=chat_type,
+                chat_id=chat_id,
+                text=text,
+                reply_to_message_id=reply_to,
+                render_mode=render_mode,
+            )
+            parts.append({"part": "text", "render_mode": render_mode, **text_result})
+        for index, attachment in enumerate(native_attachments, start=1):
+            media_kind = str(attachment.get("qq_media_kind") or "file").strip()
+            media_result = self._send_media_attachment(
+                access_token=access_token,
+                chat_type=chat_type,
+                chat_id=chat_id,
+                attachment=attachment,
+                reply_to_message_id=reply_to,
+            )
+            parts.append(
+                {
+                    "part": f"attachment_{index}",
+                    "media_kind": media_kind,
+                    "path": attachment.get("path"),
+                    "url": attachment.get("url"),
+                    **media_result,
+                }
+            )
+        succeeded = [item for item in parts if bool(item.get("ok", False))]
+        failed = [item for item in parts if not bool(item.get("ok", False))]
+        error_messages = [str(item.get("error") or "").strip() for item in failed if str(item.get("error") or "").strip()]
+        error_messages.extend(warnings)
+        last_success = succeeded[-1] if succeeded else {}
+        return {
+            "ok": bool(succeeded),
+            "queued": False,
+            "partial": bool(succeeded and (failed or warnings)),
+            "transport": "qq-http",
+            "status_code": last_success.get("status_code") or (failed[-1].get("status_code") if failed else None),
+            "message_id": last_success.get("message_id"),
+            "response": str(last_success.get("response") or "").strip()[:500] or None,
+            "parts": parts,
+            "warnings": warnings,
+            "error": "; ".join(error_messages) if error_messages else None,
+        }
+
+    @staticmethod
+    def _requested_render_mode(payload: dict[str, Any]) -> str:
+        connector_hints = payload.get("connector_hints") if isinstance(payload.get("connector_hints"), dict) else {}
+        qq_hints = connector_hints.get("qq") if isinstance(connector_hints.get("qq"), dict) else {}
+        requested = str(qq_hints.get("render_mode") or "auto").strip().lower()
+        return requested if requested in {"auto", "plain", "markdown"} else "auto"
+
+    @staticmethod
+    def _effective_render_mode(requested: str, config: dict[str, Any]) -> tuple[str, str | None]:
+        markdown_enabled = bool(config.get("enable_markdown_send", False))
+        if requested == "markdown" and not markdown_enabled:
+            return "plain", "QQ markdown send was requested, but `enable_markdown_send` is disabled."
+        if requested == "markdown":
+            return "markdown", None
+        return "plain", None
+
+    @classmethod
+    def _partition_native_attachments(
+        cls,
+        attachments: Any,
+        config: dict[str, Any],
+    ) -> tuple[list[dict[str, Any]], list[dict[str, Any]], list[dict[str, Any]]]:
+        native_enabled = bool(config.get("enable_file_upload_experimental", False))
+        native_items: list[dict[str, Any]] = []
+        residual_items: list[dict[str, Any]] = []
+        issues: list[dict[str, Any]] = []
+        for index, raw_item in enumerate(attachments if isinstance(attachments, list) else [], start=1):
+            if not isinstance(raw_item, dict):
+                continue
+            item = dict(raw_item)
+            if str(item.get("path_error") or "").strip():
+                issues.append(
+                    {
+                        "attachment_index": index,
+                        "error": f"attachment {index}: path resolution failed for {item.get('path')}",
+                    }
+                )
+                continue
+            connector_delivery = item.get("connector_delivery") if isinstance(item.get("connector_delivery"), dict) else {}
+            qq_delivery = connector_delivery.get("qq") if isinstance(connector_delivery.get("qq"), dict) else {}
+            media_kind = str(qq_delivery.get("media_kind") or "").strip().lower()
+            if media_kind not in {"image", "file"}:
+                residual_items.append(item)
+                continue
+            if not native_enabled:
+                issues.append(
+                    {
+                        "attachment_index": index,
+                        "error": (
+                            f"attachment {index}: QQ native media send is disabled by "
+                            "`enable_file_upload_experimental`."
+                        ),
+                    }
+                )
+                continue
+            source_path = str(item.get("path") or "").strip()
+            source_url = str(item.get("url") or "").strip()
+            if not source_path and not source_url:
+                issues.append(
+                    {
+                        "attachment_index": index,
+                        "error": f"attachment {index}: QQ {media_kind} send requires `path` or `url`.",
+                    }
+                )
+                continue
+            item["qq_media_kind"] = media_kind
+            native_items.append(item)
+        return native_items, residual_items, issues
+
+    @staticmethod
+    def _message_endpoint(chat_type: str, chat_id: str) -> str:
+        return (
             f"https://api.sgroup.qq.com/v2/users/{chat_id}/messages"
             if chat_type == "direct"
             else f"https://api.sgroup.qq.com/v2/groups/{chat_id}/messages"
         )
-        request = Request(endpoint, data=json.dumps(formatted["body"], ensure_ascii=False).encode("utf-8"), method="POST")
+
+    @staticmethod
+    def _files_endpoint(chat_type: str, chat_id: str) -> str:
+        return (
+            f"https://api.sgroup.qq.com/v2/users/{chat_id}/files"
+            if chat_type == "direct"
+            else f"https://api.sgroup.qq.com/v2/groups/{chat_id}/files"
+        )
+
+    @staticmethod
+    def _message_seq(reply_to_message_id: str | None) -> int | None:
+        if not reply_to_message_id:
+            return None
+        return max(int(time.time() * 1000) % 65536, 1)
+
+    def _send_text_message(
+        self,
+        *,
+        access_token: str,
+        chat_type: str,
+        chat_id: str,
+        text: str,
+        reply_to_message_id: str | None,
+        render_mode: str,
+    ) -> dict[str, Any]:
+        if not text.strip():
+            return {"ok": False, "error": "QQ text message content is empty."}
+        body: dict[str, Any]
+        if render_mode == "markdown":
+            body = {"markdown": {"content": text}, "msg_type": 2}
+        else:
+            body = {"content": text, "msg_type": 0}
+        msg_seq = self._message_seq(reply_to_message_id)
+        if msg_seq is not None:
+            body["msg_seq"] = msg_seq
+        if reply_to_message_id:
+            body["msg_id"] = reply_to_message_id
+        return self._post_json(
+            endpoint=self._message_endpoint(chat_type, chat_id),
+            access_token=access_token,
+            body=body,
+        )
+
+    def _send_media_attachment(
+        self,
+        *,
+        access_token: str,
+        chat_type: str,
+        chat_id: str,
+        attachment: dict[str, Any],
+        reply_to_message_id: str | None,
+    ) -> dict[str, Any]:
+        media_kind = str(attachment.get("qq_media_kind") or "file").strip().lower()
+        upload_payload: dict[str, Any] = {
+            "file_type": self._IMAGE_FILE_TYPE if media_kind == "image" else self._FILE_FILE_TYPE,
+            "srv_send_msg": False,
+        }
+        url_value = str(attachment.get("url") or "").strip()
+        path_value = str(attachment.get("path") or "").strip()
+        try:
+            if url_value:
+                upload_payload["url"] = url_value
+            elif path_value:
+                payload, file_name = self._file_data_payload(Path(path_value), media_kind=media_kind)
+                upload_payload["file_data"] = payload
+                if media_kind == "file" and file_name:
+                    upload_payload["file_name"] = file_name
+            else:
+                return {"ok": False, "error": "QQ native media send requires `path` or `url`."}
+        except Exception as exc:
+            return {"ok": False, "error": str(exc)}
+        upload_result = self._post_json(
+            endpoint=self._files_endpoint(chat_type, chat_id),
+            access_token=access_token,
+            body=upload_payload,
+        )
+        if not upload_result.get("ok", False):
+            upload_result["error"] = str(upload_result.get("error") or "QQ media upload failed.").strip()
+            return upload_result
+        file_info = str(upload_result.get("payload", {}).get("file_info") or "").strip()
+        if not file_info:
+            return {
+                "ok": False,
+                "error": "QQ media upload succeeded but returned no `file_info`.",
+                "status_code": upload_result.get("status_code"),
+                "response": upload_result.get("response"),
+            }
+        message_body: dict[str, Any] = {
+            "msg_type": 7,
+            "media": {"file_info": file_info},
+        }
+        msg_seq = self._message_seq(reply_to_message_id)
+        if msg_seq is not None:
+            message_body["msg_seq"] = msg_seq
+        if reply_to_message_id:
+            message_body["msg_id"] = reply_to_message_id
+        send_result = self._post_json(
+            endpoint=self._message_endpoint(chat_type, chat_id),
+            access_token=access_token,
+            body=message_body,
+        )
+        if not send_result.get("ok", False):
+            send_result["error"] = str(send_result.get("error") or "QQ media message send failed.").strip()
+        return send_result
+
+    @staticmethod
+    def _file_data_payload(path: Path, *, media_kind: str) -> tuple[str, str]:
+        if not path.exists():
+            raise FileNotFoundError(f"QQ native {media_kind} attachment path does not exist: {path}")
+        payload = base64.b64encode(path.read_bytes()).decode("utf-8")
+        return payload, path.name
+
+    def _post_json(self, *, endpoint: str, access_token: str, body: dict[str, Any]) -> dict[str, Any]:
+        request = Request(endpoint, data=json.dumps(body, ensure_ascii=False).encode("utf-8"), method="POST")
         request.add_header("Content-Type", "application/json; charset=utf-8")
         request.add_header("Authorization", f"QQBot {access_token}")
-        with urlopen(request, timeout=8) as response:  # noqa: S310
-            response_text = response.read().decode("utf-8", errors="replace")
-            return {"ok": 200 <= response.status < 300, "status_code": response.status, "response": response_text[:500], "transport": "qq-http"}
+        try:
+            with urlopen(request, timeout=8) as response:  # noqa: S310
+                response_text = response.read().decode("utf-8", errors="replace")
+                payload = json.loads(response_text) if response_text else {}
+                return {
+                    "ok": 200 <= response.status < 300,
+                    "status_code": response.status,
+                    "response": response_text[:500],
+                    "payload": payload if isinstance(payload, dict) else {},
+                    "message_id": str((payload or {}).get("id") or "").strip() or None,
+                }
+        except HTTPError as exc:
+            response_text = exc.read().decode("utf-8", errors="replace")
+            try:
+                payload = json.loads(response_text) if response_text else {}
+            except json.JSONDecodeError:
+                payload = {}
+            return {
+                "ok": False,
+                "status_code": exc.code,
+                "response": response_text[:500],
+                "payload": payload if isinstance(payload, dict) else {},
+                "error": str((payload or {}).get("message") or response_text or exc.reason).strip() or "QQ HTTP error",
+            }
+        except Exception as exc:  # pragma: no cover - defensive network transport guard
+            return {
+                "ok": False,
+                "status_code": None,
+                "response": None,
+                "payload": {},
+                "error": str(exc),
+            }
 
     @classmethod
     def _access_token(cls, app_id: str, app_secret: str) -> str:

package/src/deepscientist/channels/qq.py

@@ -352,12 +352,15 @@ class QQRelayChannel(BaseChannel):
                 fragments.append(f"Reason: {reason}")
             text = "\n".join(fragments)
         attachments = self._normalize_attachments(payload.get("attachments"))
+        conversation_id = str(payload.get("conversation_id") or "").strip()
         return {
-            "conversation_id": payload.get("conversation_id"),
-            "reply_to_message_id": payload.get("reply_to_message_id"),
+            "conversation_id": conversation_id,
+            "reply_to_message_id": payload.get("reply_to_message_id") or self._reply_to_message_id_for(conversation_id),
             "kind": kind,
             "text": text,
             "attachments": attachments,
+            "surface_actions": [dict(item) for item in (payload.get("surface_actions") or []) if isinstance(item, dict)],
+            "connector_hints": dict(payload.get("connector_hints")) if isinstance(payload.get("connector_hints"), dict) else {},
             "quest_id": payload.get("quest_id"),
             "quest_root": payload.get("quest_root"),
             "importance": payload.get("importance"),
@@ -548,6 +551,20 @@ class QQRelayChannel(BaseChannel):
         events.sort(key=lambda item: (str(item.get("created_at") or ""), str(item.get("conversation_id") or "")), reverse=True)
         return events[: self.recent_event_limit]
 
+    def _reply_to_message_id_for(self, conversation_id: str) -> str | None:
+        normalized = str(conversation_id or "").strip()
+        if not normalized:
+            return None
+        identity = conversation_identity_key(normalized)
+        state = self._read_state()
+        for item in self._recent_conversations(state):
+            if conversation_identity_key(str(item.get("conversation_id") or "").strip()) != identity:
+                continue
+            message_id = str(item.get("message_id") or "").strip()
+            if message_id:
+                return message_id
+        return None
+
     def _build_recent_event(self, event_type: str, record: dict[str, Any]) -> dict[str, Any] | None:
         if not isinstance(record, dict):
             return None

package/src/deepscientist/channels/relay.py

@@ -337,6 +337,7 @@ class GenericRelayChannel(BaseChannel):
             "kind": kind,
             "text": text,
             "attachments": attachments,
+            "surface_actions": [dict(item) for item in (payload.get("surface_actions") or []) if isinstance(item, dict)],
             "quest_id": payload.get("quest_id"),
             "quest_root": payload.get("quest_root"),
             "importance": payload.get("importance"),