agent-wire-cli 0.2.1__py3-none-any.whl

agent_wire/research/library.py

@@ -0,0 +1,74 @@
+"""Your research library: offline search over saved briefs, plus a local site and Atom feed."""
+
+import html
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+from agent_wire.research.brief import page
+from agent_wire.research.store import Store
+
+ATOM = "http://www.w3.org/2005/Atom"
+EPOCH = "1970-01-01T00:00:00+00:00"
+
+
+class Library:
+    def __init__(self, store: Store, home: Path):
+        self.store = store
+        self.dir = Path(home) / "library"
+
+    def related(self, topic: str, limit: int = 3, exclude: int | None = None) -> list[dict]:
+        return self.store.search(topic, limit=limit, exclude=exclude)
+
+    def search_markdown(self, query: str, limit: int = 10) -> str:
+        hits = self.store.search(query, limit=limit)
+        if not hits:
+            return f"no saved briefs match {query!r} (save runs with store=True / --store)"
+        return "\n".join(f"{i}. run #{h['id']} · {h['created_at'][:10]} · {h['topic']} ({h['mode']}, "
+                         f"{h['days']}d) · {h['headline']}" for i, h in enumerate(hits, 1))  # fmt: skip
+
+    def build(self, limit: int = 200) -> Path:
+        """Write index.html, feed.xml and one page per saved run under WIRE_HOME/library."""
+        runs_dir = self.dir / "runs"
+        runs_dir.mkdir(parents=True, exist_ok=True)
+        runs = self.store.runs(limit=limit)
+        for r in runs:
+            full = self.store.run(r["id"])
+            (runs_dir / f"{r['id']}.html").write_text(
+                page(full["markdown"], f"#{r['id']} · {r['topic']}"), encoding="utf-8"
+            )
+        rows = "".join(
+            f"<tr><td>{r['created_at'][:10]}</td><td><a href='runs/{r['id']}.html'>"
+            f"{html.escape(r['topic'])}</a></td><td>{r['mode']}</td><td>{r['days']}d</td>"
+            f"<td>{html.escape(r['headline'])}</td></tr>"
+            for r in runs
+        )
+        table = ("<p><a href='feed.xml'>Atom feed</a></p><table><tr><th>date</th><th>topic</th>"
+                 f"<th>mode</th><th>window</th><th>headline</th></tr>{rows}</table>")  # fmt: skip
+        index = page("# Research library", "agent-wire library").replace(
+            "<h1>Research library</h1>", "<h1>Research library</h1>" + table
+        )
+        (self.dir / "index.html").write_text(index, encoding="utf-8")
+        (self.dir / "feed.xml").write_bytes(self.atom(runs))
+        return self.dir
+
+    def atom(self, runs: list[dict]) -> bytes:
+        ET.register_namespace("", ATOM)
+
+        def sub(parent, tag, text=None, **attrs):
+            el = ET.SubElement(parent, f"{{{ATOM}}}{tag}", **attrs)
+            el.text = text
+            return el
+
+        feed = ET.Element(f"{{{ATOM}}}feed")
+        sub(feed, "title", "agent-wire research library")
+        sub(feed, "id", "urn:agent-wire:library")
+        sub(feed, "updated", runs[0]["created_at"] if runs else EPOCH)
+        sub(sub(feed, "author"), "name", "agent-wire")
+        for r in runs:
+            e = sub(feed, "entry")
+            sub(e, "title", f"{r['topic']} · last {r['days']} days")
+            sub(e, "id", f"urn:agent-wire:run:{r['id']}")
+            sub(e, "updated", r["created_at"])
+            sub(e, "link", href=(self.dir / "runs" / f"{r['id']}.html").as_uri())
+            sub(e, "summary", r["headline"])
+        return ET.tostring(feed, encoding="utf-8", xml_declaration=True)

agent_wire/research/planner.py

