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

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

@@ -1,6 +1,6 @@
 {
   "name": "tl-cli",
-  "version": "0.9.18",
+  "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.18 → thoughtleaders_cli-0.9.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: thoughtleaders-cli
-Version: 0.9.18
+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.18 → thoughtleaders_cli-0.9.20}/pyproject.toml

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

{thoughtleaders_cli-0.9.18 → 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.18 → thoughtleaders_cli-0.9.20}/skills/connector-impact/SKILL.md

@@ -65,7 +65,11 @@ questions from `help.md` or the mapping file, then continue the run.
 - ELSE ask ONE question covering every unstated item (view, brand, window), one line per view on
   what it shows. Never default silently.
 - IF `autonomous`, `--auto` or "don't stop to ask": all three views, default window, no questions.
-- IF the user says "include pending": count pending actions in the headline numbers.
+- IF the user explicitly asks to include pending for this run: count pending actions in the
+  headline numbers, label both states, and do not ask. This holds even beside a standing line
+  such as "keep pending separate unless I ask"; the explicit request wins. Interpret the request's
+  meaning: "do not include pending" or a standing "unless I ask to include pending" rule does
+  not enable pending by itself.
 
 ## Workflow
 
@@ -133,11 +137,11 @@ deliverable is per partner and per deal; nothing below that grain leaves Impact.
    type differs from the one the user described, stop and tell the user.
 6. Resolve the brand with `tl brands find "<name>"`. Never match brand names in SQL.
 7. IF creators are named, resolve them to TL channel ids now (stage 1), before any deal read.
-8. Record the currency the Impact figures are in and the TL deals' `price_currency`. On a
-   report, the figures' currency is its display-currency setting; do not change it. IF the two
-   differ, tell the user now and apply mapping 2.3.
+8. Record the currency the Impact figures are in. TL prices are always USD, and the report is in
+   USD. On a report, the figures' currency is its display-currency setting; do not change it. IF
+   the Impact figures are not in USD (usually EUR), tell the user now and apply mapping 2.3.
 9. Quote the run's credit cost (above), then state the scope back: brand, creators, window, view,
-   states (approved headline, pending separate), currencies.
+   the selected headline states with approved and pending labelled separately, currencies.
 
 ### 1. TL side
 
@@ -272,6 +276,9 @@ group (mapping 4.4).
   platforms); ELSE list it as unresolved without asking.
 - List actions that used the creator's promo codes but are credited to another partner (mapping
   3.4).
+- Use only promo codes that appear on Impact actions. Never build a code from a creator's name to
+  search for, and never call a code the creator's unless it is on their own actions. IF their
+  actions carry no code, say so.
 - List TL deals with no Impact partner, with the likely reason.
 
 ### 4. Dates
@@ -314,6 +321,9 @@ not reach a number quoted earlier — the reader meets the figure first. Where t
 repeat several times in one section, mark each figure and carry one note for the section, placed
 where a reader meets the first of them.
 
+Deliver final figures only. IF a figure changes while you write, replace it: no old figure,
+arrow or "correction" note stays in the report.
+
 Use business terms from the `tl` glossary, not table names. IF the user asks for a chart, render
 it as SVG.
 
@@ -347,5 +357,11 @@ channel added from a link the user gave. IF the user wants results saved, offer
     otherwise empty: a bare `0` does not say which currency it is zero of. A currency named once
     in the table's title covers the table.
 13. Mapping 2 holds: views from TL only; Paid to TL and commission in separate columns; all-in
-    figures only in the to-date block; converted columns use a shown ECB rate; the TL price is
-    never converted.
+    figures only in the to-date block; Impact money not in USD is shown in USD at a shown ECB
+    monthly rate, with the original beside it, or flagged when conversion is unavailable; the
+    TL price is never converted, and unexpected price currencies follow mapping 2.3.
+14. Promo-code sales count like link sales: approved actions state the observed promo-code split
+    in the table and the opening summary, with attribution labels only where Impact supplies
+    evidence (mapping 2.2); a held-back conversion rate points to actions per 1,000 views when
+    available; a creator with codes credited to other partners has the "including" line
+    (mapping 2, 2.2, 3.4).

{thoughtleaders_cli-0.9.18 → thoughtleaders_cli-0.9.20}/skills/connector-impact/references/help.md

