Skip to content

AI agent skill that researches any topic across Reddit, X, YouTube, HN, Polymarket, and the web - then synthesizes a grounded summary

fix(observability): require tty_only=False in source modules' log helpers (#454)

dzivkovi3bad700f0be3
diff --git a/AGENTS.md b/AGENTS.md
index 9c0bca52..d7261541 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -38,6 +38,7 @@ Python 3.12+ required. Use `uv` for the env; the venv lives at `.venv/`.
- `lib/__init__.py` must be bare package marker (comment only, NO eager imports)
- One-time setup: `npx skills add . -g -y` copies the skill into `~/.agents/skills/<name>/` (real directory) and, for harnesses that support symlinked skill dirs, drops a per-host symlink pointing at that copy. **Working-tree edits do NOT propagate automatically** — the `~/.agents/skills/<name>/` copy is frozen at install time. To sync after edits, re-run `npx skills add . -g -y`. For live-edit on a dev machine, replace the install copy with a symlink to the working tree: `ln -sfn "$PWD/skills/last30days" ~/.agents/skills/last30days` (run from the repo root).
- Git remote: origin = public (`mvanhorn/last30days-skill`)
+- Every `lib/*.py` call to `log.source_log(...)` must pass `tty_only=False`. The default is `True`, which silently drops every line when stderr isn't a TTY (Claude Code, Codex, CI, captured output) — turning source observability into invisible failure. Enforced by `tests/test_source_log_visibility.py`.
## Security hygiene
- Never commit real API keys, browser cookies, auth tokens, app passwords, access tokens, or `.env` contents.
diff --git a/skills/last30days/scripts/lib/bird_x.py b/skills/last30days/scripts/lib/bird_x.py
index 0627a749..57e89ac3 100644
--- a/skills/last30days/scripts/lib/bird_x.py
+++ b/skills/last30days/scripts/lib/bird_x.py
@@ -252,10 +252,11 @@ def _run_bird_search(query: str, count: int, timeout: int) -> Dict[str, Any]:
log.source_log(
"X/bird",
f"{log_msg}; retrying in {JSON_DECODE_RETRY_DELAY:.0f}s",
+ tty_only=False,
)
time.sleep(JSON_DECODE_RETRY_DELAY)
continue
- log.source_log("X/bird", log_msg)
+ log.source_log("X/bird", log_msg, tty_only=False)
return {
"error": (
f"Invalid JSON response after {MAX_JSON_DECODE_RETRIES} attempts "
diff --git a/skills/last30days/scripts/lib/bluesky.py b/skills/last30days/scripts/lib/bluesky.py
index d6e494dc..f75d399e 100644
--- a/skills/last30days/scripts/lib/bluesky.py
+++ b/skills/last30days/scripts/lib/bluesky.py
@@ -96,7 +96,7 @@ _TOKEN_MAX_AGE_SECONDS = 5400 # 90 minutes (conservative, tokens last ~2 hours)
def _log(msg: str):
- log.source_log("Bluesky", msg)
+ log.source_log("Bluesky", msg, tty_only=False)
def _create_session(handle: str, app_password: str) -> Optional[str]:
diff --git a/skills/last30days/scripts/lib/digg.py b/skills/last30days/scripts/lib/digg.py
index ea03689c..48844775 100644
--- a/skills/last30days/scripts/lib/digg.py
+++ b/skills/last30days/scripts/lib/digg.py
@@ -53,7 +53,7 @@ POSTS_TIMEOUT = 15
def _log(msg: str) -> None:
- log.source_log("Digg", msg)
+ log.source_log("Digg", msg, tty_only=False)
def _is_available() -> bool:
diff --git a/skills/last30days/scripts/lib/hackernews.py b/skills/last30days/scripts/lib/hackernews.py
index 51e56cb1..3f68843c 100644
--- a/skills/last30days/scripts/lib/hackernews.py
+++ b/skills/last30days/scripts/lib/hackernews.py
@@ -39,7 +39,7 @@ ENRICH_LIMITS = {
def _log(msg: str):
- log.source_log("HN", msg)
+ log.source_log("HN", msg, tty_only=False)
def _date_to_unix(date_str: str) -> int:
diff --git a/skills/last30days/scripts/lib/instagram.py b/skills/last30days/scripts/lib/instagram.py
index ab69b6b3..5a77f9a9 100644
--- a/skills/last30days/scripts/lib/instagram.py
+++ b/skills/last30days/scripts/lib/instagram.py
@@ -152,7 +152,7 @@ def expand_instagram_queries(topic: str, depth: str) -> List[str]:
def _log(msg: str):
- log.source_log("Instagram", msg)
+ log.source_log("Instagram", msg, tty_only=False)
def _parse_date(item: Dict[str, Any]) -> Optional[str]:
diff --git a/skills/last30days/scripts/lib/log.py b/skills/last30days/scripts/lib/log.py
index d8f60b01..8ff2c6ea 100644
--- a/skills/last30days/scripts/lib/log.py
+++ b/skills/last30days/scripts/lib/log.py
@@ -21,6 +21,13 @@ def source_log(prefix: str, msg: str, *, tty_only: bool = True) -> None:
msg: Message text.
tty_only: If True, only log when stderr is a TTY (avoids cluttering
non-interactive output like Claude Code).
+
+ CONVENTION: source modules under `lib/` must call this with
+ `tty_only=False`. The default exists to keep ad-hoc callers quiet, but
+ a source module's logs are observability — silently dropping them under
+ Claude Code, Codex, or CI hides both failures and success signals from
+ the user and the synthesis LLM. The convention is enforced by
+ `tests/test_source_log_visibility.py`.
"""
if tty_only and not sys.stderr.isatty():
return
diff --git a/skills/last30days/scripts/lib/perplexity.py b/skills/last30days/scripts/lib/perplexity.py
index 6a44b885..0a4f5f15 100644
--- a/skills/last30days/scripts/lib/perplexity.py
+++ b/skills/last30days/scripts/lib/perplexity.py
@@ -20,7 +20,7 @@ MODEL_DEEP_RESEARCH = "perplexity/sonar-deep-research"
def _log(msg: str):
- log.source_log("Perplexity", msg)
+ log.source_log("Perplexity", msg, tty_only=False)
def _domain(url: str) -> str:
diff --git a/skills/last30days/scripts/lib/pinterest.py b/skills/last30days/scripts/lib/pinterest.py
index 06df7c53..1c589832 100644
--- a/skills/last30days/scripts/lib/pinterest.py
+++ b/skills/last30days/scripts/lib/pinterest.py
@@ -41,7 +41,7 @@ def _extract_core_subject(topic: str) -> str:
def _log(msg: str):
- log.source_log("Pinterest", msg)
+ log.source_log("Pinterest", msg, tty_only=False)
def _parse_items(raw_items: List[Dict[str, Any]], core_topic: str) -> List[Dict[str, Any]]:
diff --git a/skills/last30days/scripts/lib/polymarket.py b/skills/last30days/scripts/lib/polymarket.py
index f5b51e58..8656decd 100644
--- a/skills/last30days/scripts/lib/polymarket.py
+++ b/skills/last30days/scripts/lib/polymarket.py
@@ -33,7 +33,7 @@ RESULT_CAP = {
def _log(msg: str):
- log.source_log("PM", msg)
+ log.source_log("PM", msg, tty_only=False)
def _extract_core_subject(topic: str) -> str:
diff --git a/skills/last30days/scripts/lib/render.py b/skills/last30days/scripts/lib/render.py
index f267e421..d394ecb4 100644
--- a/skills/last30days/scripts/lib/render.py
+++ b/skills/last30days/scripts/lib/render.py
@@ -1339,6 +1339,7 @@ _FOOTER_SOURCES: list[tuple[str, str, str, str, list[tuple[str, str]]]] = [
# Jobs must appear so a scoped --hiring-signals run (jobs-only) still emits
# the LAW 5 footer; without it the footer was dropped entirely.
("jobs", "💼", "Jobs", "role", []),
+ ("perplexity", "🧠", "Perplexity", "result", [("citations", "citations")]),
]
diff --git a/skills/last30days/scripts/lib/threads.py b/skills/last30days/scripts/lib/threads.py
index ddaa9cfb..c7d2a0bc 100644
--- a/skills/last30days/scripts/lib/threads.py
+++ b/skills/last30days/scripts/lib/threads.py
@@ -25,7 +25,7 @@ DEPTH_CONFIG = {
def _log(msg: str):
- log.source_log("Threads", msg)
+ log.source_log("Threads", msg, tty_only=False)
def _extract_core_subject(topic: str) -> str:
diff --git a/skills/last30days/scripts/lib/tiktok.py b/skills/last30days/scripts/lib/tiktok.py
index c9e7a426..3178b17c 100644
--- a/skills/last30days/scripts/lib/tiktok.py
+++ b/skills/last30days/scripts/lib/tiktok.py
@@ -101,7 +101,7 @@ def expand_tiktok_queries(topic: str, depth: str) -> List[str]:
def _log(msg: str):
- log.source_log("TikTok", msg)
+ log.source_log("TikTok", msg, tty_only=False)
def _parse_date(item: Dict[str, Any]) -> Optional[str]:
diff --git a/skills/last30days/scripts/lib/truthsocial.py b/skills/last30days/scripts/lib/truthsocial.py
index 22070a53..83043e65 100644
--- a/skills/last30days/scripts/lib/truthsocial.py
+++ b/skills/last30days/scripts/lib/truthsocial.py
@@ -21,7 +21,7 @@ DEPTH_CONFIG = {
def _log(msg: str):
- log.source_log("TruthSocial", msg)
+ log.source_log("TruthSocial", msg, tty_only=False)
def _strip_html(html: str) -> str:
diff --git a/tests/test_render_v3.py b/tests/test_render_v3.py
index 5cee82fd..979696bf 100644
--- a/tests/test_render_v3.py
+++ b/tests/test_render_v3.py
@@ -147,6 +147,50 @@ class OutputEnvelopeTests(unittest.TestCase):
close_idx = text.index("<!-- END PASS-THROUGH FOOTER -->")
self.assertIn("All agents reported back!", text[open_idx:close_idx])
+ def _perplexity_item(self, item_id: str, citations: int) -> schema.SourceItem:
+ return schema.SourceItem(
+ item_id=item_id,
+ source="perplexity",
+ title=f"Perplexity Sonar Pro: test topic ({item_id})",
+ body="AI synthesis body.",
+ url="",
+ container="perplexity.ai",
+ published_at="2026-03-16",
+ date_confidence="high",
+ engagement={"citations": citations},
+ metadata={},
+ )
+
+ def test_emoji_footer_includes_perplexity_when_present(self):
+ # Regression: Perplexity items survived retrieval/normalize/dedup but
+ # were dropped from the emoji-tree footer because _FOOTER_SOURCES
+ # omitted perplexity. The synthesis LLM that consumes the pass-through
+ # block then had no Perplexity signal, and users reasonably concluded
+ # the source was broken.
+ report = sample_report()
+ report.items_by_source["perplexity"] = [self._perplexity_item("px1", 7)]
+ text = render.render_compact(report)
+ self.assertIn("🧠 Perplexity:", text)
+ self.assertIn("7 citations", text)
+
+ def test_emoji_footer_perplexity_pluralizes_correctly(self):
+ # The footer line helper appends a literal "s" for plurals, so the
+ # item_word must pluralize regularly. Multi-item runs must produce
+ # "results", not "synthesiss" or other malformed forms.
+ report = sample_report()
+ report.items_by_source["perplexity"] = [
+ self._perplexity_item("px1", 4),
+ self._perplexity_item("px2", 3),
+ self._perplexity_item("px3", 2),
+ ]
+ text = render.render_compact(report)
+ self.assertIn("3 results", text)
+ self.assertNotIn("3 synthesiss", text)
+ self.assertNotIn("3 syntheses", text)
+ # Aggregate of all citation counts (4+3+2 = 9) — confirms multi-item
+ # engagement summation also lands correctly.
+ self.assertIn("9 citations", text)
+
def test_canonical_boundary_scopes_pass_through_to_footer(self):
text = render.render_compact(sample_report())
# New boundary text scopes verbatim to the PASS-THROUGH FOOTER block,
diff --git a/tests/test_source_log_visibility.py b/tests/test_source_log_visibility.py
new file mode 100644
index 00000000..2cdb7dfb
--- /dev/null
+++ b/tests/test_source_log_visibility.py
@@ -0,0 +1,130 @@
+"""Convention enforcement for `log.source_log(..., tty_only=False)`.
+
+`log.source_log` defaults to `tty_only=True`, silently dropping every line
+when stderr isn't a real TTY (every Claude Code / Codex / CI / captured-
+output run). The default exists to keep interactive output uncluttered,
+but it weaponizes any source module that forgets to opt out: error logs,
+query heartbeats, and success signals all disappear.
+
+Ten source modules quietly shipped with this bug. This test prevents the
+eleventh. Every `log.source_log(...)` call site under
+`skills/last30days/scripts/lib/` must pass `tty_only=False` explicitly.
+The cost is one kwarg per call; the value is that source observability
+never goes silent again, even when the next contributor copies an old
+`_log` template without thinking.
+
+Implementation uses `ast.parse` (not regex) so the convention check is
+robust against multi-line calls, nested parens in f-strings, calls inside
+docstrings or comments, whitespace variation (`tty_only = False`), and
+future indentation styles.
+"""
+
+import ast
+import io
+import pathlib
+import sys
+import unittest
+from unittest.mock import patch
+
+from lib import bluesky, perplexity
+
+REPO_ROOT = pathlib.Path(__file__).resolve().parent.parent
+LIB_DIR = REPO_ROOT / "skills" / "last30days" / "scripts" / "lib"
+
+
+class _SourceLogCallFinder(ast.NodeVisitor):
+ """Collect every `log.source_log(...)` call from a parsed module."""
+
+ def __init__(self) -> None:
+ self.calls: list[ast.Call] = []
+
+ def visit_Call(self, node: ast.Call) -> None:
+ func = node.func
+ if (
+ isinstance(func, ast.Attribute)
+ and func.attr == "source_log"
+ and isinstance(func.value, ast.Name)
+ and func.value.id == "log"
+ ):
+ self.calls.append(node)
+ self.generic_visit(node)
+
+
+def _has_tty_only_false_kwarg(call: ast.Call) -> bool:
+ """Return True iff the call passes `tty_only=False` as a keyword arg."""
+ for kw in call.keywords:
+ if kw.arg == "tty_only" and isinstance(kw.value, ast.Constant) and kw.value.value is False:
+ return True
+ return False
+
+
+def _iter_source_modules() -> list[pathlib.Path]:
+ """Yield production source modules under lib/ (excluding vendor and __init__)."""
+ paths: list[pathlib.Path] = []
+ for path in LIB_DIR.rglob("*.py"):
+ if path.name == "log.py":
+ continue # definition site; not a caller
+ if "vendor" in path.parts:
+ continue # vendored third-party code
+ if path.name == "__init__.py":
+ continue # bare package marker per AGENTS.md
+ paths.append(path)
+ return sorted(paths)
+
+
+class SourceLogConventionTests(unittest.TestCase):
+ """Enforce the project convention at the codebase level."""
+
+ def test_every_source_log_call_passes_tty_only_false(self):
+ violations: list[str] = []
+ for path in _iter_source_modules():
+ text = path.read_text(encoding="utf-8")
+ try:
+ tree = ast.parse(text, filename=str(path))
+ except SyntaxError as exc:
+ self.fail(f"Could not parse {path.name}: {exc}")
+ finder = _SourceLogCallFinder()
+ finder.visit(tree)
+ for call in finder.calls:
+ if not _has_tty_only_false_kwarg(call):
+ violations.append(f"{path.relative_to(REPO_ROOT)}:{call.lineno}")
+ if violations:
+ self.fail(
+ "Source modules must call `log.source_log(..., tty_only=False)` so "
+ "lines stay visible under non-TTY contexts (Claude Code, Codex, CI, "
+ "captured output). See AGENTS.md for the convention. Violations:\n - "
+ + "\n - ".join(violations)
+ )
+
+
+class _NonTTYStringIO(io.StringIO):
+ """StringIO subclass that reports as a non-TTY stream."""
+
+ def isatty(self) -> bool:
+ return False
+
+
+class PerplexityAndBlueskyVisibilityTests(unittest.TestCase):
+ """Targeted regression tests for the two original bug instances.
+
+ Kept alongside the convention test so a future refactor of either
+ module immediately surfaces a regression if the opt-out is dropped.
+ """
+
+ def _captured_stderr_under_non_tty(self, log_callable) -> str:
+ fake_stderr = _NonTTYStringIO()
+ with patch.object(sys, "stderr", fake_stderr):
+ log_callable("visibility probe")
+ return fake_stderr.getvalue()
+
+ def test_perplexity_log_visible_under_non_tty(self):
+ out = self._captured_stderr_under_non_tty(perplexity._log)
+ self.assertIn("[Perplexity] visibility probe", out)
+
+ def test_bluesky_log_visible_under_non_tty(self):
+ out = self._captured_stderr_under_non_tty(bluesky._log)
+ self.assertIn("[Bluesky] visibility probe", out)
+
+
+if __name__ == "__main__":
+ unittest.main()