feat(posthog): add per-metric summary reports (#3824)

Add PostHog analytics per-metric summary reports, mirroring the existing
Sentry morning-digest (Viktor-style) pattern.

- posthog-summary skill: pull metrics via PostHog MCP tools, format a
  per-metric report with current/previous deltas and trends
- report_runner: headless posthog-summary turn returning the report text
- report_prerequisites: PostHog + delivery-provider readiness checks
- CLI: opensre posthog report run + report schedule add/list/remove/run
  (on-demand and scheduled)
- scheduler: POSTHOG_METRIC_REPORT TaskKind, message builder, runner route
- assistant prompt: PostHog report output-shape rule for consistent format
- tests: builder + runner coverage

Author: sanskar-singh-2403

core/agent_harness/prompts/assistant_agent_prompt.py

@@ -66,6 +66,16 @@
     "the user asks."
 )
 
+_POSTHOG_SUMMARY_RULE = (
+    "PostHog metric report: open **I found:** with a one-line scope summary "
+    "(window, project, metric count). Present a per-metric table with columns "
+    "Metric | Current | Previous | Change | % | Trend. Use up/down/flat words for "
+    "the trend, never colour alone. Call out the 1-3 most notable movers with a "
+    "short why-it-matters line. When a metric window returns no data, say so "
+    "explicitly for that metric — do not silently widen the window or present a "
+    "failed query as zero."
+)
+
 _HANDOFF_GUIDANCE: dict[str, str] = {
     "provider:local_llama_connect": (
         "The action planner handed off a vague local-model connection request. "
@@ -251,6 +261,7 @@ def _build_system_prompt(
         f"{setup_rule}\n\n"
         f"{_SOURCE_SCOPED_INVESTIGATION_RULE}\n\n"
         f"{_SENTRY_SUMMARY_RULE}\n\n"
+        f"{_POSTHOG_SUMMARY_RULE}\n\n"
         f"{response_shape_rule}\n\n"
         f"{layout_block}"
         f"{terminology_rule}\n{_MARKDOWN_RULE}\n\n"

docs/posthog-mcp.mdx

@@ -113,3 +113,46 @@ opensre integrations verify posthog_mcp
 ```
 
 A successful check connects to the MCP server and reports how many tools it discovered. If it fails, the most common cause is a missing or invalid personal API key — confirm the key was created with the `MCP Server` preset and that outbound HTTPS to `mcp.posthog.com` is allowed.
+
+## Metric report (scheduled)
+
+Deliver a per-metric PostHog analytics summary to Slack or Telegram, on demand or on a schedule. This uses the headless **posthog-summary** skill path (schema discovery, then one bounded HogQL query per metric), not the investigation pipeline or generic `opensre cron` kinds. It requires the PostHog **MCP** integration above — the REST `posthog` integration alone cannot serve it.
+
+| Command | What it does |
+| --- | --- |
+| `opensre posthog report run` | Run once and print the per-metric report to stdout |
+| `opensre posthog report run --period 30d --metrics "active users,pageviews"` | Run once for a custom window and metric focus |
+| `opensre posthog report schedule add` | Schedule recurring delivery (cron + provider + chat) |
+| `opensre posthog report schedule list` | List PostHog report schedules |
+| `opensre posthog report schedule run TASK_ID` | Run a scheduled report immediately |
+| `opensre posthog report schedule remove TASK_ID` | Remove a schedule |
+
+Example — every Monday at 08:00 London time to Telegram:
+
+```bash
+opensre posthog report schedule add \
+  --cron "0 8 * * 1" \
+  --tz Europe/London \
+  --provider telegram \
+  --chat-id "-1001234567890" \
+  --period 7d
+```
+
+Example — same schedule to a Slack channel (`C…` member/channel id):
+
+```bash
+opensre posthog report schedule add \
+  --cron "0 8 * * 1" \
+  --tz Europe/London \
+  --provider slack \
+  --chat-id C0123ABCD \
+  --period 7d
+```
+
+`--period` accepts a relative window (`24h`, `7d`, `30d`; default `7d`). Optional `--metrics` narrows the report to a comma-separated set instead of the default metric set.
+
+The gateway daemon picks up scheduled reports automatically when it is running. If the LLM is unavailable, the run fails with an error (no deterministic fallback).
+
+<Note>
+The report compares the current window against the previous comparable window per metric. When a metric returns no data for the window it is reported explicitly as zero-ingestion, not silently widened or fabricated.
+</Note>

integrations/posthog/report_prerequisites.py

@@ -0,0 +1,85 @@
+"""Shared prerequisites for PostHog metric report automation."""
+
+from __future__ import annotations
+
+from rich.console import Console
+
+from integrations.sentry.digest_delivery import (
+    delivery_provider_ready,
+    digest_delivery_setup_hint,
+)
+from platform.harness_ports import configured_integration_services
+from platform.scheduler.types import Provider
+
+_console = Console()
+
+POSTHOG_SERVICE_NAMES: tuple[str, ...] = ("posthog_mcp",)
+
+_NOT_CONFIGURED_HINT = (
+    "PostHog MCP is not configured. Run `opensre integrations setup` and verify "
+    "with `opensre integrations verify posthog_mcp` before requesting a report."
+)
+
+
+def posthog_report_available() -> bool:
+    """Return True when a PostHog data source that can serve the skill is configured."""
+    configured = configured_integration_services()
+    return any(name in configured for name in POSTHOG_SERVICE_NAMES)
+
+
+def posthog_not_configured_hint() -> str:
+    """Human-readable guidance shown when no PostHog data source is configured."""
+    return _NOT_CONFIGURED_HINT
+
+
+_PERIOD_UNIT_HOURS: dict[str, int] = {"h": 1, "d": 24, "w": 24 * 7}
+_DEFAULT_WINDOW_HOURS = 24 * 7
+
+
+def stats_period_to_hours(stats_period: str, *, default: int = _DEFAULT_WINDOW_HOURS) -> int:
+    """Convert a relative period string (e.g. ``24h``, ``7d``, ``4w``) to hours.
+
+    Returns ``default`` when the value is empty or not a recognised
+    ``<int><unit>`` shape, so callers never store a misleading window on a task.
+    """
+    value = (stats_period or "").strip().lower()
+    if len(value) < 2:
+        return default
+    unit = value[-1]
+    multiplier = _PERIOD_UNIT_HOURS.get(unit)
+    if multiplier is None:
+        return default
+    try:
+        magnitude = int(value[:-1])
+    except ValueError:
+        return default
+    if magnitude <= 0:
+        return default
+    return magnitude * multiplier
+
+
+def require_posthog_integration() -> None:
+    """Exit when PostHog is not configured."""
+    if posthog_report_available():
+        return
+    _console.print(f"[red]{_NOT_CONFIGURED_HINT}[/red]")
+    raise SystemExit(1)
+
+
+def require_report_delivery_provider(provider: str) -> None:
+    """Exit when the chosen delivery provider is not configured."""
+    provider_enum = Provider(provider)
+    if delivery_provider_ready(provider_enum):
+        return
+    _console.print(f"[red]{digest_delivery_setup_hint(provider_enum)}[/red]")
+    raise SystemExit(1)
+
+
+__all__ = [
+    "POSTHOG_SERVICE_NAMES",
+    "posthog_not_configured_hint",
+    "posthog_report_available",
+    "require_posthog_integration",
+    "require_report_delivery_provider",
+    "stats_period_to_hours",
+]

integrations/posthog/report_runner.py

@@ -0,0 +1,115 @@
+"""Headless PostHog per-metric report via the posthog-summary skill.
+
+Mirrors :mod:`integrations.sentry.morning_digest_runner`: run one headless
+agent turn driven by the ``posthog-summary`` skill and return the assistant
+report text. Used by the ``opensre posthog report`` command and the scheduled
+delivery path (issue #3824).
+"""
+
+from __future__ import annotations
+
+import logging
+from io import StringIO
+
+from rich.console import Console
+
+from core.agent_harness.accounting.run_record import DefaultRunRecordFactory
+from core.agent_harness.accounting.turn_accounting import DefaultTurnAccounting
+from core.agent_harness.error_reporting import DefaultErrorReporter
+from core.agent_harness.harness import AgentHarness, HarnessConfig
+from core.agent_harness.prompts.prompt_context import DefaultPromptContextProvider
+from core.agent_harness.tools.tool_provider import DefaultToolProvider
+from core.agent_harness.turns.default_reasoning_client import DefaultReasoningClientProvider
+from core.agent_harness.turns.headless_adapters import BufferOutputSink
+from core.agent_harness.turns.headless_dispatch import HeadlessAgent
+from core.agent_harness.turns.turn_results import ShellTurnResult
+from integrations.posthog.report_prerequisites import (
+    posthog_not_configured_hint,
+    posthog_report_available,
+)
+from platform.scheduler.agent_runner import AgentPayload
+
+logger = logging.getLogger(__name__)
+
+_REPORT_BASE_PROMPT = (
+    "PostHog analytics report: produce a per-metric summary report of PostHog "
+    "product analytics. Follow the posthog-summary skill workflow."
+)
+
+_DEFAULT_STATS_PERIOD = "7d"
+
+
+def _payload_stats_period(payload: AgentPayload) -> str:
+    period = str(payload.get("stats_period") or "").strip()
+    return period or _DEFAULT_STATS_PERIOD
+
+
+def _payload_metrics(payload: AgentPayload) -> str:
+    return str(payload.get("metrics") or "").strip()
+
+
+def build_report_prompt(payload: AgentPayload) -> str:
+    """Build the fixed headless prompt for scheduled/on-demand metric reports."""
+    prompt = f"{_REPORT_BASE_PROMPT} Use a {_payload_stats_period(payload)} window."
+    metrics = _payload_metrics(payload)
+    if metrics:
+        prompt = f"{prompt} Focus on these metrics: {metrics}."
+    return prompt
+
+
+def _require_posthog_configured() -> None:
+    if posthog_report_available():
+        return
+    raise RuntimeError(posthog_not_configured_hint())
+
+
+def _dispatch_headless_turn(message: str) -> ShellTurnResult:
+    _require_posthog_configured()
+
+    harness = AgentHarness(
+        HarnessConfig(
+            load_env=True,
+            hydrate_integrations=True,
+            warm_integrations=True,
+            persistent_tasks=False,
+            open_storage=False,
+        )
+    )
+    startup = harness.startup()
+    session = startup.session
+    output = BufferOutputSink()
+    error_reporter = DefaultErrorReporter(logger)
+    console = Console(force_terminal=False, file=StringIO())
+
+    agent = HeadlessAgent(
+        session=session,
+        output=output,
+        tools=DefaultToolProvider(session, console, tool_action_logger=logger),
+        prompts=DefaultPromptContextProvider(session),
+        reasoning=DefaultReasoningClientProvider(
+            output=output,
+            error_reporter=error_reporter,
+            session=session,
+        ),
+        run_factory=DefaultRunRecordFactory(session),
+        accounting=DefaultTurnAccounting(session, message),
+        error_reporter=error_reporter,
+        gather_enabled=True,
+        is_tty=False,
+    )
+    return agent.dispatch(message)
+
+
+def run_posthog_report(payload: AgentPayload) -> str:
+    """Run one headless posthog-summary turn and return the assistant report."""
+    message = build_report_prompt(payload)
+    result = _dispatch_headless_turn(message)
+    report = (result.assistant_response_text or result.action_result.response_text).strip()
+    if not result.answered or not report:
+        raise RuntimeError(
+            "PostHog report failed: the reasoning client did not produce a response."
+        )
+    return report
+
+
+__all__ = ["build_report_prompt", "run_posthog_report"]

integrations/posthog/tools/skills/posthog-summary/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: posthog-summary
+description: Summarise PostHog product analytics into a per-metric report (like a Viktor report). Use for PostHog usage overviews, per-metric summaries, product-analytics digests, or "what happened this week" reporting.
+tools:
+  - list_posthog_tools
+  - call_posthog_tool
+---
+
+# PostHog Summary
+
+PostHog product-analytics reporting. Produce a per-metric summary report over a
+window. Single source (PostHog); finish here, then optionally suggest a
+multi-source follow-up.
+
+## 1. Discover
+
+`list_posthog_tools` once with `name_filter: "insights dashboard sql events"` to
+find the query surface. Then call `read-data-schema` (or the equivalent schema
+tool) BEFORE any aggregation query and only reference events and properties it
+confirms exist. Do not reference a property (e.g. `properties.$mcp_error`)
+without seeing it in the schema first — HogQL rejects queries against unknown
+properties. To pull metric data, use `call_posthog_tool` with
+`tool_name: "execute-sql"`; use insight/dashboard tools when the user names a
+specific dashboard.
+
+## 2. Fetch metrics
+
+Map user words to windows:
+
+- **24h** — "today", "overnight", morning report
+- **7d** — "this week", default weekly report
+- **30d** — "this month", monthly rollup
+
+Run **one small HogQL query per metric** — do NOT combine multiple metrics into a
+single aggregated statement, and never cross-join events against synthetic
+"window" rows. That combined shape is the most common cause of PostHog's
+`unknown error running this query`. Compute the two windows with an explicit
+conditional aggregate over a single time filter, e.g.:
+
+```sql
+SELECT
+  countIf(timestamp >= now() - INTERVAL 7 DAY) AS current,
+  countIf(timestamp >= now() - INTERVAL 14 DAY
+          AND timestamp < now() - INTERVAL 7 DAY) AS previous
+FROM events
+WHERE event = '$pageview'
+```
+
+Swap `event = '...'` (or `count(DISTINCT person_id)` for active users) per
+metric. If a query still fails, retry that single metric once with a simpler
+`SELECT count() ... WHERE timestamp >= now() - INTERVAL 7 DAY`, then report the
+metric as failed rather than aborting the whole report.
+
+Default metric set when the user does not name specific metrics (restrict to
+events confirmed present in the schema):
+
+- Active users (`count(DISTINCT person_id)`)
+- Key events (`$pageview`, sessions, or the project's top custom events)
+- New signups / new users if an identifying event exists
+- Notable custom events surfaced by the schema
+
+## 3. Compute per-metric deltas
+
+For each metric: current value, previous value, absolute change, percent change,
+and direction (up / down / flat). Flag a metric as notable when the percent
+change exceeds ~15% in either direction, or when a value hits zero unexpectedly.
+
+## 4. Summarise (per-metric report)
+
+Open with **I found:** a one-line scope summary (window + project + metric
+count). Then a per-metric table:
+
+Metric | Current | Previous | Change | % | Trend
+
+- Trend: use up / down / flat words, never rely on colour alone.
+- Call out the 1-3 most notable movers with a short "why it matters" line.
+- When a window returns no data, say so explicitly for that metric — never
+  silently widen the window or invent numbers.
+
+## Traps
+
+- HogQL time ranges are relative; state the absolute window in the report.
+- Distinguish "metric returned zero" (real) from "query failed" (report the
+  failure, do not present it as zero).
+- The MCP server exposes 240+ tools; narrow with `name_filter` before calling —
+  never dump the full listing.
+- One bounded query per metric group; event-level scans are expensive.
+- `unknown error running this query` almost always means the statement was too
+  complex (multiple metrics combined, cross-joins, or an unverified property).
+  Recover by splitting into one simple per-metric query, not by giving up.

integrations/scheduled_agent_bootstrap.py

@@ -3,13 +3,14 @@
 from __future__ import annotations
 
 from integrations.github.pr_sweep_runner import run_github_pr_sweep
+from integrations.posthog.report_runner import run_posthog_report
 from integrations.sentry.morning_digest_runner import run_sentry_morning_digest
 from integrations.sentry.uptime import run_uptime_watch_tick
 from platform.scheduler.agent_runner import AgentPayload, register_agent_runner
 
 
 def run_scheduled_agent_digest(payload: AgentPayload) -> str:
-    """Route by ``payload['source']`` to Sentry digest, uptime watch, or GitHub PR sweep."""
+    """Route by ``payload['source']`` to Sentry digest, uptime watch, GitHub PR sweep, or PostHog report."""
     source = str(payload.get("source") or "")
     if "uptime_watch" in source:
         return run_uptime_watch_tick(
@@ -18,6 +19,8 @@ def run_scheduled_agent_digest(payload: AgentPayload) -> str:
         )
     if "github_pr" in source:
         return run_github_pr_sweep(payload)
+    if "posthog" in source:
+        return run_posthog_report(payload)
     return run_sentry_morning_digest(payload)