@researai/deepscientist 1.5.0 → 1.5.1

package/src/deepscientist/quest/service.py

@@ -1778,7 +1778,13 @@ class QuestService:
             )
         return documents
 
-    def explorer(self, quest_id: str, revision: str | None = None, mode: str | None = None) -> dict:
+    def explorer(
+        self,
+        quest_id: str,
+        revision: str | None = None,
+        mode: str | None = None,
+        profile: str | None = None,
+    ) -> dict:
         if revision:
             return self._revision_explorer(quest_id, revision=revision, mode=mode or "ref")
 
@@ -1796,6 +1802,7 @@ class QuestService:
             workspace_root,
             git_status=git_status,
             changed_paths=changed_paths,
+            profile=profile,
         )
         sections = self._group_explorer_sections(root_nodes)
 
@@ -1807,6 +1814,7 @@ class QuestService:
                 "revision": None,
                 "label": "Latest",
                 "read_only": False,
+                "profile": profile,
             },
             "sections": sections,
         }
@@ -2626,6 +2634,8 @@ class QuestService:
         message: str,
         response_phase: str | None = None,
         reply_mode: str | None = None,
+        surface_actions: list[dict[str, Any]] | None = None,
+        connector_hints: dict[str, Any] | None = None,
         created_at: str | None = None,
     ) -> dict[str, Any]:
         timestamp = created_at or utc_now()
@@ -2639,6 +2649,8 @@ class QuestService:
             "message": message,
             "response_phase": response_phase,
             "reply_mode": reply_mode,
+            "surface_actions": [dict(item) for item in (surface_actions or []) if isinstance(item, dict)],
+            "connector_hints": dict(connector_hints) if isinstance(connector_hints, dict) else {},
             "created_at": timestamp,
         }
         append_jsonl(self._interaction_journal_path(quest_root), payload)
@@ -3025,6 +3037,8 @@ class QuestService:
         *,
         git_status: dict[str, str],
         changed_paths: dict[str, dict],
+        profile: str | None = None,
+        depth: int = 0,
     ) -> list[dict]:
         if not root.exists():
             return []
@@ -3044,6 +3058,9 @@ class QuestService:
             try:
                 if self._skip_explorer_path(quest_root, path):
                     continue
+                relative = path.relative_to(quest_root).as_posix()
+                if self._skip_explorer_profile_relative(relative, profile):
+                    continue
             except OSError:
                 continue
             try:
@@ -3051,7 +3068,19 @@ class QuestService:
             except OSError:
                 continue
             if is_dir:
