thoughtleaders-cli 0.9.19__tar.gz → 0.9.20__tar.gz

{thoughtleaders_cli-0.9.19 → thoughtleaders_cli-0.9.20}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tl-cli",
-  "version": "0.9.19",
+  "version": "0.9.20",
   "description": "ThoughtLeaders CLI — query sponsorship deals, channels, brands, uploads, and intelligence from the terminal",
   "author": {
     "name": "ThoughtLeaders",

{thoughtleaders_cli-0.9.19 → thoughtleaders_cli-0.9.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: thoughtleaders-cli
-Version: 0.9.19
+Version: 0.9.20
 Summary: ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence
 Project-URL: Homepage, https://thoughtleaders.io
 Project-URL: Repository, https://github.com/ThoughtLeaders-io/thoughtleaders-cli

{thoughtleaders_cli-0.9.19 → thoughtleaders_cli-0.9.20}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "thoughtleaders-cli"
-version = "0.9.19"
+version = "0.9.20"
 description = "ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence"
 readme = "README.md"
 license = "MIT"

{thoughtleaders_cli-0.9.19 → thoughtleaders_cli-0.9.20}/skills/_shared/tl_data.py

@@ -235,6 +235,26 @@ def preflight() -> None:
     _tl(["whoami"], timeout=60)
 
 
+def report_run(skill: str, outcome: str = "completed") -> None:
+    """Tell ThoughtLeaders a skill opened from one of its surfaces has finished.
+
+    Best effort, never raises: the skill's own result is already on the way
+    to the user, and a report that cannot be delivered must not change that.
+    A skill started by hand has no run to close; the CLI says so and exits 0.
+    """
+    exe = shutil.which(TL_BIN) or TL_BIN
+    try:
+        subprocess.run(
+            [exe, "agent", "complete", skill, "--outcome", outcome],
+            capture_output=True,
+            env=_child_env(),
+            timeout=30,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        pass
+
+
 if __name__ == "__main__":
     if len(sys.argv) == 2 and sys.argv[1] == "preflight":
         preflight()

{thoughtleaders_cli-0.9.19 → thoughtleaders_cli-0.9.20}/skills/tl-brand-creator-connection/SKILL.md

@@ -224,6 +224,8 @@ PROFILE completion, three lines:
 2. Fact count and what the socials lane did: `socials off, N linked platforms listed unread` or `socials on, N websites opened, N sources read, N facts`. Report "on" with 0 facts as such.
 3. What was cached on the channel record this run (host name, format label, host aliases, sibling channels), from `host_name_cache` and `cache`.
 
+A PROFILE-only run (no brand) is finished here: run `tl agent complete tl-brand-creator-connection` so a run opened from a ThoughtLeaders surface is counted (the CONNECT page reports itself). If the ledger could not be built, run it with `--outcome failed`.
+
 **Fast run** (a run shape, not a flag): PROFILE only, primary channel only, socials OFF without asking, default selection, no corroboration round.
 
 ## 4. CONNECT pipeline

{thoughtleaders_cli-0.9.19 → thoughtleaders_cli-0.9.20}/skills/tl-brand-creator-connection/scripts/build_html.py

@@ -86,6 +86,10 @@ from collections import Counter, defaultdict
 sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
 import tier_hint  # sibling module  # noqa: E402
 from store_io import read_ledger  # sibling module  # noqa: E402
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[2] / "_shared"))
+import tl_data  # noqa: E402
+
+SKILL = "tl-brand-creator-connection"
 
 BADGES = {
     "direct": "direct",
@@ -2092,6 +2096,8 @@ def main() -> None:
            elapsed_s=round(time.monotonic() - t0, 1))
     if problems:
         print("PAGE CONTRACT: " + "; ".join(problems), file=sys.stderr)
+    # The connections page is the deliverable; a no-fit page is still a result.
+    tl_data.report_run(SKILL)
 
 
 if __name__ == "__main__":

{thoughtleaders_cli-0.9.19 → thoughtleaders_cli-0.9.20}/skills/tl-channel-authenticity/scripts/analyze_channel.py

@@ -42,6 +42,7 @@ import tl_data
 
 import channel_lookup
 
+SKILL = "tl-channel-authenticity"
 OUT_DIR = Path("/tmp")
 
 
@@ -147,12 +148,18 @@ def main() -> None:
         if args.finalize:
             if len(args.finalize) < 2:
                 ap.error("--finalize needs STATE and at least one LLM file")
-            res = finalize(args.finalize[0], args.finalize[1:])
+            try:
+                res = finalize(args.finalize[0], args.finalize[1:])
+            except Exception:
+                tl_data.report_run(SKILL, "failed")
+                raise
             print(res["markdown"])
             print(
                 f"\n<!-- final JSON: {res['final_json']} · "
                 f"report: {res['report_md']} -->"
             )
+            # The verdict is the deliverable; the run is counted once it is printed.
+            tl_data.report_run(SKILL)
         elif args.ref:
             res = collect(args.ref)
             print(json.dumps(res, indent=2))

{thoughtleaders_cli-0.9.19 → thoughtleaders_cli-0.9.20}/skills/tl-save-report/SKILL.md

@@ -505,9 +505,11 @@ The follow-up offer matters because **FilterSet changes (keywords, demographics,
 
 If the user requests a chart, create it as a SVG graphic.
 
+Then, as the last step, run `tl agent complete tl-save-report`. A run opened from a ThoughtLeaders surface (the Chrome extension's skill buttons) is counted as finished by it; one started by hand gets a short note and nothing else, which is fine.
+
 ### On failure
 
-If the command exits non-zero, the CLI prints the error on stderr (shape: `Error (NNN): <detail>` for most codes; specific lines for 401/402/403). **Surface the error verbatim** — do NOT silently report success.
+If the command exits non-zero, the CLI prints the error on stderr (shape: `Error (NNN): <detail>` for most codes; specific lines for 401/402/403). **Surface the error verbatim** — do NOT silently report success. Then run `tl agent complete tl-save-report --outcome failed`.
 
 Map the visible code + detail to the likely cause:
 

{thoughtleaders_cli-0.9.19 → thoughtleaders_cli-0.9.20}/skills/tl-views-guarantee/scripts/vg.py

@@ -15,12 +15,18 @@ Usage:
 import argparse
 import datetime
 import json
+import pathlib as _pathlib
 import random
 import subprocess
 import sys
 from dataclasses import dataclass
 from typing import TypedDict
 
+sys.path.insert(0, str(_pathlib.Path(__file__).resolve().parents[2] / "_shared"))
+import tl_data  # noqa: E402
+
+SKILL = "tl-views-guarantee"
+
 SEED = 42  # passed to a fresh random.Random in bootstrap_sweep so each call starts from the same RNG state
 DEFAULT_MAX_BUNDLE_SIZE = 4
 HARD_MAX_BUNDLE_SIZE = 10
@@ -368,4 +374,15 @@ def main() -> None:
 
 
 if __name__ == "__main__":
-    main()
+    # The run is counted once the four lines are out; a data shortfall (a
+    # message exit) is a run with nothing to show, a crash is a failed one.
+    try:
+        main()
+    except SystemExit as exc:
+        if exc.code not in (None, 0):
+            tl_data.report_run(SKILL, "no_results" if isinstance(exc.code, str) else "failed")
+        raise
+    except Exception:
+        tl_data.report_run(SKILL, "failed")
+        raise
+    tl_data.report_run(SKILL)

{thoughtleaders_cli-0.9.19 → thoughtleaders_cli-0.9.20}/src/tl_cli/__init__.py

@@ -1,3 +1,3 @@
 """ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence."""
 
-__version__ = "0.9.19"
+__version__ = "0.9.20"

thoughtleaders_cli-0.9.20/src/tl_cli/commands/agent.py

@@ -0,0 +1,57 @@
+"""tl agent — the AI agent you open ThoughtLeaders skills in.
+
+A skill handed over from a ThoughtLeaders surface (the Chrome extension's skill
+buttons, the web app's export door) is counted as finished when it reports back
+here with its slug and how it ended.
+"""
+
+import typer
+from rich.console import Console
+
+from tl_cli._typer_utils import AlphaSortedTyperGroup
+from tl_cli.client.errors import ApiError, handle_api_error
+from tl_cli.client.http import get_client
+from tl_cli.output.formatter import detect_format, output_single
+
+app = typer.Typer(cls=AlphaSortedTyperGroup, help="Your AI agent: report a skill it ran as finished (free)")
+
+OUTCOMES = ("completed", "no_results", "failed")
+NO_RUN_CODE = "run_not_found"
+
+
+@app.command("complete")
+def complete_cmd(
+    skill: str = typer.Argument(..., help="The skill's slug, e.g. tl-views-guarantee"),
+    outcome: str = typer.Option("completed", "--outcome", help="How the run ended: completed, no_results or failed"),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+) -> None:
+    """Report that a skill opened from a ThoughtLeaders surface has finished.
+
+    Skills call this as their last step. Only a skill opened from a ThoughtLeaders
+    surface has a run to close; one started by hand is simply not counted, and
+    this command says so and exits cleanly, so a skill's own result is never
+    lost over it.
+
+    Examples:
+        tl agent complete tl-views-guarantee
+        tl agent complete tl-channel-authenticity --outcome no_results
+        tl agent complete tl-brand-creator-connection --outcome failed
+    """
+    fmt = detect_format(json_output, False, False, toon_output)
+    err = Console(stderr=True)
+    if outcome not in OUTCOMES:
+        err.print(f"[red]Error:[/red] --outcome must be one of: {', '.join(OUTCOMES)}.")
+        raise typer.Exit(1)
+
+    client = get_client()
+    try:
+        data = client.post("/agent/complete", json_body={"skill": skill, "outcome": outcome})
+        output_single(data, fmt)
+    except ApiError as e:
+        if e.status_code == 404 and isinstance(e.raw, dict) and e.raw.get("code") == NO_RUN_CODE:
+            err.print(f"[dim]No open run of {skill} from a ThoughtLeaders surface; nothing to report.[/dim]")
+            return
+        handle_api_error(e)
+    finally:
+        client.close()

{thoughtleaders_cli-0.9.19 → thoughtleaders_cli-0.9.20}/src/tl_cli/main.py

@@ -10,33 +10,35 @@ import typer
 from rich.console import Console
 
 from tl_cli import __version__
-from tl_cli._typer_utils import AlphaSortedTyperGroup
 from tl_cli import config as tl_config
+from tl_cli._typer_utils import AlphaSortedTyperGroup
 from tl_cli.auth.commands import app as auth_app
+from tl_cli.commands.agent import app as agent_app
 from tl_cli.commands.balance import app as balance_app
-from tl_cli.commands.changelog import changelog_command
 from tl_cli.commands.brands import app as brands_app
 from tl_cli.commands.bulk_import import bulk_import_command
-from tl_cli.commands.credits import app as credits_app
+from tl_cli.commands.changelog import changelog_command
 from tl_cli.commands.channels import app as channels_app
+from tl_cli.commands.credits import app as credits_app
 from tl_cli.commands.db import app as db_app
 from tl_cli.commands.deals import app as deals_app
+from tl_cli.commands.describe import app as describe_app
+from tl_cli.commands.doctor import app as doctor_app
 from tl_cli.commands.matches import app as matches_app
 from tl_cli.commands.memory import app as memory_app
 from tl_cli.commands.profiles import app as profiles_app
 from tl_cli.commands.proposals import app as proposals_app
 from tl_cli.commands.recommender import app as recommender_app
-from tl_cli.commands.sponsorships import app as sponsorships_app
-from tl_cli.commands.describe import app as describe_app
-from tl_cli.commands.schema import app as schema_app
-from tl_cli.commands.doctor import app as doctor_app
 from tl_cli.commands.reports import app as reports_app
-from tl_cli.commands.workflows import app as workflows_app
+from tl_cli.commands.schema import app as schema_app
 from tl_cli.commands.setup import app as setup_app
-from tl_cli.commands.skills import app as skills_app, check_skill_staleness
+from tl_cli.commands.skills import app as skills_app
+from tl_cli.commands.skills import check_skill_staleness
 from tl_cli.commands.snapshots import app as snapshots_app
+from tl_cli.commands.sponsorships import app as sponsorships_app
 from tl_cli.commands.uploads import app as uploads_app
 from tl_cli.commands.whoami import app as whoami_app
+from tl_cli.commands.workflows import app as workflows_app
 
 app = typer.Typer(
     name="tl",
@@ -124,6 +126,7 @@ app.add_typer(balance_app, name="balance")
 app.add_typer(credits_app, name="credits")
 app.add_typer(doctor_app, name="doctor")
 app.add_typer(whoami_app, name="whoami")
+app.add_typer(agent_app, name="agent")
 
 # `changelog` is a single command (not a sub-typer) so positional version args
 # don't get interpreted as subcommand names.

thoughtleaders_cli-0.9.20/tests/test_agent_complete.py

@@ -0,0 +1,81 @@
+"""Tests for `tl agent complete`: the skill reports its slug and outcome, and a
+skill with no run behind it exits cleanly so the skill's own result survives."""
+
+from unittest.mock import patch
+
+from typer.testing import CliRunner
+
+from tl_cli.client.errors import ApiError
+from tl_cli.commands import agent as agent_mod
+from tl_cli.main import app as root_app
+
+runner = CliRunner()
+
+
+class _FakeClient:
+    def __init__(self, payload: dict | None = None, error: ApiError | None = None) -> None:
+        self.payload = payload or {}
+        self.error = error
+        self.posts: list[tuple[str, dict]] = []
+
+    def post(self, path: str, json_body: dict | None = None, timeout: float | None = None) -> dict:
+        self.posts.append((path, json_body or {}))
+        if self.error is not None:
+            raise self.error
+        return self.payload
+
+    def close(self) -> None:
+        pass
+
+
+def _done() -> dict:
+    return {
+        "run_id": "0123456789abcdef",
+        "skill": "tl-views-guarantee",
+        "outcome": "completed",
+        "usage": {"credits_charged": 0},
+    }
+
+
+def test_reports_the_skill_with_the_default_outcome() -> None:
+    fake = _FakeClient(_done())
+    with patch.object(agent_mod, "get_client", return_value=fake):
+        result = runner.invoke(root_app, ["agent", "complete", "tl-views-guarantee", "--json"])
+    assert result.exit_code == 0, result.output
+    assert fake.posts == [("/agent/complete", {"skill": "tl-views-guarantee", "outcome": "completed"})]
+    assert '"run_id": "0123456789abcdef"' in result.output
+
+
+def test_outcome_is_passed_through() -> None:
+    fake = _FakeClient(_done())
+    with patch.object(agent_mod, "get_client", return_value=fake):
+        result = runner.invoke(root_app, ["agent", "complete", "tl-channel-authenticity", "--outcome", "no_results"])
+    assert result.exit_code == 0, result.output
+    assert fake.posts[0][1] == {"skill": "tl-channel-authenticity", "outcome": "no_results"}
+
+
+def test_unknown_outcome_is_refused_before_any_request() -> None:
+    fake = _FakeClient(_done())
+    with patch.object(agent_mod, "get_client", return_value=fake):
+        result = runner.invoke(root_app, ["agent", "complete", "tl-views-guarantee", "--outcome", "done"])
+    assert result.exit_code == 1
+    assert fake.posts == []
+
+
+def test_a_skill_started_by_hand_exits_cleanly() -> None:
+    # The command sits at the end of a skill's script; a non-zero exit here would
+    # read as the skill failing, when it only has nothing to report.
+    error = ApiError(404, "No open run", raw={"code": "run_not_found"})
+    fake = _FakeClient(error=error)
+    with patch.object(agent_mod, "get_client", return_value=fake):
+        result = runner.invoke(root_app, ["agent", "complete", "tl-views-guarantee"])
+    assert result.exit_code == 0, result.output
+    assert "No open run of tl-views-guarantee" in result.stderr
+
+
+def test_other_errors_still_fail() -> None:
+    error = ApiError(401, "Not signed in", raw={"code": "not_authenticated"})
+    fake = _FakeClient(error=error)
+    with patch.object(agent_mod, "get_client", return_value=fake), patch.object(agent_mod, "handle_api_error") as handled:
+        runner.invoke(root_app, ["agent", "complete", "tl-views-guarantee"])
+    handled.assert_called_once_with(error)

{thoughtleaders_cli-0.9.19 → thoughtleaders_cli-0.9.20}/tests/test_shared_tl_data.py

@@ -166,3 +166,21 @@ class TestTransientRetry:
         _use(monkeypatch, self._flaky(tmp_path, 1, "no such table"))
         with pytest.raises(tl_data.DataError, match="no such table"):
             tl_data.db_pg("SELECT 1")
+
+
+class TestReportRun:
+    def test_reports_the_skill_and_outcome(self, tmp_path: Path, monkeypatch) -> None:
+        runner = _stub(tmp_path, exit_code=0, stdout="{}")
+        monkeypatch.setattr(tl_data, "TL_BIN", str(runner))
+        tl_data.report_run("tl-views-guarantee", "no_results")
+        call = json.loads((tmp_path / "call.json").read_text())
+        assert call["argv"] == ["agent", "complete", "tl-views-guarantee", "--outcome", "no_results"]
+
+    def test_never_raises(self, tmp_path: Path, monkeypatch) -> None:
+        # The report sits after the skill's own result; a missing or failing
+        # CLI must not turn a finished run into a crash.
+        monkeypatch.setattr(tl_data, "TL_BIN", str(tmp_path / "no-such-tl"))
+        tl_data.report_run("tl-views-guarantee")
+        runner = _stub(tmp_path, exit_code=3, stderr="server error")
+        monkeypatch.setattr(tl_data, "TL_BIN", str(runner))
+        tl_data.report_run("tl-views-guarantee", "failed")

{thoughtleaders_cli-0.9.19 → thoughtleaders_cli-0.9.20}/uv.lock

@@ -422,7 +422,7 @@ wheels = [
 
 [[package]]
 name = "thoughtleaders-cli"
-version = "0.9.19"
+version = "0.9.20"
 source = { editable = "." }
 dependencies = [
     { name = "authlib" },