@@ -0,0 +1,232 @@
+"""Pre-research: decide mode, window, sources and per-source queries before any network call."""
+
+import re
+from dataclasses import asdict, dataclass, field
+from datetime import UTC, datetime, timedelta
+
+# Key-free sources researched by default; others join when the topic calls for them.
+CORE = (
+    "reddit",
+    "hackernews",
+    "youtube",
+    "github",
+    "news",
+    "bluesky",
+    "mastodon",
+    "polymarket",
+    "web",
+)
+TECH = ("devto", "stackoverflow")
+ALL_SOURCES = (*CORE, *TECH, "arxiv", "stocktwits", "x", "lobsters")
+ALIASES = {"hn": "hackernews", "gh": "github", "yt": "youtube", "so": "stackoverflow",
+           "bsky": "bluesky", "fediverse": "bluesky", "twitter": "x", "techmeme": "news",
+           "papers": "arxiv", "dev.to": "devto", "markets": "polymarket"}  # fmt: skip
+DEPTHS = {"quick": {"per_source": 5, "deep_reads": 0, "queries": 1},
+          "default": {"per_source": 8, "deep_reads": 3, "queries": 1},
+          "deep": {"per_source": 15, "deep_reads": 6, "queries": 2}}  # fmt: skip
+
+_TECH_WORDS = frozenset(
+    ["ai", "llm", "gpt", "model", "api", "sdk", "python", "rust", "go", "golang", "typescript", "javascript", "js", "react", "vue", "svelte", "node", "deno", "bun", "docker", "kubernetes", "k8s", "linux", "git", "github", "cli", "framework", "library", "database", "sql", "postgres", "redis", "cloud", "aws", "gcp", "azure", "devops", "ml", "agent", "agents", "mcp", "claude", "openai", "anthropic", "gemini", "llama", "compiler", "wasm", "webassembly", "kernel", "gpu", "cuda", "nvidia", "programming", "code", "coding", "developer", "open-source", "opensource", "vscode", "cursor", "neovim", "vim", "terminal", "uv", "pip", "npm", "cargo", "crate", "package"]
+)  # fmt: skip
+_ACADEMIC = frozenset(
+    [
+        "paper",
+        "papers",
+        "arxiv",
+        "research",
+        "study",
+        "benchmark",
+        "dataset",
+        "theorem",
+        "diffusion",
+        "transformer",
+    ]
+)
+_STOP = frozenset(
+    [
+        "the",
+        "a",
+        "an",
+        "and",
+        "or",
+        "of",
+        "for",
+        "to",
+        "in",
+        "on",
+        "with",
+        "what",
+        "is",
+        "are",
+        "how",
+        "why",
+        "best",
+        "new",
+        "about",
+        "latest",
+        "news",
+        "last",
+        "days",
+        "week",
+        "month",
+        "people",
+        "think",
+    ]
+)
+_VS = re.compile(r"\s+(?:vs\.?|versus)\s+", re.IGNORECASE)
+_TICKER = re.compile(r"\$([A-Za-z]{1,6}(?:\.[A-Za-z]{1,2})?)\b")
+_DISCOVER = re.compile(
+    r"^\s*(?:what'?s\s+)?(?:trending|hot|discover|what is happening)\b", re.IGNORECASE
+)
+
+
+@dataclass
+class Plan:
+    topic: str
+    mode: str  # topic | compare | discover | person
+    days: int
+    since: datetime
+    until: datetime
+    depth: str
+    sources: list[str]
+    queries: dict[str, list[str]] = field(default_factory=dict)
+    subjects: list[str] = field(default_factory=list)
+    tickers: list[str] = field(default_factory=list)
+    github_user: str | None = None
+    notes: list[str] = field(default_factory=list)
+
+    @property
+    def per_source(self) -> int:
+        return DEPTHS[self.depth]["per_source"]
+
+    @property
+    def deep_reads(self) -> int:
+        return DEPTHS[self.depth]["deep_reads"]
+
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        d["since"], d["until"] = self.since.isoformat(), self.until.isoformat()
+        return d
+
+    def describe(self) -> str:
+        """--preflight: what would run, without running it."""
+        window = f"{self.since.date()} -> {self.until.date()} ({self.days} days)"
+        lines = [f"mode: {self.mode} · depth: {self.depth} · window: {window}"]
+        if self.subjects:
+            lines.append("subjects: " + " | ".join(self.subjects))
+        if self.github_user:
+            lines.append(f"github person: {self.github_user}")
+        lines.append("reads (anonymous unless you saved a session with `wire auth login`):")
+        lines += [f"- {s}: " + " · ".join(repr(q) for q in self.queries.get(s) or [self.topic])
+                  for s in self.sources]  # fmt: skip
+        lines.append("writes: none unless store=True (then WIRE_HOME/research.db)")
+        lines += [f"note: {n}" for n in self.notes]
+        return "\n".join(lines)
+
+
+def terms(text: str) -> list[str]:
+    words = re.findall(r"[a-z0-9][a-z0-9+#.\-]*", text.lower())
+    return [w.strip(".-") for w in words if w not in _STOP and len(w) > 1]
+
+
+def is_tech(topic: str) -> bool:
+    return any(t in _TECH_WORDS for t in terms(topic))
+
+
+def _expand(topic: str, n: int) -> list[str]:
+    """Query expansion: the topic, then (deep) its key terms without filler words."""
+    out = [topic.strip()]
+    core = " ".join(terms(topic))
+    if n > 1 and core and core != topic.strip().lower():
+        out.append(core)
+    return out[:n]
+
+
+def normalize_sources(sources) -> list[str] | None:
+    if not sources:
+        return None
+    if isinstance(sources, str):
+        sources = [s for s in re.split(r"[,\s]+", sources) if s]
+    out = []
+    for s in sources:
+        key = ALIASES.get(s.strip().lower(), s.strip().lower())
+        if key == "all":
+            return list(ALL_SOURCES)
+        if key not in ALL_SOURCES:
+            raise ValueError(
+                f"unknown research source {s!r}; choose from: {', '.join(ALL_SOURCES)}"
+            )
+        out.append(key)
+    return list(dict.fromkeys(out))
+
+
+def make_plan(topic: str = "", *, days: int = 30, sources=None, mode: str = "auto",
+              depth: str = "default", as_of=None, github_user: str | None = None,
+              has_x_session: bool = False) -> Plan:  # fmt: skip
+    if depth not in DEPTHS:
+        raise ValueError(f"depth must be one of {', '.join(DEPTHS)}")
+    days = max(1, min(int(days), 365))
+    until = _as_of(as_of)
+    since = until - timedelta(days=days)
+    topic = (topic or "").strip()
+    chosen = normalize_sources(sources)
+
+    if mode == "auto":
+        if github_user and not topic:
+            mode = "person"
+        elif not topic or _DISCOVER.match(topic):
+            mode = "discover"
+        elif len(_VS.split(topic)) > 1:
+            mode = "compare"
+        else:
+            mode = "topic"
+    if mode not in ("topic", "compare", "discover", "person"):
+        raise ValueError("mode must be auto, topic, compare, discover or person")
+
+    plan = Plan(topic=topic, mode=mode, days=days, since=since, until=until, depth=depth,
+                sources=[], github_user=github_user.lstrip("@") if github_user else None)  # fmt: skip
+    plan.tickers = [t.upper() for t in _TICKER.findall(topic)]
+    if mode == "compare":
+        plan.subjects = [s.strip() for s in _VS.split(topic) if s.strip()][:4]
+
+    if chosen:
+        plan.sources = chosen
+    elif mode == "discover":
+        plan.sources = ["hackernews", "github", "news", "polymarket", "mastodon", "lobsters"]
+    elif mode == "person":
+        plan.sources = ["github"]
+    else:
+        plan.sources = list(CORE)
+        if is_tech(topic):
+            plan.sources += list(TECH)
+        if set(terms(topic)) & _ACADEMIC:
+            plan.sources.append("arxiv")
+        if plan.tickers:
+            plan.sources.append("stocktwits")
+    if "x" in plan.sources and not has_x_session:
+        plan.sources.remove("x")
+        plan.notes.append("x skipped: no saved session (`wire auth login x.com` adds it)")
+    elif has_x_session and "x" not in plan.sources and not chosen and mode in ("topic", "compare"):
+        plan.sources.append("x")
+
+    n = DEPTHS[depth]["queries"]
+    subjects = plan.subjects or ([topic] if topic else [])
+    for s in plan.sources:
+        if s == "stocktwits":
+            plan.queries[s] = [f"${t}" for t in plan.tickers] or subjects
+        else:
+            plan.queries[s] = [q for subj in subjects for q in _expand(subj, n)]
+    if plan.github_user and "github" not in plan.sources:
+        plan.sources.append("github")
+    return plan
+
+
+def _as_of(value) -> datetime:
+    if value in (None, ""):
+        return datetime.now(UTC)
+    if isinstance(value, datetime):
+        return value if value.tzinfo else value.replace(tzinfo=UTC)
+    d = datetime.fromisoformat(str(value))
+    if len(str(value)) <= 10:  # a bare date means the end of that day
+        d += timedelta(days=1)
+    return d if d.tzinfo else d.replace(tzinfo=UTC)