-                children = self._tree_children(quest_root, path, git_status=git_status, changed_paths=changed_paths)
+                truncate_children = self._truncate_explorer_directory(relative, profile=profile, depth=depth)
+                children = (
+                    []
+                    if truncate_children
+                    else self._tree_children(
+                        quest_root,
+                        path,
+                        git_status=git_status,
+                        changed_paths=changed_paths,
+                        profile=profile,
+                        depth=depth + 1,
+                    )
+                )
                 nodes.append(
                     self._directory_node(
                         quest_root,
@@ -3143,6 +3172,38 @@ class QuestService:
         parts = PurePosixPath(relative).parts
         return "__pycache__" in parts or ".pytest_cache" in parts
 
+    @staticmethod
+    def _skip_explorer_profile_relative(relative: str, profile: str | None) -> bool:
+        if profile != "mobile":
+            return False
+        normalized = relative.strip("/")
+        if not normalized:
+            return False
+        parts = PurePosixPath(normalized).parts
+        top = parts[0] if parts else normalized
+        if top in {".codex", ".claude", ".ds", "tmp", "userfiles", "artifacts"}:
+            return True
+        if top.startswith(".") and normalized not in {".gitignore"}:
+            return True
+        return False
+
+    @staticmethod
+    def _truncate_explorer_directory(relative: str, *, profile: str | None, depth: int) -> bool:
+        if profile != "mobile":
+            return False
+        normalized = relative.strip("/")
+        if not normalized:
+            return False
+        parts = PurePosixPath(normalized).parts
+        top = parts[0] if parts else normalized
+        if top == "memory":
+            return False
+        if top == "baselines":
+            return depth >= 1
+        if top in {"literature", "paper", "experiments", "handoffs"}:
+            return depth >= 2
+        return depth >= 1
+
     @staticmethod
     def _classify_path_scope(quest_root: Path, path: Path) -> tuple[str, bool]:
         relative = path.relative_to(quest_root).as_posix()

package/src/deepscientist/quest/stage_views.py

@@ -1093,7 +1093,8 @@ class QuestStageViewBuilder:
         latest = stage_items[-1] if stage_items else None
         latest_payload = self._payload(latest or {})
         slices = [dict(item) for item in (manifest.get("slices") or []) if isinstance(item, dict)]
-        todo_items = [
+        manifest_todo_items = [dict(item) for item in (manifest.get("todo_items") or []) if isinstance(item, dict)]
+        todo_items = manifest_todo_items or [
             {
                 "todo_id": str(item.get("slice_id") or f"slice-{index}"),
                 "slice_id": str(item.get("slice_id") or f"slice-{index}"),
@@ -1102,6 +1103,11 @@ class QuestStageViewBuilder:
                 "research_question": item.get("research_question"),
                 "experimental_design": item.get("experimental_design"),
                 "completion_condition": item.get("must_not_simplify") or item.get("goal") or "Complete the planned analysis slice.",
+                "why_now": item.get("why_now"),
+                "success_criteria": item.get("success_criteria"),
+                "abandonment_criteria": item.get("abandonment_criteria"),
+                "reviewer_item_ids": item.get("reviewer_item_ids") or [],
+                "manuscript_targets": item.get("manuscript_targets") or [],
             }
             for index, item in enumerate(slices, start=1)
         ]
@@ -1124,8 +1130,17 @@ class QuestStageViewBuilder:
                     "run_kind": item.get("run_kind"),
                     "question": item.get("research_question") or detail_payload.get("question"),
                     "hypothesis": item.get("hypothesis"),
+                    "why_now": item.get("why_now"),
+                    "success_criteria": item.get("success_criteria"),
+                    "abandonment_criteria": item.get("abandonment_criteria"),
+                    "reviewer_item_ids": item.get("reviewer_item_ids") or [],
+                    "manuscript_targets": item.get("manuscript_targets") or [],
                     "status": item.get("status") or run_payload.get("status") or "pending",
                     "metric_summary": run_payload.get("metrics_summary") or {},
+                    "claim_impact": detail_payload.get("claim_impact"),
+                    "reviewer_resolution": detail_payload.get("reviewer_resolution"),
+                    "manuscript_update_hint": detail_payload.get("manuscript_update_hint"),
+                    "next_recommendation": detail_payload.get("next_recommendation"),
                     "deviations": detail_payload.get("deviations") or [],
                     "evidence_paths": detail_payload.get("evidence_paths") or [],
                     "plan_path": item.get("plan_path"),
@@ -1189,11 +1204,14 @@ class QuestStageViewBuilder:
                     "goal": manifest.get("goal"),
                     "parent_run_id": manifest.get("parent_run_id"),
                     "parent_branch": manifest.get("parent_branch") or self.branch_name,
+                    "campaign_origin": manifest.get("campaign_origin"),
                     "selected_outline_ref": manifest.get("selected_outline_ref"),
                     "todo_items": todo_items,
                     "slices": slice_rows,
                     "summary": latest_payload.get("summary"),
                     "manifest_path": manifest.get("_manifest_path"),
+                    "charter_path": manifest.get("charter_path"),
+                    "todo_manifest_path": manifest.get("todo_manifest_path"),
                 }
             },
         )

package/src/deepscientist/runtime_tools/__init__.py

@@ -0,0 +1,16 @@
+from .builtins import register_builtin_runtime_tools
+from .models import RuntimeBinaryMatch, RuntimeTool, RuntimeToolFactory, RuntimeToolStatus
+from .registry import get_runtime_tool_factory, list_runtime_tool_names, register_runtime_tool
+from .service import RuntimeToolService
+
+__all__ = [
+    "RuntimeBinaryMatch",
+    "RuntimeTool",
+    "RuntimeToolFactory",
+    "RuntimeToolService",
+    "RuntimeToolStatus",
+    "get_runtime_tool_factory",
+    "list_runtime_tool_names",
+    "register_builtin_runtime_tools",
+    "register_runtime_tool",
+]

package/src/deepscientist/runtime_tools/builtins.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from .registry import register_runtime_tool
+from .tinytex import TinyTeXRuntimeTool
+
+
+def register_builtin_runtime_tools(*, home=None) -> None:
+    def _tinytex_factory(**kwargs):
+        selected_home = kwargs.get("home") or home
+        if selected_home is None:
+            raise ValueError("Runtime tool factories require `home`.")
+        return TinyTeXRuntimeTool(Path(selected_home))
+
+    register_runtime_tool("tinytex", _tinytex_factory)
+
+
+__all__ = ["register_builtin_runtime_tools"]