@@ -17,7 +17,8 @@ the right tool for you.
 - Your TL login (the `tl` CLI).
 - One way into Impact:
   - Impact's connector for Claude (recommended): add a custom connector with the URL
-    `https://mcp.impact.com/mcp` and sign in with your Impact login.
+    `https://mcp.impact.com/mcp`, enter `mcp-impact-claude` as the OAuth client ID under
+    Advanced settings, and sign in with your Impact login.
   - The Impact API, with a read-only token you create in Impact (Settings → Technical → API).
   - A CSV export from Impact's Reports (Performance by Partner or by Day), dropped into the chat.
   - The Impact website, open and signed in in your browser. Slowest, but no setup.
@@ -75,9 +76,11 @@ TL data takes about a day to fill in.
 - The TL price and the Impact commission are always shown separately. They're added together
   only in an "All-in cost to date" box under the table, over the same videos and dates, with an
   as-of date.
-- If Impact and TL use different currencies, every money column names its currency. Where money
-  is compared with money, a converted column is added at the European Central Bank's monthly
-  average rate, with the rate shown. The TL price is never converted.
+- Everything is reported in US dollars, because TL prices are always in USD. If your Impact
+  account shows another currency, such as euros, those figures are converted to USD at the
+  European Central Bank's monthly average rate, with the original amount and the rate shown.
+  The TL price is never converted. If a TL deal unexpectedly records another currency, you'll
+  see that price in its recorded currency and affected USD figures will wait for confirmation.
 
 Costs and CPMs here are last-click numbers from your own Impact account: they count sales that
 arrived through the creator's link, not sales the video may have driven some other way. They're a
@@ -92,7 +95,7 @@ floor on what a sponsorship did, not the full picture.
 | Action | A conversion: sale, sign-up or install |
 | Revenue | Your sales, not TL revenue |
 | Action Cost | Commission paid to the creator through Impact, not the TL price |
-| Total Cost | That commission plus Impact's fees |
+| Total Cost | That commission plus per-click payments, bonuses, make-good and fixed payments made through Impact. No Impact platform fee |
 | Ad | A tracking link or creative, not a TL ad spot |
 | Contract | Commission terms, not a TL IO |
 

{thoughtleaders_cli-0.9.18 → thoughtleaders_cli-0.9.20}/skills/connector-impact/references/impact-schema.md

@@ -9,7 +9,7 @@ The user brings one route. This skill never holds a login.
 
 | Route | Setup | Best for |
 |---|---|---|
-| Impact MCP | Custom connector `https://mcp.impact.com/mcp`, signed in with the user's Impact login | Most questions; aggregates on Impact's side |
+| Impact MCP | Custom connector `https://mcp.impact.com/mcp` with OAuth client ID `mcp-impact-claude` under Advanced settings (Impact does not support dynamic client registration), signed in with the user's Impact login | Most questions; aggregates on Impact's side |
 | Impact Brand API | `AccountSID` + a token the user creates (Settings → Technical → API) | Action-level detail, long ranges |
 | CSV export | Reports: Performance by Partner, Performance by Day, Advanced Action Listing | No setup |
 | Impact web app | The user's own browser, already signed in. Read report pages only: no downloads, no settings, no answers to pop-ups | When none of the above is set up. Slowest route; same report data |