agent_wire/research/scoring.py

@@ -0,0 +1,89 @@
+"""Score research items by relevance x (engagement, freshness), with a relevance floor."""
+
+import math
+from dataclasses import dataclass
+from datetime import datetime
+
+from agent_wire.models import WireSearchHit
+from agent_wire.research.planner import terms
+
+# How much one unit of each public signal is worth, roughly "one upvote".
+WEIGHTS = {"score": 1.0, "likes": 1.0, "comments": 2.0, "reposts": 2.0, "reactions": 1.0,
+           "stars": 0.1, "forks": 0.2, "views": 0.003, "volume24h": 0.001, "volume": 0.0001}  # fmt: skip
+RELEVANCE_FLOOR = 0.34  # below this an item is off-topic, however viral
+UNDATED_FRESHNESS = 0.35
+MIN_SOURCE_TOP = math.log1p(50)
+
+
+@dataclass
+class Item:
+    hit: WireSearchHit
+    query: str = ""
+    origin: str = ""  # the planned source that produced it ("news" for a Techmeme item)
+    relevance: float = 0.0
+    freshness: float = 0.0
+    engagement: float = 0.0
+    score: float = 0.0
+
+    @property
+    def source(self) -> str:
+        return self.hit.source
+
+
+def raw_engagement(hit: WireSearchHit) -> float:
+    return sum(WEIGHTS.get(k, 0.0) * max(0, v) for k, v in hit.engagement.items())
+
+
+def relevance(hit: WireSearchHit, topic: str) -> float:
+    """Share of topic terms present (title counts fully, snippet partly) + exact-phrase bonus."""
+    want = list(dict.fromkeys(terms(topic)))
+    if not want:
+        return 1.0
+    title, body = hit.title.lower(), f"{hit.snippet} {hit.author or ''}".lower()
+    got = sum(1.0 if t in title else 0.6 if t in body else 0.0 for t in want) / len(want)
+    if topic.lower().strip() in title:
+        got += 0.25
+    return min(got, 1.25)
+
+
+def freshness(ts: datetime | None, until: datetime, days: int) -> float:
+    if ts is None:
+        return UNDATED_FRESHNESS
+    age = max(0.0, (until - ts).total_seconds() / 86400)
+    return 0.5 ** (age / max(days / 2, 0.5))  # half-life: half the window
+
+
+def in_window(hit: WireSearchHit, since: datetime, until: datetime) -> bool:
+    return hit.timestamp is None or since <= hit.timestamp <= until
+
+
+def floor_for(query: str) -> float:
+    """Two-word topics need both words ('rust programming' is not any programming post)."""
+    n = len(set(terms(query)))
+    return 0.55 if n == 2 else 0.4 if n >= 3 else RELEVANCE_FLOOR
+
+
+def score_items(items: list[Item], topic: str, since: datetime, until: datetime, days: int,
+                floor: float | None = None) -> list[Item]:  # fmt: skip
+    """Drop out-of-window and off-topic items; fill the score fields; best first.
+
+    `floor=None` picks a relevance floor from each item's query; pass a number to override.
+    """
+    kept = [i for i in items if in_window(i.hit, since, until)]
+    for i in kept:
+        i.relevance = relevance(i.hit, i.query or topic)
+    kept = [i for i in kept
+            if i.relevance >= (floor if floor is not None else floor_for(i.query or topic))]  # fmt: skip
+    logs = {id(i): math.log1p(raw_engagement(i.hit)) for i in kept}
+    top_all = max(logs.values(), default=0.0) or 1.0
+    top_src: dict[str, float] = {}
+    for i in kept:
+        top_src[i.source] = max(top_src.get(i.source, 0.0), logs[id(i)])
+    for i in kept:
+        # per-source normalisation keeps a 50-point HN story from losing to a 5k-view video
+        # ... but a source whose best item has ~no engagement must not get a free 1.0
+        src_norm = max(top_src[i.source], MIN_SOURCE_TOP)
+        i.engagement = 0.6 * logs[id(i)] / src_norm + 0.4 * logs[id(i)] / top_all
+        i.freshness = freshness(i.hit.timestamp, until, days)
+        i.score = round(min(i.relevance, 1.0) * (0.45 * i.engagement + 0.35 * i.freshness + 0.2), 4)
+    return sorted(kept, key=lambda i: -i.score)