package/src/deepscientist/runtime_tools/models.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, Protocol
+
+
+class RuntimeTool(Protocol):
+    tool_name: str
+
+    def status(self) -> dict[str, Any]:
+        ...
+
+    def install(self) -> dict[str, Any]:
+        ...
+
+    def resolve_binary(self, binary: str) -> dict[str, Any]:
+        ...
+
+
+RuntimeToolFactory = Callable[..., RuntimeTool]
+RuntimeBinaryMatch = dict[str, Any]
+RuntimeToolStatus = dict[str, Any]
+
+__all__ = [
+    "RuntimeBinaryMatch",
+    "RuntimeTool",
+    "RuntimeToolFactory",
+    "RuntimeToolStatus",
+]

package/src/deepscientist/runtime_tools/registry.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import re
+
+from .models import RuntimeToolFactory
+
+
+_RUNTIME_TOOL_FACTORIES: dict[str, RuntimeToolFactory] = {}
+_RUNTIME_TOOL_NAME_PATTERN = re.compile(r"^[a-z0-9][a-z0-9_-]*$")
+
+
+def _normalize_runtime_tool_name(name: str) -> str:
+    normalized = str(name or "").strip().lower()
+    if not normalized or not _RUNTIME_TOOL_NAME_PATTERN.fullmatch(normalized):
+        raise ValueError("Runtime tool name must match `^[a-z0-9][a-z0-9_-]*$`.")
+    return normalized
+
+
+def register_runtime_tool(name: str, factory: RuntimeToolFactory) -> None:
+    _RUNTIME_TOOL_FACTORIES[_normalize_runtime_tool_name(name)] = factory
+
+
+def get_runtime_tool_factory(name: str) -> RuntimeToolFactory:
+    normalized = _normalize_runtime_tool_name(name)
+    try:
+        return _RUNTIME_TOOL_FACTORIES[normalized]
+    except KeyError as exc:
+        available = ", ".join(sorted(_RUNTIME_TOOL_FACTORIES)) or "none"
+        raise KeyError(f"Unknown runtime tool `{normalized}`. Available runtime tools: {available}.") from exc
+
+
+def list_runtime_tool_names() -> list[str]:
+    return sorted(_RUNTIME_TOOL_FACTORIES)
+
+
+__all__ = [
+    "get_runtime_tool_factory",
+    "list_runtime_tool_names",
+    "register_runtime_tool",
+]

package/src/deepscientist/runtime_tools/service.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable
+
+from ..shared import which
+from .builtins import register_builtin_runtime_tools
+from .models import RuntimeBinaryMatch, RuntimeTool, RuntimeToolStatus
+from .registry import get_runtime_tool_factory, list_runtime_tool_names
+
+
+class RuntimeToolService:
+    def __init__(self, home: Path) -> None:
+        self.home = home
+        register_builtin_runtime_tools(home=home)
+
+    def get_tool(self, name: str) -> RuntimeTool:
+        return get_runtime_tool_factory(name)(home=self.home)
+
+    def list_tool_names(self) -> list[str]:
+        return list_runtime_tool_names()
+
+    def status(self, name: str) -> RuntimeToolStatus:
+        return self.get_tool(name).status()
+
+    def install(self, name: str) -> RuntimeToolStatus:
+        return self.get_tool(name).install()
+
+    def all_statuses(self) -> dict[str, RuntimeToolStatus]:
+        return {name: self.status(name) for name in self.list_tool_names()}
+
+    def resolve_binary(
+        self,
+        binary: str,
+        *,
+        preferred_tools: Iterable[str] | None = None,
+        allow_system_fallback: bool = True,
+    ) -> RuntimeBinaryMatch:
+        normalized = str(binary or "").strip()
+        if not normalized:
+            return {"binary": None, "path": None, "source": None, "root": None, "bin_dir": None}
+
+        names = list(preferred_tools or self.list_tool_names())
+        for name in names:
+            match = self.get_tool(name).resolve_binary(normalized)
+            if isinstance(match, dict) and match.get("path"):
+                return match
+
+        system_path = which(normalized) if allow_system_fallback else None
+        return {
+            "binary": normalized,
+            "path": system_path,
+            "source": "path" if system_path else None,
+            "root": None,
+            "bin_dir": None,
+        }
+
+
+__all__ = ["RuntimeToolService"]