@@ -42,7 +42,7 @@ Filters: `ActionDateStart` / `ActionDateEnd` (on `EventDate`; use these for wind
 | `AdId` | integer | Ad or link behind the winning click |
 | `Amount`, `DeltaAmount`, `IntendedAmount` | number | Sale value: current, last change, original |
 | `Payout`, `DeltaPayout`, `IntendedPayout` | number | Partner commission: current, last change, original |
-| `ClientCost` | number | Payout plus fees |
+| `ClientCost` | number | Cost for this action: payout plus fees. Not the grouped report's Total Cost; never sum it as a substitute for all action, click and fixed payments |
 | `Currency` | string | ISO 4217, for all money on the row |
 | `EventDate`, `ReferringDate`, `CreationDate`, `LockingDate`, `ClearedDate` | date-time | See mapping 1.2 |
 | `ReferringType`, `ReferringDomain` | string | Attribution method, click site |
@@ -119,8 +119,9 @@ documentation:
 | `Sales`, `Leads`, `Calls`, `Mobile_Installs` | Actions split by type |
 | `Sale_Amount` | Sale value ("Revenue" on the Brand dashboard) |
 | `Action_Cost` | Commission on actions |
-| `Other_Cost` | Fixed payments made through Impact (e.g. a flat fee), which can be spread as equal daily amounts across the payment period |
-| `Total_Cost` | Includes `Action_Cost`, bonuses and `Other_Cost` |
+| `Other_Cost` | Bonuses, make-good and fixed payments made through Impact (e.g. a flat fee), which can be spread as equal daily amounts across the payment period |
+| `Click_Cost` | Pay-per-click payments |
+| `Total_Cost` | `Action_Cost` + `Click_Cost` + `Other_Cost`. Holds no Impact platform fee |
 | `CR`, `EPC`, `AOV`, `RR` | Conversion rate, earnings per click, average order value, reversal rate |
 
 On a Partner account the labels say "Earnings" instead of "Cost" (Action Earnings, Total

{thoughtleaders_cli-0.9.18 → thoughtleaders_cli-0.9.20}/skills/connector-impact/references/impact-to-tl-mapping.md

@@ -85,8 +85,8 @@ counts in Paid to TL.
 | Actions | count of Actions, by state | `conversions` | Use Impact's; the TL value is hand-entered on few deals. |
 | Action Cost | sum of `Payout` | none | Affiliate commission paid to the creator through Impact. Never the TL price (2.1). |
 | Revenue | sum of `Amount` | `revenue` + `revenue_currency` | The brand's sales. In TL, "revenue" means sold deal price. Write "sales revenue (Impact)". |
-| Total Cost | sum of `ClientCost` | none | Commission plus Impact fees and bonuses; not the creator's cost. Use only for whole-program cost. A flat fee paid through Impact sits in `Other_Cost`, inside Total Cost: IF it could be the same fee as a TL `price`, ask before adding them. |
-| Conversion Rate | Actions ÷ Clicks | none | Impact actions over Impact clicks only. Suppressed per displayed ratio when the code-tracked share passes half (below). |
+| Total Cost | Grouped report's Total Cost, mapped from its metadata (schema: *Reports*) | none | Action Cost plus Click Cost plus Other Cost, with no Impact platform fee; not the creator's cost. Never sum action-level `ClientCost` for this: it covers action payouts and fees, not all click and fixed payments. IF the route supplies neither Total Cost nor all three components for the same scope, mark Total Cost unavailable. Use only for whole-program cost. A flat fee paid through Impact sits in `Other_Cost`, inside Total Cost: IF it could be the same fee as a TL `price`, ask before adding them. |
+| Conversion Rate | Actions ÷ Clicks | none | Impact actions over Impact clicks only. Suppressed per displayed ratio when the code-tracked share passes half (below); actions per 1,000 views is then the rate to read where TL views are available. |
 | none | | Views: `views` on the video-index document (1.4), `projected_views_at_purchase_date` | TL only. Impact has no views. |
 | none | | Paid to TL: `price` + `price_currency` | TL only. |
 | none | | Sponsorship CPM: Paid to TL ÷ the video's current TL views × 1,000 | Always computed, on deals with TL views (1.4). Never from projected views (2.2). |
@@ -104,8 +104,10 @@ creator's actions — never once over the window and applied to every cell.
   and never a blank cell: the column keeps its shape so the reader can tell suppression from
   absence.
 - ELSE print the rate.
-- Give the reason once in the output: a sale made with a promo code never had to click, so the
-  rate would count conversions the clicks could not have produced.
+- Give the reason once in the output: a sale made with a promo code can occur without a click,
+  so the rate may count conversions the tracked clicks did not produce. In the same note, point the
+  reader to actions per 1,000 views, which counts code and link sales alike. IF the row has no TL
+  views or zero views, say this alternative rate is unavailable; never invent views or divide by zero.
 
 Event types: show approved actions per event type, plus a total labelled "all event types".
 Sales revenue and commission sum across types.
@@ -125,13 +127,13 @@ Other cross metrics:
 |---|---|---|
 | Field | `price` (+ `price_currency`) | Action Cost (sum of `Payout`) |
 | Timing | Fixed before the video | Grows with every sale, including after the video |
-| Currency | The deal's `price_currency` | The Impact account's currency |
+| Currency | USD, always | The Impact account's currency, shown in USD (2.3) |
 
 Source of truth for what the brand paid:
 
 | The creator was | Source of truth | Also shown |
 |---|---|---|
-| Booked through TL | Paid to TL, in its own currency | Commission, as its own figure |
+| Booked through TL | Paid to TL, in USD | Commission, as its own figure |
 | Booked through TL and outside TL | Paid to TL, for the TL videos | Impact payments outside the TL bookings, own line, labelled "outside TL bookings" |
 | Never booked through TL | Commission plus fixed payments through Impact (`Other_Cost`) | Nothing from TL |
 
@@ -149,6 +151,13 @@ value is 0 or blank: Impact clicks, approved actions, pending actions, conversio
 revenue, commission (approved only), TL views, Paid to TL, sponsorship CPM, actions per 1,000
 views, clicks per 1,000 views. No figure that adds commission to Paid to TL.
 
+**Promo-code sales are sales.** A sale made with a promo code counts like a link sale in every
+figure. In the table and opening summary, split approved actions by the recorded promo-code
+field, e.g. "40 (12 with promo code, 28 without promo code)". This is code usage, not attribution:
+a coded action can also have a winning click. Use "by promo code" / "by link" only when Impact
+supplies evidence of the crediting method; never infer link attribution from a blank code. IF
+the promo-code field is unavailable, say the split is unavailable rather than infer zero codes.
+
 **Package pricing** — a row whose deals are priced 0 — drops that row's sponsorship CPM and
 nothing else. Pending actions, clicks, views and both per-1,000-view columns stay, on that row
 and on every other.
@@ -166,7 +175,7 @@ it does not satisfy this.
 | Line | Definition |
 |---|---|
 | TL videos included | Every live sold TL deal for this brand and creator, across the creator's TL records in scope, to today |
-| Paid to TL | Sum of those prices, in the price currency |
+| Paid to TL | Sum of those prices, in USD |
 | Commission since the first TL video | Approved, first TL go-live to today, converted (2.3) |
 | Commission before the first TL video | Approved, from the partner's first action to the day before the first go-live. Own line, labelled "outside TL bookings". Not added to any all-in figure |
 | All-in cost | Paid to TL + commission since the first TL video |
@@ -189,23 +198,31 @@ it does not satisfy this.
 
 ### 2.3 Currency
 
+TL prices are always in USD, and the report is in USD. The ECB rate is for one case only: Impact
+figures in another currency, usually EUR.
+
 Every money heading names its currency, in every case, e.g. "Paid to TL (USD)", "Sales revenue,
-Impact (EUR)". A currency named once in the table's title covers that table. A money cell reading
-0 is still a money cell: "0" alone does not say which currency it is zero of, and a row that is
-otherwise empty — no commission before the first TL video, no sales in the period — is exactly
+Impact (USD; EUR original)". A currency named once in the table's title covers that table. A
+money cell reading 0 is still a money cell: "0" alone does not say which currency it is zero of,
+and a row that is otherwise empty — no commission before the first TL video, no sales in the period — is exactly
 where the heading is easiest to lose. Record the currency of the Impact figures from the report or
 export; reports have a display-currency setting, so say so when Impact has already converted them.
 
-- IF the Impact figures are in the TL `price_currency`: no conversion.
-- ELSE, when money is compared with money (everything in the all-in block): add a converted column
-  beside the original one, never in place of it. Money divided by a count or by views (sponsorship
-  CPM, sponsorship cost per action) is not converted.
-  - Convert the Impact figure into the price currency. Never convert the TL price.
-  - Rate: the ECB euro reference rate, averaged over the month of the Impact activity. Convert
-    each month at its own rate, then sum. Convert other currencies through the euro.
+- Never convert the TL price. IF a TL deal's `price_currency` is not USD, name the deal and its
+  currency to the user, since TL prices are expected in USD. Keep that price labelled in its
+  recorded currency and withhold every USD total or ratio that depends on it until its USD price
+  is confirmed. Never relabel it USD, mix it into a USD sum, or silently omit the deal from a total.
+- IF the Impact figures are in USD (the account's own currency, or a report whose display
+  currency is USD): no conversion.
+- ELSE (for example EUR): show every Impact money figure in USD, with the original beside it,
+  never in place of it, e.g. "Commission, Impact (USD 1,352; EUR 1,240)".
+  - Rate: the ECB euro reference rate for USD, averaged over the month of the Impact activity.
+    Convert each month at its own rate, then sum. A currency other than EUR goes through the
+    euro.
   - Look the rate up; never use one from memory. IF the month's average is not yet published,
     average that month's published daily rates and say so. IF no rate is found, show the original
-    currency only and say a rate is needed.
+    currency only and say a rate is needed. Withhold affected USD figures and calculations that
+    combine currencies until every required rate is available; never treat a missing rate as 1.
   - Show the rates used in the column name or a note.
 
 ## 3. Identity join
@@ -264,6 +281,9 @@ The creator's codes are the promo codes on the creator's own actions that contai
 (3.1). They are read from Impact's actions; TL holds no copy of them. Actions using them but
 credited to another partner go on their own line under the creator, "creator's code, credited to
 <partner>", with counts, sales revenue and commission, not added to the creator's totals.
+Under the creator's totals, add one line labelled "including the creator's code credited to other
+partners": approved actions and sales revenue with those actions added. The commission stays with
+the partner that was paid it. The headline totals stay as they are.
 
 ### 3.5 Coverage count
 
@@ -355,7 +375,7 @@ Impact partner totals are lifetime and hide decay. Never judge a creator on a li
 | Group | Definition | Shown |
 |---|---|---|
 | Booked through TL | TL channel with a sold deal for this brand | Scorecard or timeline, and the block |
-| Not booked through TL | TL channel, no sold deal for this brand | Impact performance; what the brand paid through Impact as the source of truth, in Impact's currency; cost per action = Impact payments ÷ approved actions; the TL channel's subscribers, projected views and bookability |
+| Not booked through TL | TL channel, no sold deal for this brand | Impact performance; what the brand paid through Impact as the source of truth, in USD (2.3); cost per action = Impact payments ÷ approved actions; the TL channel's subscribers, projected views and bookability |
 | Not a TL creator | No TL channel | Impact performance and Impact cost only |
 
 - For the last two groups, Paid to TL reads "not booked through TL", never 0. Invent no TL figure.
@@ -364,7 +384,7 @@ Impact partner totals are lifetime and hide decay. Never judge a creator on a li
   in range; syntax in the `tl` skill's Elasticsearch reference). List date, title and views, and
   ask which ones the brand paid for; accept pasted links instead. Use only confirmed videos.
   - CPM: Impact payments ÷ confirmed videos' TL views × 1,000, labelled "CPM on what you paid
-    through Impact", in Impact's currency.
+    through Impact", in USD (2.3).
   - Rebooking signal: each confirmed video's `projected_views` (frozen when TL first indexed it)
     against the channel document's current projection, as a percent change. The channel
     document's field is `impression`; a `projected_views` field on a channel document matches no
@@ -423,7 +443,7 @@ there; add no tenth to this block, and state no schema fact outside it.
 | `adlink.media_url` | The sponsored video's own link; destination links live in `urls`. Its video id is the fallback when `article_id` is null (1.4). |
 | `adlink.conversions` | Action count, hand-entered; set on few deals. |
 | `adlink.revenue` + `adlink.revenue_currency` | Sales revenue and its currency, hand-entered; set on few deals. Elsewhere in TL "revenue" means the sold price. |
-| `adlink.price_currency` | The currency of `price`. Never converted (2.3). |
+| `adlink.price_currency` | The currency of `price`: always USD. Never converted (2.3). |
 | `adlink.projected_views_at_purchase_date` | TL's projected views for the video, frozen at the purchase date. Never a source for CPM (2.2). |
 | `adspot.ad_format` | The ad spot's format code: 4 YouTube, 8 TikTok, 9 Instagram, other values other placements (newsletter, podcast, stream, X). Nullable, and absent from the restricted schema. Not a source for whether a deal has TL views — that is the video-index document (1.4). |
 | `channel.social_links` | JSON of the creator's links: platform keys (`instagram`, `tiktok`, …), an `_other` dict of the labelled links in the channel header, and an `_emails` array. ⚠️ Select named keys only. Never select the column wholesale: `_emails` is contact data and has no place in a performance report. |

{thoughtleaders_cli-0.9.18 → 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.18 → 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.18 → 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.18 → 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.18 → 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.18 → 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.18"
+__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.18 → 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.