agent_wire/research/store.py

@@ -0,0 +1,149 @@
+"""Research persistence (WIRE_HOME/research.db): saved runs, their items, and watched topics."""
+
+import json
+import sqlite3
+from datetime import UTC, datetime
+from pathlib import Path
+
+from agent_wire.channels.tier1_global.search import url_key
+from agent_wire.compression.bm25_slicer import bm25_scores
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS runs (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    topic TEXT NOT NULL,
+    mode TEXT NOT NULL,
+    days INTEGER NOT NULL,
+    created_at TEXT NOT NULL,
+    headline TEXT NOT NULL DEFAULT '',
+    markdown TEXT NOT NULL,
+    json TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS items (
+    run_id INTEGER NOT NULL REFERENCES runs(id) ON DELETE CASCADE,
+    url_key TEXT NOT NULL,
+    url TEXT NOT NULL,
+    title TEXT NOT NULL,
+    source TEXT NOT NULL,
+    ts TEXT,
+    score REAL NOT NULL DEFAULT 0
+);
+CREATE INDEX IF NOT EXISTS items_run ON items(run_id);
+CREATE INDEX IF NOT EXISTS runs_topic ON runs(topic);
+CREATE TABLE IF NOT EXISTS watches (
+    topic TEXT PRIMARY KEY,
+    days INTEGER NOT NULL DEFAULT 7,
+    sources TEXT,
+    webhook TEXT,
+    created_at TEXT NOT NULL,
+    last_run_id INTEGER
+);
+"""
+
+
+def norm_topic(topic: str) -> str:
+    return " ".join(topic.lower().split())
+
+
+class Store:
+    def __init__(self, path: Path):
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.db = sqlite3.connect(self.path)
+        self.db.row_factory = sqlite3.Row
+        self.db.execute("PRAGMA foreign_keys = ON")
+        self.db.executescript(SCHEMA)
+
+    def close(self) -> None:
+        self.db.close()
+
+    # ---- runs --------------------------------------------------------------------------------
+    def save(self, result, markdown: str, data: dict) -> int:
+        p = result.plan
+        topic = norm_topic(p.topic) or ("discover" if p.mode == "discover" else p.github_user or "")
+        with self.db:
+            cur = self.db.execute(
+                "INSERT INTO runs (topic, mode, days, created_at, headline, markdown, json)"
+                " VALUES (?, ?, ?, ?, ?, ?, ?)",
+                (topic, p.mode, p.days, result.created_at.isoformat(), data.get("headline", ""),
+                 markdown, json.dumps(data, ensure_ascii=False)),
+            )  # fmt: skip
+            run_id = cur.lastrowid
+            self.db.executemany(
+                "INSERT INTO items (run_id, url_key, url, title, source, ts, score)"
+                " VALUES (?, ?, ?, ?, ?, ?, ?)",
+                [(run_id, url_key(i.hit.url), i.hit.url, i.hit.title, i.source,
+                  i.hit.timestamp.isoformat() if i.hit.timestamp else None, i.score)
+                 for i in result.items],
+            )  # fmt: skip
+        return run_id
+
+    def runs(self, limit: int = 20, topic: str | None = None) -> list[dict]:
+        q, args = "SELECT id, topic, mode, days, created_at, headline FROM runs", []
+        if topic:
+            q, args = q + " WHERE topic = ?", [norm_topic(topic)]
+        rows = self.db.execute(q + " ORDER BY id DESC LIMIT ?", [*args, limit]).fetchall()
+        return [dict(r) for r in rows]
+
+    def run(self, run_id: int) -> dict | None:
+        row = self.db.execute("SELECT * FROM runs WHERE id = ?", (run_id,)).fetchone()
+        return dict(row) if row else None
+
+    def items(self, run_id: int) -> list[dict]:
+        rows = self.db.execute(
+            "SELECT * FROM items WHERE run_id = ? ORDER BY score DESC", (run_id,)
+        )
+        return [dict(r) for r in rows]
+
+    def previous(self, topic: str, before_id: int) -> int | None:
+        row = self.db.execute(
+            "SELECT id FROM runs WHERE topic = ? AND id < ? ORDER BY id DESC LIMIT 1",
+            (norm_topic(topic), before_id),
+        ).fetchone()
+        return row["id"] if row else None
+
+    def new_items(self, run_id: int, previous_id: int | None) -> list[dict]:
+        """Items in this run whose URL never appeared in the previous run of the same topic."""
+        if previous_id is None:
+            return self.items(run_id)
+        rows = self.db.execute("SELECT url_key FROM items WHERE run_id = ?", (previous_id,))
+        seen = {r["url_key"] for r in rows}
+        return [i for i in self.items(run_id) if i["url_key"] not in seen]
+
+    def search(self, query: str, limit: int = 10, exclude: int | None = None) -> list[dict]:
+        """Offline, deterministic BM25 over every saved brief."""
+        rows = [dict(r) for r in self.db.execute(
+            "SELECT id, topic, mode, days, created_at, headline, markdown FROM runs"
+            " ORDER BY id DESC LIMIT 2000")]  # fmt: skip
+        rows = [r for r in rows if r["id"] != exclude]
+        if not rows:
+            return []
+        texts = [f"{r['topic']} {r['topic']} {r['headline']} {r['markdown']}" for r in rows]
+        scores = bm25_scores(texts, query)
+        ranked = sorted(zip(scores, rows, strict=True), key=lambda sr: (-sr[0], -sr[1]["id"]))
+        return [{k: v for k, v in r.items() if k != "markdown"} | {"score": round(s, 3)}
+                for s, r in ranked[:limit] if s > 0]  # fmt: skip
+
+    # ---- watches -----------------------------------------------------------------------------
+    def add_watch(self, topic: str, days: int = 7, sources: str | None = None,
+                  webhook: str | None = None) -> None:  # fmt: skip
+        with self.db:
+            self.db.execute(
+                "INSERT INTO watches (topic, days, sources, webhook, created_at) VALUES (?, ?, ?, ?, ?)"
+                " ON CONFLICT(topic) DO UPDATE SET days = excluded.days,"
+                " sources = excluded.sources, webhook = excluded.webhook",
+                (norm_topic(topic), days, sources, webhook, datetime.now(UTC).isoformat()),
+            )
+
+    def remove_watch(self, topic: str) -> bool:
+        with self.db:
+            cur = self.db.execute("DELETE FROM watches WHERE topic = ?", (norm_topic(topic),))
+        return cur.rowcount > 0
+
+    def watches(self) -> list[dict]:
+        return [dict(r) for r in self.db.execute("SELECT * FROM watches ORDER BY topic")]
+
+    def mark_watched(self, topic: str, run_id: int) -> None:
+        with self.db:
+            self.db.execute("UPDATE watches SET last_run_id = ? WHERE topic = ?",
+                            (run_id, norm_topic(topic)))  # fmt: skip

agent_wire/research/watch.py

@@ -0,0 +1,70 @@
+"""Watchlist: re-run saved topics, report only what is new since the last run, optional webhook."""
+
+from urllib.parse import urlsplit
+
+from curl_cffi.requests.exceptions import RequestException
+
+from agent_wire.firewall.outbound_privacy import scrub
+from agent_wire.research.store import norm_topic
+
+MAX_NEW = 10
+
+
+def check_webhook(url: str | None) -> str | None:
+    if not url:
+        return None
+    parts = urlsplit(url)
+    if parts.scheme not in ("http", "https") or not parts.hostname:
+        raise ValueError("webhook must be an http(s) URL")
+    return url
+
+
+async def run_watch(wire, watch: dict) -> dict:
+    """One watched topic -> fresh stored run + the items the previous run didn't have."""
+    topic = watch["topic"]
+    result, _, _ = await wire.research_result(topic, days=watch["days"],
+                                              platforms=watch.get("sources"), depth="quick",
+                                              store=True)  # fmt: skip
+    store = wire.store
+    prev = store.previous(topic, result.run_id)
+    fresh = store.new_items(result.run_id, prev)[:MAX_NEW]
+    store.mark_watched(topic, result.run_id)
+    report = {"topic": topic, "run_id": result.run_id, "previous_run": prev,
+              "new": [{"title": i["title"], "url": i["url"], "source": i["source"], "ts": i["ts"]}
+                      for i in fresh]}  # fmt: skip
+    if hook := watch.get("webhook"):
+        report["webhook"] = await _post(wire, hook, report)
+    return report
+
+
+async def _post(wire, url: str, report: dict) -> str:
+    if not report["new"]:
+        return "skipped (nothing new)"
+    try:
+        f = await wire.pool.get(url, method="POST", impersonate=None, json_body=report,
+                                headers={"content-type": "application/json"})  # fmt: skip
+    except RequestException as e:
+        return f"failed: {type(e).__name__}"
+    return f"HTTP {f.status}"
+
+
+async def run_watches(wire, topic: str | None = None) -> str:
+    watches = wire.store.watches()
+    if topic:
+        watches = [w for w in watches if w["topic"] == norm_topic(topic)]
+    if not watches:
+        return "no watched topics (wire watch add <topic>)"
+    out = []
+    for w in watches:
+        r = await run_watch(wire, w)
+        head = f"## {r['topic']} · run #{r['run_id']}"
+        if r["previous_run"]:
+            head += f" · {len(r['new'])} new since run #{r['previous_run']}"
+        else:
+            head += " · first run"
+        if r.get("webhook"):
+            head += f" · webhook {r['webhook']}"
+        lines = [f"- [{i['title']}]({i['url']}) · {i['source']} · {(i['ts'] or '')[:10]}"
+                 for i in r["new"]]  # fmt: skip
+        out.append("\n".join([head, *(lines or ["- nothing new"])]))
+    return scrub("\n\n".join(out))