package/src/deepscientist/runtime_tools/tinytex.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ..tinytex import inspect_latex_runtime, install_tinytex, resolve_tinytex_binary
+
+
+class TinyTeXRuntimeTool:
+    tool_name = "tinytex"
+
+    def __init__(self, home: Path) -> None:
+        self.home = home
+
+    def status(self) -> dict[str, Any]:
+        return inspect_latex_runtime(self.home)
+
+    def install(self) -> dict[str, Any]:
+        return install_tinytex(self.home)
+
+    def resolve_binary(self, binary: str) -> dict[str, Any]:
+        return resolve_tinytex_binary(binary, self.home)
+
+
+__all__ = ["TinyTeXRuntimeTool"]

package/src/deepscientist/tinytex.py

@@ -0,0 +1,276 @@
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+from urllib.error import URLError
+from urllib.request import Request, urlopen
+
+from .shared import which
+
+_TINYTEX_DOC_URL = "https://yihui.org/tinytex/"
+_TINYTEX_CHINESE_DOC_URL = "https://yihui.org/tinytex/cn/"
+_TINYTEX_UNIX_INSTALLER_URL = "https://tinytex.yihui.org/install-bin-unix.sh"
+_TINYTEX_WINDOWS_INSTALLER_URL = "https://tinytex.yihui.org/install-bin-windows.bat"
+
+
+def _unique_paths(paths: list[Path]) -> list[Path]:
+    ordered: list[Path] = []
+    seen: set[str] = set()
+    for path in paths:
+        key = str(path.expanduser())
+        if key in seen:
+            continue
+        seen.add(key)
+        ordered.append(path.expanduser())
+    return ordered
+
+
+def _home_tools_root(home: Path | None) -> Path | None:
+    if home is None:
+        return None
+    return home / "runtime" / "tools"
+
+
+def tinytex_root_candidates(home: Path | None = None) -> list[Path]:
+    candidates: list[Path] = []
+    for env_name in ("DEEPSCIENTIST_TINYTEX_ROOT", "DS_TINYTEX_ROOT", "TINYTEX_DIR"):
+        raw = str(os.environ.get(env_name) or "").strip()
+        if raw:
+            candidates.append(Path(raw).expanduser())
+
+    tools_root = _home_tools_root(home)
+    if tools_root is not None:
+        candidates.append(tools_root / "TinyTeX")
+
+    if sys.platform.startswith("darwin"):
+        candidates.append(Path.home() / "Library" / "TinyTeX")
+    elif sys.platform.startswith("win"):
+        appdata_root = Path(os.environ.get("APPDATA") or (Path.home() / "AppData" / "Roaming"))
+        candidates.append(appdata_root / "TinyTeX")
+    else:
+        candidates.append(Path.home() / ".TinyTeX")
+
+    return _unique_paths(candidates)
+
+
+def _binary_names(binary: str) -> list[str]:
+    normalized = str(binary or "").strip()
+    if not normalized:
+        return []
+    if sys.platform.startswith("win"):
+        return [f"{normalized}.exe", f"{normalized}.bat", f"{normalized}.cmd", normalized]
+    return [normalized]
+
+
+def _tinytex_bin_dirs(root: Path) -> list[Path]:
+    bin_root = root / "bin"
+    if not bin_root.exists():
+        return []
+    child_dirs = sorted(path for path in bin_root.iterdir() if path.is_dir())
+    return child_dirs or ([bin_root] if bin_root.is_dir() else [])
+
+
+def resolve_tinytex_binary(binary: str, home: Path | None = None) -> dict[str, Any]:
+    normalized = str(binary or "").strip()
+    if not normalized:
+        return {"binary": None, "path": None, "source": None, "root": None, "bin_dir": None}
+    for root in tinytex_root_candidates(home):
+        for bin_dir in _tinytex_bin_dirs(root):
+            for name in _binary_names(normalized):
+                candidate = bin_dir / name
+                if candidate.exists():
+                    return {
+                        "binary": normalized,
+                        "path": str(candidate),
+                        "source": "tinytex",
+                        "root": str(root),
+                        "bin_dir": str(bin_dir),
+                    }
+    return {
+        "binary": normalized,
+        "path": None,
+        "source": None,
+        "root": None,
+        "bin_dir": None,
+    }
+
+
+def resolve_latex_binary(binary: str, home: Path | None = None) -> dict[str, Any]:
+    tinytex_match = resolve_tinytex_binary(binary, home)
+    if tinytex_match.get("path"):
+        return tinytex_match
+    system_path = which(binary)
+    return {
+        "binary": str(binary or "").strip() or None,
+        "path": system_path,
+        "source": "path" if system_path else None,
+        "root": None,
+        "bin_dir": None,
+    }
+
+
+def inspect_latex_runtime(home: Path | None = None) -> dict[str, Any]:
+    pdflatex = resolve_latex_binary("pdflatex", home)
+    xelatex = resolve_latex_binary("xelatex", home)
+    lualatex = resolve_latex_binary("lualatex", home)
+    bibtex = resolve_latex_binary("bibtex", home)
+    tinytex = resolve_tinytex_binary("pdflatex", home)
+
+    guidance: list[str] = []
+    warnings: list[str] = []
+    available = bool(pdflatex.get("path"))
+    bibtex_available = bool(bibtex.get("path"))
+
+    if not available:
+        warnings.append("Local PDF compilation is optional and currently unavailable because `pdflatex` is missing.")
+        guidance.append("Install a lightweight TinyTeX runtime with `ds latex install-runtime`.")
+        guidance.append(
+            "Or install a system LaTeX distribution that provides `pdflatex` and `bibtex`."
+        )
+    elif not bibtex_available:
+        warnings.append("`pdflatex` is available, but `bibtex` is missing. Bibliography builds may fail.")
+        guidance.append("Install TinyTeX with `ds latex install-runtime` or add `bibtex` to your system LaTeX distribution.")
+
+    summary = "A local `pdflatex` runtime is available for paper builds." if available else "Local `pdflatex` is not available."
+    if pdflatex.get("source") == "tinytex":
+        summary = "A TinyTeX-managed `pdflatex` runtime is available for paper builds."
+
+    return {
+        "ok": available,
+        "summary": summary,
+        "warnings": warnings,
+        "guidance": guidance,
+        "tinytex": {
+            "installed": bool(tinytex.get("path")),
+            "root": tinytex.get("root"),
+            "bin_dir": tinytex.get("bin_dir"),
+            "doc_url": _TINYTEX_DOC_URL,
+            "doc_url_zh": _TINYTEX_CHINESE_DOC_URL,
+            "installer_url": _TINYTEX_WINDOWS_INSTALLER_URL if sys.platform.startswith("win") else _TINYTEX_UNIX_INSTALLER_URL,
+        },
+        "binaries": {
+            "pdflatex": pdflatex,
+            "xelatex": xelatex,
+            "lualatex": lualatex,
+            "bibtex": bibtex,
+        },
+    }
+
+
+def _download_installer(url: str) -> tuple[bool, str]:
+    request = Request(url, headers={"User-Agent": "DeepScientist TinyTeX bootstrap"})
+    try:
+        with urlopen(request, timeout=30) as response:  # noqa: S310
+            payload = response.read()
+    except (OSError, TimeoutError, URLError) as exc:
+        return False, str(exc)
+    suffix = ".bat" if url.endswith(".bat") else ".sh"
+    with tempfile.NamedTemporaryFile(delete=False, suffix=suffix) as handle:
+        handle.write(payload)
+        return True, handle.name
+
+
+def install_tinytex(home: Path | None = None) -> dict[str, Any]:
+    current = inspect_latex_runtime(home)
+    if current.get("tinytex", {}).get("installed"):
+        return {
+            "ok": True,
+            "changed": False,
+            "summary": "TinyTeX-managed pdflatex is already installed.",
+            "runtime": current,
+        }
+
+    if sys.platform.startswith("win"):
+        ok, installer_path_or_error = _download_installer(_TINYTEX_WINDOWS_INSTALLER_URL)
+        if not ok:
+            return {
+                "ok": False,
+                "changed": False,
+                "summary": "Failed to download the TinyTeX Windows installer.",
+                "errors": [installer_path_or_error],
+                "guidance": [f"Open {_TINYTEX_DOC_URL} for the official manual install instructions."],
+            }
+        command = ["cmd", "/c", installer_path_or_error]
+    else:
+        if not which("sh"):
+            return {
+                "ok": False,
+                "changed": False,
+                "summary": "TinyTeX installation requires `/bin/sh` or a compatible shell.",
+                "errors": ["`sh` is not available on PATH."],
+                "guidance": [f"Install TinyTeX manually from {_TINYTEX_DOC_URL}."],
+            }
+        if not which("perl"):
+            return {
+                "ok": False,
+                "changed": False,
+                "summary": "TinyTeX installation requires Perl on Linux and macOS.",
+                "errors": ["`perl` is not available on PATH."],
+                "guidance": [
+                    "Install Perl first, then rerun `ds latex install-runtime`.",
+                    f"Official docs: {_TINYTEX_DOC_URL}",
+                ],
+            }
+        ok, installer_path_or_error = _download_installer(_TINYTEX_UNIX_INSTALLER_URL)
+        if not ok:
+            return {
+                "ok": False,
+                "changed": False,
+                "summary": "Failed to download the TinyTeX installer.",
+                "errors": [installer_path_or_error],
+                "guidance": [f"Open {_TINYTEX_DOC_URL} for the official manual install instructions."],
+            }
+        command = ["sh", installer_path_or_error]
+
+    installer_path = Path(installer_path_or_error)
+    try:
+        result = subprocess.run(command, capture_output=True, text=True, check=False)
+    finally:
+        installer_path.unlink(missing_ok=True)
+    refreshed = inspect_latex_runtime(home)
+
+    stdout_tail = "\n".join(str(result.stdout or "").splitlines()[-40:])
+    stderr_tail = "\n".join(str(result.stderr or "").splitlines()[-40:])
+    if result.returncode != 0:
+        return {
+            "ok": False,
+            "changed": False,
+            "summary": "TinyTeX installer exited with a non-zero status.",
+            "errors": [stderr_tail or stdout_tail or f"Installer exited with status {result.returncode}."],
+            "guidance": [
+                "Retry `ds latex install-runtime` after checking network connectivity.",
+                f"Official docs: {_TINYTEX_DOC_URL}",
+            ],
+            "exit_code": result.returncode,
+            "stdout_tail": stdout_tail,
+            "stderr_tail": stderr_tail,
+            "runtime": refreshed,
+        }
+
+    if not refreshed.get("tinytex", {}).get("installed"):
+        return {
+            "ok": False,
+            "changed": False,
+            "summary": "TinyTeX installer finished, but DeepScientist could not find the managed pdflatex runtime afterward.",
+            "errors": ["Installation did not expose a discoverable TinyTeX `pdflatex` binary."],
+            "guidance": [
+                "Open the TinyTeX documentation and verify the install location.",
+                f"Official docs: {_TINYTEX_DOC_URL}",
+            ],
+            "stdout_tail": stdout_tail,
+            "stderr_tail": stderr_tail,
+            "runtime": refreshed,
+        }
+
+    return {
+        "ok": True,
+        "changed": True,
+        "summary": "TinyTeX-managed pdflatex is ready.",
+        "stdout_tail": stdout_tail,
+        "stderr_tail": stderr_tail,
+        "runtime": refreshed,
+    }

