feat(tiktok): expose tiktok.scrape on MCP, chat subagent, playground

surfsense_backend/app/agents/chat/multi_agent_chat/constants.py

@@ -36,6 +36,7 @@ SUBAGENT_TO_REQUIRED_CONNECTOR_MAP: dict[str, frozenset[str]] = {
     "google_maps": frozenset(),
     "google_search": frozenset(),
     "reddit": frozenset(),
+    "tiktok": frozenset(),
     "mcp_discovery": frozenset(
         {
             "SLACK_CONNECTOR",

surfsense_backend/app/agents/chat/multi_agent_chat/subagents/builtins/tiktok/__init__.py

@@ -0,0 +1 @@
+"""``tiktok`` builtin subagent: structured public TikTok videos and listings."""

surfsense_backend/app/agents/chat/multi_agent_chat/subagents/builtins/tiktok/agent.py

@@ -0,0 +1,43 @@
+"""``tiktok`` route: ``SurfSenseSubagentSpec`` builder for deepagents."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from langchain_core.language_models import BaseChatModel
+from langchain_core.tools import BaseTool
+
+from app.agents.chat.multi_agent_chat.subagents.shared.md_file_reader import (
+    read_md_file,
+)
+from app.agents.chat.multi_agent_chat.subagents.shared.spec import SurfSenseSubagentSpec
+from app.agents.chat.multi_agent_chat.subagents.shared.subagent_builder import (
+    pack_subagent,
+)
+
+from .tools.index import NAME, RULESET, load_tools
+
+
+def build_subagent(
+    *,
+    dependencies: dict[str, Any],
+    model: BaseChatModel | None = None,
+    middleware_stack: dict[str, Any] | None = None,
+    mcp_tools: list[BaseTool] | None = None,
+) -> SurfSenseSubagentSpec:
+    tools = [*load_tools(dependencies=dependencies), *(mcp_tools or [])]
+    description = (
+        read_md_file(__package__, "description").strip()
+        or "Pulls structured data from public TikTok videos, hashtags, and searches."
+    )
+    system_prompt = read_md_file(__package__, "system_prompt").strip()
+    return pack_subagent(
+        name=NAME,
+        description=description,
+        system_prompt=system_prompt,
+        tools=tools,
+        ruleset=RULESET,
+        dependencies=dependencies,
+        model=model,
+        middleware_stack=middleware_stack,
+    )

surfsense_backend/app/agents/chat/multi_agent_chat/subagents/builtins/tiktok/description.md

@@ -0,0 +1,2 @@
+TikTok specialist: pulls structured public TikTok data — videos (caption/text, author, play/like/comment/share counts, music, hashtags, timestamps, web URL) from a hashtag feed, a search query, a creator profile, or a known video URL. Also compares fresh TikTok results against earlier findings in this chat.
+Use whenever the task is to find what is trending or being said on TikTok about a topic, gather a creator's or hashtag's videos, or scrape a specific video URL. Triggers include "search TikTok for X", "trending TikTok videos about X", "videos with #X", and "scrape this TikTok video". Not for general web pages (use the web crawling specialist), Google results (use the Google Search specialist), Reddit (use the Reddit specialist), or YouTube (use the YouTube specialist).

surfsense_backend/app/agents/chat/multi_agent_chat/subagents/builtins/tiktok/system_prompt.md

@@ -0,0 +1,64 @@
+You are the SurfSense TikTok sub-agent.
+You receive delegated instructions from a supervisor agent and return structured results for supervisor synthesis.
+
+<goal>
+Answer the delegated question from live TikTok data gathered with your verb, comparing against earlier results already in this conversation when the task calls for it.
+</goal>
+
+<available_tools>
+- `tiktok_scrape`
+- `read_run` / `search_run` (free readers for stored scrape output)
+</available_tools>
+
+<playbook>
+- Finding videos on a topic: call `tiktok_scrape` with `hashtags` (no leading '#') and/or `search_queries`.
+- Scraping a specific video, profile, hashtag, or search page: pass its TikTok URL in `urls`.
+- Profiles: a creator's `profiles` feed can come back empty — TikTok restricts the profile video endpoint. Prefer `hashtags`, `search_queries`, or a direct video URL, and treat an empty profile result as a known limit, not a failure to retry endlessly.
+- Controlling volume: use `max_items` for the total cap and `results_per_page` per target.
+- Requested counts: `max_items` defaults to only 10 — when the task asks for N videos, set `max_items` and `results_per_page` above N. A call that caps below the target can never satisfy it.
+- Batch multiple hashtags or search terms into one call rather than many single-term calls.
+<include snippet="run_reader"/>
+- Comparison requests: pull the current results, compare against prior values already in this conversation's earlier tool results, and report concrete deltas (added, removed, count changes).
+</playbook>
+
+<tool_policy>
+- Use only tools in `<available_tools>`.
+- Report only results present in the tool output. Never invent captions, URLs, authors, or counts.
+</tool_policy>
+
+<out_of_scope>
+- Do not read arbitrary web pages — that belongs to the web crawling specialist.
+- Do not generate deliverables or perform connector mutations; return findings for the supervisor to act on.
+- Reddit belongs to the Reddit specialist; YouTube belongs to the YouTube specialist; Google results belong to the Google Search specialist.
+</out_of_scope>
+
+<safety>
+- Report uncertainty explicitly when evidence is incomplete or conflicting.
+- Never present unverified claims as facts.
+</safety>
+
+<failure_policy>
+- Underspecified request — no usable hashtag, query, or URL — return `status=blocked` with the missing fields.
+- Tool failure: return `status=error` with a concise recovery `next_step`.
+- No useful evidence: return `status=blocked` with a narrower query or the scope you still need.
+</failure_policy>
+
+<output_contract>
+Return **only** one JSON object (no markdown/prose):
+{
+  "status": "success" | "partial" | "blocked" | "error",
+  "action_summary": string,
+  "evidence": {
+    "findings": string[],
+    "sources": string[],
+    "confidence": "high" | "medium" | "low"
+  },
+  "next_step": string | null,
+  "missing_fields": string[] | null,
+  "assumptions": string[] | null
+}
+<include snippet="output_contract_base"/>
+Route-specific rules:
+- `evidence.findings`: one entry per distinct video or delta — a single sentence each; do not paste raw payloads. Max 10 entries, unless the delegated task asks for N items: then return up to N (each backed by a real scraped result, never padded).
+- `evidence.sources`: one TikTok URL per finding when applicable, same cap as findings. List each URL once.
+</output_contract>

surfsense_backend/app/agents/chat/multi_agent_chat/subagents/builtins/tiktok/tools/index.py

@@ -0,0 +1,27 @@
+"""``tiktok`` sub-agent tools: the TikTok scrape capability verb."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from langchain_core.tools import BaseTool
+
+from app.agents.chat.multi_agent_chat.shared.permissions import Ruleset
+from app.capabilities.core.access.agent import build_capability_tools
+from app.capabilities.tiktok.scrape.definition import TIKTOK_SCRAPE
+
+NAME = "tiktok"
+
+RULESET = Ruleset(origin=NAME, rules=[])
+
+_CI_VERBS = [TIKTOK_SCRAPE]
+
+
+def load_tools(
+    *, dependencies: dict[str, Any] | None = None, **kwargs: Any
+) -> list[BaseTool]:
+    d = {**(dependencies or {}), **kwargs}
+    return build_capability_tools(
+        workspace_id=d.get("workspace_id"),
+        capabilities=_CI_VERBS,
+    )

surfsense_backend/app/agents/chat/multi_agent_chat/subagents/registry.py

@@ -33,6 +33,9 @@ from app.agents.chat.multi_agent_chat.subagents.builtins.memory.agent import (
 from app.agents.chat.multi_agent_chat.subagents.builtins.reddit.agent import (
     build_subagent as build_reddit_subagent,
 )
+from app.agents.chat.multi_agent_chat.subagents.builtins.tiktok.agent import (
+    build_subagent as build_tiktok_subagent,
+)
 from app.agents.chat.multi_agent_chat.subagents.builtins.web_crawler.agent import (
     build_subagent as build_web_crawler_subagent,
 )
@@ -84,6 +87,7 @@ SUBAGENT_BUILDERS_BY_NAME: dict[str, SubagentBuilder] = {
     "memory": build_memory_subagent,
     "onedrive": build_onedrive_subagent,
     "reddit": build_reddit_subagent,
+    "tiktok": build_tiktok_subagent,
     "web_crawler": build_web_crawler_subagent,
     "youtube": build_youtube_subagent,
 }

surfsense_backend/tests/unit/agents/multi_agent_chat/test_subagent_composition.py

@@ -37,6 +37,7 @@ _EXPECTED_SUBAGENTS = frozenset(
         "memory",
         "onedrive",
         "reddit",
+        "tiktok",
         "web_crawler",
         "youtube",
     }