package/src/prompts/connectors/lingzhu.md

@@ -0,0 +1,12 @@
+# Lingzhu Connector Contract
+
+- connector_contract_id: lingzhu
+- connector_contract_scope: loaded only when Lingzhu is the active or bound external connector for this quest
+- connector_contract_goal: keep `artifact.interact(...)` as the main durable conversation spine while optionally requesting device-side actions through `surface_actions`
+- lingzhu_runtime_ack_rule: the Lingzhu bridge itself emits the immediate transport-level receipt acknowledgement before the model turn starts
+- lingzhu_no_duplicate_ack_rule: do not waste your first model response or first `artifact.interact(...)` call on a redundant receipt-only acknowledgement such as "received" or "I am processing" when the bridge already sent that
+- lingzhu_surface_actions_rule: when a device-side step materially helps the current task, request it through `artifact.interact(surface_actions=[...])` rather than inventing ad hoc tool syntax
+- lingzhu_surface_actions_supported: `take_photo`, `send_notification`, `send_toast`, `speak_tts`, `open_custom_view`
+- lingzhu_progress_rule: for long-running work, your first substantive reply should contain either the direct answer or the first concrete checkpoint, not a duplicate transport acknowledgement
+- lingzhu_safety_rule: request only actions that are clearly justified by the current quest and understandable to the human user
+- lingzhu_text_rule: even when requesting `surface_actions`, always include a clear text explanation of what is happening and why