tesseract-agent 0.11.37 → 0.11.38

package/dist-bundle/builtin-skills/build-mcp-server/scripts/mcp_check.py

@@ -174,7 +174,8 @@ class HttpConn:
 
     def _post(self, msg: dict, headers: dict | None, timeout: float) -> tuple[int, dict, bytes]:
         data = json.dumps(msg).encode("utf-8")
-        h = {"Content-Type": "application/json", "Accept": "application/json, text/event-stream", **self.auth_headers}
+        # Our own User-Agent: a server behind Cloudflare refuses Python's default ("Python-urllib", error 1010).
+        h = {"User-Agent": "tesseract-mcp-check/1.0", "Content-Type": "application/json", "Accept": "application/json, text/event-stream", **self.auth_headers}
         if self.session_id:
             h["Mcp-Session-Id"] = self.session_id
         h.update(headers or {})
@@ -232,7 +233,7 @@ class HttpConn:
     def close(self) -> None:
         if self.session_id:
             req = urllib.request.Request(self.url, method="DELETE",
-                                         headers={"Mcp-Session-Id": self.session_id, **self.auth_headers})
+                                         headers={"User-Agent": "tesseract-mcp-check/1.0", "Mcp-Session-Id": self.session_id, **self.auth_headers})
             try:
                 urllib.request.urlopen(req, timeout=5).close()
             except (urllib.error.URLError, OSError):

package/dist-bundle/builtin-skills/google-workspace/scripts/gws_setup.py

@@ -295,7 +295,8 @@ def cmd_install(args) -> int:
         print(f"already installed: {target}")
         return 0
     try:
-        with urllib.request.urlopen(RELEASES + name, timeout=120) as resp:
+        req = urllib.request.Request(RELEASES + name, headers={"User-Agent": "tesseract-google-workspace/1.0"})
+        with urllib.request.urlopen(req, timeout=120) as resp:
             data = resp.read()
     except (urllib.error.URLError, TimeoutError) as e:
         return fail(f"download failed: {e}")

package/dist-bundle/builtin-skills/local-models/scripts/lambda_cloud.py

@@ -47,7 +47,8 @@ def request(method: str, path: str, body: dict | None = None) -> dict:
         raise ApiError("LAMBDA_API_KEY is not set — ask for it with secret_request and run this with run_with_secrets")
     req = urllib.request.Request(API + path, method=method, data=json.dumps(body).encode() if body is not None else None,
                                  headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json",
-                                          "Accept": "application/json"})
+                                          # Lambda's API is behind Cloudflare, which refuses Python's default User-Agent (error 1010).
+                                          "Accept": "application/json", "User-Agent": "tesseract-local-models/1.0"})
     try:
         with urllib.request.urlopen(req, timeout=60) as r:  # noqa: S310 — Lambda's own API
             return json.loads(r.read().decode("utf-8") or "{}")

package/dist-bundle/builtin-skills/local-models/scripts/side_by_side.py

@@ -69,7 +69,7 @@ def payload(model: str, messages: list[dict], args: argparse.Namespace) -> dict:
 
 def post(url: str, body: dict, key: str | None, timeout: float) -> dict:
     req = urllib.request.Request(url, data=json.dumps(body).encode(), method="POST",
-                                 headers={"Content-Type": "application/json",
+                                 headers={"Content-Type": "application/json", "User-Agent": "tesseract-local-models/1.0",
                                           "Authorization": f"Bearer {key or 'local'}"})
     with urllib.request.urlopen(req, timeout=timeout) as r:  # noqa: S310 — the person's own endpoint
         return json.loads(r.read().decode("utf-8"))

package/dist-bundle/builtin-skills/social-posts/SKILL.md

@@ -48,6 +48,31 @@ manual and grows nobody.
 | YouTube Shorts | — | 1080×1920, ≤ 3 min | title ≤ 100, `#Shorts` | 3–5 a week |
 | Stories | `--size story` 1080×1920 | — | — | most days |
 
+## Hashtags
+
+Hashtags only sort a post into a topic; the words of the caption, the hook and how long people watch decide its
+reach. So: few, specific, in the post's own caption (never a first comment), and different from post to post.
+
+| Where | How many | Where they go |
+|---|---|---|
+| Instagram | 3–5 — five at most, Instagram refuses a sixth | end of the caption; the caption's own words carry the keywords people search |
+| Facebook Page | 1–3 | end of the caption |
+| LinkedIn Page | 1–3 | the last line |
+| TikTok | 3–5 | after a caption whose first sentence names the topic in plain words (TikTok searches captions) |
+| YouTube Short | `#Shorts` + 2 | the description's last line; the first three show above the title; over 15 and YouTube ignores them all |
+| YouTube video | 2–3 | the description's last line |
+| X | 0–2 | inline, only when they read naturally |
+
+- **Specific before broad.** Tag what THIS post is: the joke's own subject first (`#browsertabs`, `#scopecreep`,
+  `#rubberduckdebugging`), then the kind of humour or audience (`#officehumor`, `#devhumor`), then at most one category
+  tag (`#aiagents`, `#aitools`). Tags that only say "AI", "work" or "relatable" sink in feeds of millions — a post with
+  nothing else is under-tagged.
+- **Never the same set twice in a row.** Rotate by topic; pass the last posts' captions to `check_post.py --recent`.
+- **No dead tags**: `#fyp`, `#foryou`, `#viral`, `#explore`, `#trending`, `#like4like`, `#followforfollow` — no reach,
+  and they read as spam.
+- **A brand's own tag** only when nobody else uses it — look at the tag's page first (a product name is often taken).
+- channels.md may add the account's own rules (a tag never to use, a campaign tag).
+
 ## A picture post
 
 1. **The picture** — `generate_image`, 3:4 or 1:1: one striking, slightly surreal object that IS the joke, alone on a
@@ -58,8 +83,8 @@ manual and grows nobody.
 2. **The card** — `card.py post --image pic.png --head "47 tabs open." --sub "0 thoughts in my head." --mark logo.png
    --size ig [--theme dark] --out card.jpg`. `--width 0.8` when the picture crowds the headline.
 3. **Look at it** — `image_inspect` the card: the headline clear of the picture, nothing cut, the mark visible.
-4. **The words** — the caption carries a question people answer ("How many are open right now?"), then the hashtags;
-   `check_post.py --platform instagram --never "…"` until it passes.
+4. **The words** — the caption carries a question people answer ("How many are open right now?"), then the hashtags
+   (above); `check_post.py --platform instagram --never "…" --recent last-posts.txt` until it passes.
 
 The same picture makes the other sizes: `--size li` for LinkedIn, `--size story` for a story.
 
@@ -94,6 +119,9 @@ muted.
   into LinkedIn's and TikTok's own schedulers from their computer (LinkedIn's composer schedules up to three months
   ahead, TikTok Studio on the web ten days). When they say a batch is in, mark those lines "scheduled in LinkedIn" /
   "scheduled in TikTok" in calendar.md.
+- **TikTok, once connected** — the tiktok-account skill sends each finished video to the account's TikTok inbox as a
+  draft (after TikTok approves the app); the words and the AI label still go to them in the batch, since the draft
+  carries only the video.
 - **X** — the x-account skill.
 
 ## When they change the plan

package/dist-bundle/builtin-skills/social-posts/scripts/check_post.py

@@ -2,15 +2,19 @@
 """Check a post's words against the platform's rules and the account's own, before it goes out or into a scheduler.
 
     check_post.py --platform instagram|facebook|linkedin|tiktok|youtube|x [--file CAPTION.txt | -] [--never "Name,Other"]
+                  [--recent LAST_POSTS.txt] [--short]
 
 Reads the caption from --file or stdin. Prints one line per finding — FAIL (fix it first), WARN (worth a look),
 OK — and exits 1 on any FAIL.
 
 FAIL: a "made with AI" / "AI-generated" note in the words (the picture speaks for itself; a platform's own AI label is
 a setting, never text); a name the account must never show (--never); over the platform's length limit; Instagram
-over 5 hashtags. WARN: outside the length that does best (LinkedIn 900–1,300 characters); more hashtags than the
-platform rewards; a link where it is not clickable or costs reach (Instagram captions, LinkedIn's body — put it on
-the page's button or in a comment).
+over 5 hashtags; YouTube over 15 (it then ignores them all). WARN: outside the length that does best (LinkedIn
+900–1,300 characters); a hashtag count outside what the platform rewards (Instagram 3–5, Facebook 1–3, LinkedIn 1–3,
+TikTok 3–5, a YouTube Short #Shorts + 2, X 0–2) or none at all; only broad tags ("#ai", "#worklife", "#relatable"…)
+with nothing specific to the post; dead tags (#fyp, #viral, #explore…); the same set as one of the posts in --recent
+(a file of the last captions, one per paragraph); a link where it is not clickable or costs reach (Instagram captions,
+LinkedIn's body — put it on the page's button or in a comment).
 Standard library only (Python 3.9+; `python` on Windows).
 """
 from __future__ import annotations
@@ -20,7 +24,14 @@ import re
 import sys
 
 LIMITS = {"instagram": 2200, "facebook": 63206, "linkedin": 3000, "tiktok": 4000, "youtube": 5000, "x": 280}
-HASHTAGS_WARN = {"instagram": 5, "facebook": 3, "linkedin": 3, "tiktok": 5, "youtube": 3, "x": 2}
+# The count each platform rewards (min, max) — researched 2026-10; a Short is #Shorts + 2.
+HASHTAG_RANGE = {"instagram": (3, 5), "facebook": (1, 3), "linkedin": (1, 3), "tiktok": (3, 5), "youtube": (2, 3), "x": (0, 2)}
+# Tags so wide a post sinks in them; a post may carry one, never only these.
+BROAD = {"#ai", "#tech", "#technology", "#business", "#worklife", "#work", "#productivity", "#relatable", "#motivation",
+         "#love", "#instagood", "#photooftheday", "#funny", "#memes", "#life", "#success", "#marketing", "#innovation"}
+# No reach, and they read as spam.
+DEAD = {"#fyp", "#foryou", "#foryoupage", "#viral", "#explore", "#explorepage", "#trending", "#like4like", "#likeforlike",
+        "#followforfollow", "#follow4follow", "#f4f", "#l4l", "#followme"}
 
 AI_NOTE = re.compile(
     r"\((?:image|video|photo|picture|clip|art)?\s*(?:made|created|generated)\s+(?:with|by|using)\s+(?:ai|veo|midjourney|dall[- ·]?e|gpt[- ]?image)[^)]*\)"
@@ -33,7 +44,11 @@ URL = re.compile(r"\b(?:https?://|www\.)\S+|\b[a-z0-9-]+\.(?:com|dev|app|io|ai|n
 HASHTAG = re.compile(r"(?<![\w#])#\w+", re.UNICODE)
 
 
-def check(platform: str, text: str, never: list[str]) -> list[tuple[str, str]]:
+def tagset(text: str) -> frozenset:
+    return frozenset(t.lower() for t in HASHTAG.findall(text))
+
+
+def check(platform: str, text: str, never: list[str], recent: list[str] | None = None, short: bool = False) -> list[tuple[str, str]]:
     out: list[tuple[str, str]] = []
     n = len(text)
     m = AI_NOTE.search(text)
@@ -45,15 +60,32 @@ def check(platform: str, text: str, never: list[str]) -> list[tuple[str, str]]:
     if n > LIMITS[platform]:
         out.append(("FAIL", f"{n} characters — {platform} takes {LIMITS[platform]} at most"))
     tags = HASHTAG.findall(text)
+    low = [t.lower() for t in tags]
+    lo, hi = HASHTAG_RANGE[platform]
+    if platform == "youtube" and short:
+        lo, hi = 3, 3
+        if "#shorts" not in low:
+            out.append(("WARN", "a Short without #Shorts — keep it, with two tags about the video itself"))
     if platform == "instagram" and len(tags) > 5:
         out.append(("FAIL", f"{len(tags)} hashtags — Instagram takes 5 at most"))
-    elif len(tags) > HASHTAGS_WARN[platform]:
-        out.append(("WARN", f"{len(tags)} hashtags — {HASHTAGS_WARN[platform]} or fewer does better on {platform}"))
+    elif platform == "youtube" and len(tags) > 15:
+        out.append(("FAIL", f"{len(tags)} hashtags — over 15 and YouTube ignores every one"))
+    elif len(tags) > hi:
+        out.append(("WARN", f"{len(tags)} hashtags — {platform} rewards {lo}–{hi}"))
+    elif len(tags) < lo:
+        out.append(("WARN", f"{'no hashtag' if not tags else f'{len(tags)} hashtag(s)'} — {platform} does best with {lo}–{hi} specific ones"))
+    dead = [t for t in tags if t.lower() in DEAD]
+    if dead:
+        out.append(("WARN", f"{', '.join(dead)}: no reach, and reads as spam — tag what the post is about"))
+    topical = [t for t in low if t not in BROAD and t not in DEAD and t != "#shorts"]
+    if tags and not topical:
+        out.append(("WARN", "only broad tags — add the post's own subject first (what the joke or the topic is), then one category tag"))
+    mine = tagset(text)
+    if mine and any(mine == tagset(r) for r in (recent or [])):
+        out.append(("WARN", "the same hashtags as a recent post — rotate them by topic"))
     if platform == "linkedin":
         if n < 900 or n > 1300:
             out.append(("WARN", f"{n} characters — LinkedIn company posts of 900–1,300 do best"))
-        if not tags:
-            out.append(("WARN", "no hashtag — one to three specific ones help a little on LinkedIn"))
         if URL.search(text):
             out.append(("WARN", "a link in the body — LinkedIn shows link posts less; use the page's button or a first comment"))
     if platform == "instagram" and URL.search(text):
@@ -68,9 +100,12 @@ def main() -> None:
     ap.add_argument("--platform", required=True, choices=sorted(LIMITS))
     ap.add_argument("--file", default="-", help="the caption file, or - for stdin")
     ap.add_argument("--never", default="", help="comma-separated names the account must never show")
+    ap.add_argument("--recent", help="a file of the account's last captions, one per paragraph (blank line between)")
+    ap.add_argument("--short", action="store_true", help="a YouTube Short: #Shorts + 2")
     a = ap.parse_args()
     text = sys.stdin.read() if a.file == "-" else open(a.file, encoding="utf-8").read()
-    findings = check(a.platform, text.strip(), [s.strip() for s in a.never.split(",")])
+    recent = [p for p in open(a.recent, encoding="utf-8").read().split("\n\n") if p.strip()] if a.recent else []
+    findings = check(a.platform, text.strip(), [s.strip() for s in a.never.split(",")], recent, a.short)
     for level, msg in findings:
         print(f"{level:4}  {msg}")
     sys.exit(1 if any(level == "FAIL" for level, _ in findings) else 0)

package/dist-bundle/builtin-skills/tiktok-account/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: tiktok-account
+description: Send finished vertical videos to the person's own TikTok account through TikTok's official Content Posting API — each arrives in the account's TikTok inbox as a draft, which the person opens in TikTok, checks (caption, sound, the "AI-generated content" label) and posts — after connecting the account once with TikTok's Login Kit. Also shows which account is connected and where an upload is. Use to deliver a week's TikToks to the brand account, or to check the TikTok connection. Needs a TikTok developer app (client key and secret) the owner makes once; until TikTok approves it, only the app's sandbox or a private account can receive videos. Not for making the videos (social-posts, product-videos), scheduling a post for later (TikTok Studio on the web does that, ten days ahead), reading comments or numbers, ads, or driving tiktok.com in a browser.
+license: MIT
+version: 1.0.0
+metadata:
+  tesseract.summary: Send finished videos to your TikTok account as drafts, ready to post from the app.
+  tesseract.category: writing
+  tesseract.examples: "send this week's TikToks to our account | connect our TikTok account | is our TikTok still connected | envía estos vídeos a nuestra cuenta de TikTok como borradores | 把这三个视频发到我们抖音国际版账号的草稿箱"
+  tesseract.tools: secret_status, secret_request, run_with_secrets, job_start, job_output, probe_video, channels_send, memory_read, memory_write
+---
+
+# TikTok account
+
+Everything goes through `scripts/tiktok.py` (standard-library Python 3.9+, `python` on Windows) and TikTok's
+official APIs. It runs through `run_with_secrets` with `names: ["TIKTOK_CLIENT_KEY", "TIKTOK_CLIENT_SECRET"]` — the
+TikTok app's credentials, from developers.tiktok.com — so you never see them. It prints JSON; TikTok's own error
+(code, message, log_id) and what it means go to stderr.
+
+## Connecting, once
+
+1. `tiktok.py auth-url` prints the address to open. Send it to the person (Atrium, `channels_send`): they open it,
+   sign in to the brand account and allow it.
+2. TikTok sends them to `https://tesseract.dev/oauth/tiktok`, which shows one line — a code and a state. They paste
+   it back; run `tiktok.py connect "<the line>"`. The refresh token is kept in a 0600 file (`--state`, by default
+   `~/.tesseract/skills-data/tiktok/token.json`) and lasts a year; say so, and put a reminder in your calendar a
+   week before it ends.
+3. `tiktok.py whoami` — check it is the right account before anything is sent.
+
+## Sending a video
+
+- A finished 9:16 MP4 (1080×1920, under 10 minutes; `probe_video` it first). `tiktok.py upload video.mp4 --wait`: the
+  video goes to the account's TikTok inbox as a draft; `--wait` follows it until TikTok says it is there
+  (`SEND_TO_USER_INBOX`). A long upload is a `job_start` job.
+- Then tell them in one message: which video, its caption (from the batch — the API does not carry the words), whether
+  to turn on "AI-generated content" (a realistic AI video needs it), the time it was planned for, and that it waits in
+  their TikTok inbox. At most five drafts can wait at once — space them, or ask them to post the earlier ones.
+- Until TikTok approves the app, only the sandbox's target accounts (or a private account) receive videos — an
+  "unaudited" error says so. Then hand the video over in Atrium instead, as social-posts' LinkedIn and TikTok batch.
+
+## Never
+
+Post to anyone else's account, download other people's videos, or keep the access token anywhere but the state
+file. A refresh that hands out a new refresh token replaces the old one there — keep only the newest.

package/dist-bundle/builtin-skills/tiktok-account/scripts/tiktok.py

@@ -0,0 +1,247 @@
+#!/usr/bin/env python3
+"""The person's own TikTok account through TikTok's official APIs: connect it once (Login Kit for Web), see which
+account is connected, and send a finished video to its inbox as a draft (Content Posting API, video.upload) — the
+person opens TikTok, checks it and posts it.
+
+    tiktok.py auth-url [--redirect URI] [--scopes user.info.basic,video.upload]   the address to open, to connect
+    tiktok.py connect "CODE STATE"            the line the redirect page shows → the refresh token, kept in --state
+    tiktok.py whoami                          the connected account (open id, display name, avatar)
+    tiktok.py upload VIDEO.mp4 [--wait]       a draft in the account's TikTok inbox; --wait follows it until it lands
+    tiktok.py status PUBLISH_ID               where an upload is
+
+Needs TIKTOK_CLIENT_KEY and TIKTOK_CLIENT_SECRET (the app's, from developers.tiktok.com) — run it through
+run_with_secrets. The refresh token lives in a 0600 state file (--state, default ~/.tesseract/skills-data/tiktok/
+token.json): TikTok may hand out a new one on each refresh, and the newest must be kept. A refresh token lasts a year;
+an access token a day, made fresh for every call. Standard library only (Python 3.9+; `python` on Windows). Prints
+JSON; TikTok's own error (code, message, log_id) goes to stderr with what it means.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import secrets
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+AUTH = os.environ.get("TIKTOK_AUTH_URL", "https://www.tiktok.com/v2/auth/authorize/")
+OPEN = os.environ.get("TIKTOK_OPEN_API", "https://open.tiktokapis.com")
+REDIRECT = "https://tesseract.dev/oauth/tiktok"
+DEFAULT_STATE = Path.home() / ".tesseract" / "skills-data" / "tiktok" / "token.json"
+MIN_CHUNK = 5 * 1024 * 1024
+MAX_CHUNK = 64 * 1024 * 1024
+
+HINTS = {
+    "access_token_invalid": "The connection expired or was revoked: connect again (auth-url, then connect).",
+    "scope_not_authorized": "The account did not grant this scope: connect again and allow it.",
+    "spam_risk_too_many_pending_share": "Five drafts already wait in the account's inbox: post or delete some in TikTok first.",
+    "spam_risk_too_many_posts": "The account posted its daily limit through apps: try again tomorrow.",
+    "rate_limit_exceeded": "Too many requests: wait a minute and try again.",
+    "url_ownership_unverified": "The redirect or media URL's domain is not verified on the TikTok app.",
+    "unaudited_client_can_only_post_to_private_accounts": "The app is not approved by TikTok yet: until it is, only a private account (or the sandbox) can receive posts.",
+}
+
+
+def die(msg: str, code: int = 1) -> None:
+    print(msg, file=sys.stderr)
+    sys.exit(code)
+
+
+def need(name: str) -> str:
+    v = os.environ.get(name, "").strip()
+    if not v:
+        die(f"{name} is not set — run this through run_with_secrets with names [\"{name}\"].", 2)
+    return v
+
+
+def state_path(a) -> Path:
+    return Path(a.state).expanduser() if a.state else DEFAULT_STATE
+
+
+def save_state(p: Path, data: dict) -> None:
+    p.parent.mkdir(parents=True, exist_ok=True)
+    tmp = p.with_suffix(".tmp")
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w") as f:
+        json.dump(data, f)
+    os.replace(tmp, p)
+
+
+def load_state(p: Path) -> dict:
+    try:
+        return json.loads(p.read_text())
+    except (OSError, ValueError):
+        return {}
+
+
+def request(method: str, url: str, *, form: dict | None = None, body: dict | None = None, token: str | None = None,
+            data: bytes | None = None, headers: dict | None = None) -> dict:
+    h = {"User-Agent": "tesseract-tiktok-account/1.0", **(headers or {})}  # never Python's default, which Cloudflare refuses
+    payload = data
+    if form is not None:
+        payload = urllib.parse.urlencode(form).encode()
+        h["Content-Type"] = "application/x-www-form-urlencoded"
+    elif body is not None:
+        payload = json.dumps(body).encode()
+        h["Content-Type"] = "application/json; charset=UTF-8"
+    if token:
+        h["Authorization"] = f"Bearer {token}"
+    req = urllib.request.Request(url, data=payload, method=method, headers=h)
+    try:
+        with urllib.request.urlopen(req, timeout=300) as r:
+            raw = r.read()
+    except urllib.error.HTTPError as e:
+        raw = e.read()
+        try:
+            j = json.loads(raw or b"{}")
+        except ValueError:
+            die(f"TikTok answered {e.code}: {raw[:300]!r}")
+        fail(j, e.code)
+    try:
+        j = json.loads(raw) if raw else {}
+    except ValueError:
+        j = {}
+    if not isinstance(j, dict):  # a chunk PUT answers 201 with an empty body or a bare `null`
+        return {}
+    err = j.get("error")
+    if isinstance(err, dict) and err.get("code") not in (None, "ok"):
+        fail(j, 200)
+    if isinstance(err, str) and err:  # the OAuth endpoint's own shape
+        fail(j, 200)
+    return j
+
+
+def fail(j: dict, status: int) -> None:
+    err = j.get("error")
+    if isinstance(err, dict):
+        code, msg, log = err.get("code"), err.get("message"), err.get("log_id")
+    else:
+        code, msg, log = err, j.get("error_description"), j.get("log_id")
+    print(json.dumps({"status": status, "code": code, "message": msg, "log_id": log}), file=sys.stderr)
+    if code in HINTS:
+        print(HINTS[code], file=sys.stderr)
+    sys.exit(1)
+
+
+def access_token(a) -> str:
+    """A fresh access token from the kept refresh token; keeps the new refresh token when TikTok rotates it."""
+    p = state_path(a)
+    st = load_state(p)
+    refresh = st.get("refresh_token") or os.environ.get("TIKTOK_REFRESH_TOKEN", "").strip()
+    if not refresh:
+        die("Not connected yet: run auth-url, open it, then connect with the line the page shows.", 2)
+    j = request("POST", f"{OPEN}/v2/oauth/token/", form={
+        "client_key": need("TIKTOK_CLIENT_KEY"), "client_secret": need("TIKTOK_CLIENT_SECRET"),
+        "grant_type": "refresh_token", "refresh_token": refresh,
+    })
+    if j.get("refresh_token") and j["refresh_token"] != refresh:
+        st.update({"refresh_token": j["refresh_token"], "refreshed_at": int(time.time())})
+        save_state(p, st)
+    return j["access_token"]
+
+
+def cmd_auth_url(a) -> None:
+    st_path = state_path(a)
+    st = load_state(st_path)
+    state = secrets.token_urlsafe(16)
+    st.update({"pending_state": state, "redirect_uri": a.redirect})
+    save_state(st_path, st)
+    q = urllib.parse.urlencode({"client_key": need("TIKTOK_CLIENT_KEY"), "scope": a.scopes, "response_type": "code",
+                                "redirect_uri": a.redirect, "state": state, "disable_auto_auth": 1})
+    print(json.dumps({"url": f"{AUTH}?{q}", "then": "open it, allow, and give the line the page shows to: tiktok.py connect \"CODE STATE\""}))
+
+
+def cmd_connect(a) -> None:
+    parts = a.line.split()
+    code = urllib.parse.unquote(parts[0]) if parts else ""
+    p = state_path(a)
+    st = load_state(p)
+    if not code:
+        die("Give the line the page shows: the code, then the state.", 2)
+    if len(parts) > 1 and st.get("pending_state") and parts[1] != st["pending_state"]:
+        die("That code was not asked for by this connection (the state does not match): start again with auth-url.", 2)
+    j = request("POST", f"{OPEN}/v2/oauth/token/", form={
+        "client_key": need("TIKTOK_CLIENT_KEY"), "client_secret": need("TIKTOK_CLIENT_SECRET"), "code": code,
+        "grant_type": "authorization_code", "redirect_uri": st.get("redirect_uri") or REDIRECT,
+    })
+    st.pop("pending_state", None)
+    st.update({"refresh_token": j["refresh_token"], "open_id": j.get("open_id"), "scope": j.get("scope"),
+               "refresh_expires_in": j.get("refresh_expires_in"), "connected_at": int(time.time())})
+    save_state(p, st)
+    print(json.dumps({"connected": True, "open_id": j.get("open_id"), "scope": j.get("scope"), "state_file": str(p)}))
+
+
+def cmd_whoami(a) -> None:
+    j = request("GET", f"{OPEN}/v2/user/info/?fields=open_id,display_name,avatar_url", token=access_token(a))
+    print(json.dumps(j.get("data", {}).get("user", {})))
+
+
+def cmd_upload(a) -> None:
+    path = Path(a.video)
+    if not path.exists():
+        die(f"{path}: no such file.", 2)
+    size = path.stat().st_size
+    if size > 4 * 1024 ** 3:
+        die("TikTok takes videos up to 4 GB.", 3)
+    # Under 64 MB: one chunk, the whole file. Larger: 10 MB chunks, the remainder joining the last one.
+    chunk = size if size <= MAX_CHUNK else 10 * 1024 * 1024
+    count = max(1, size // chunk)
+    mime = {".mp4": "video/mp4", ".mov": "video/quicktime", ".webm": "video/webm"}.get(path.suffix.lower())
+    if not mime:
+        die("Send an MP4, MOV or WebM.", 3)
+    token = access_token(a)
+    init = request("POST", f"{OPEN}/v2/post/publish/inbox/video/init/", token=token, body={
+        "source_info": {"source": "FILE_UPLOAD", "video_size": size, "chunk_size": chunk, "total_chunk_count": count}})
+    data = init["data"]
+    url, publish_id = data["upload_url"], data["publish_id"]
+    with path.open("rb") as f:
+        for i in range(count):
+            start = i * chunk
+            end = size - 1 if i == count - 1 else start + chunk - 1
+            f.seek(start)
+            part = f.read(end - start + 1)
+            request("PUT", url, data=part, headers={"Content-Type": mime, "Content-Length": str(len(part)),
+                                                    "Content-Range": f"bytes {start}-{end}/{size}"})
+    out = {"publish_id": publish_id, "bytes": size, "chunks": count}
+    if a.wait:
+        out["status"] = follow(token, publish_id)
+    print(json.dumps(out))
+
+
+def status_of(token: str, publish_id: str) -> dict:
+    return request("POST", f"{OPEN}/v2/post/publish/status/fetch/", token=token, body={"publish_id": publish_id}).get("data", {})
+
+
+def follow(token: str, publish_id: str) -> dict:
+    last = {}
+    for _ in range(60):
+        last = status_of(token, publish_id)
+        if last.get("status") in ("SEND_TO_USER_INBOX", "PUBLISH_COMPLETE", "FAILED"):
+            break
+        time.sleep(5)
+    return last
+
+
+def cmd_status(a) -> None:
+    print(json.dumps(status_of(access_token(a), a.publish_id)))
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="The person's own TikTok account, through TikTok's APIs.")
+    ap.add_argument("--state", help="the 0600 file that keeps the refresh token")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    p = sub.add_parser("auth-url"); p.add_argument("--redirect", default=REDIRECT); p.add_argument("--scopes", default="user.info.basic,video.upload")
+    p = sub.add_parser("connect"); p.add_argument("line")
+    sub.add_parser("whoami")
+    p = sub.add_parser("upload"); p.add_argument("video"); p.add_argument("--wait", action="store_true")
+    p = sub.add_parser("status"); p.add_argument("publish_id")
+    a = ap.parse_args()
+    {"auth-url": cmd_auth_url, "connect": cmd_connect, "whoami": cmd_whoami, "upload": cmd_upload, "status": cmd_status}[a.cmd](a)
+
+
+if __name__ == "__main__":
+    main()

package/dist-bundle/builtin-skills/tracked-links/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: tracked-links
+description: Give every link to the product's own site that goes out — in a bio or about section, a post, a reply, a message, a video's description, an email — its own short tag (`?utm_source=ab63az`), registered with where it is published and why, so each placement's visits, downloads and new accounts are counted on their own; then read which links, platforms and other sites bring people. Use before publishing anything that links to the site, after it is posted (to record where), and when asked what is working. Needs the product's marketing key (Tesseract's blog key). Not for shortening links, links to other people's sites, ad campaigns' own tracking, or reading a platform's own statistics (youtube-channel, facebook-instagram, x-account do that).
+license: MIT
+version: 1.0.0
+metadata:
+  tesseract.summary: Tag every link you publish, and see which ones bring visits, downloads and sign-ups.
+  tesseract.category: writing
+  tesseract.examples: "tag the link for our Instagram bio | which of our posts brought the most sign-ups this month | make a tracked link for this Reddit reply | ¿qué enlaces nos trajeron más visitas esta semana? | 给我们的 YouTube 简介链接加一个追踪标签"
+  tesseract.tools: secret_status, secret_request, run_with_secrets, channels_send, memory_read, memory_write
+---
+
+# Tracked links
+
+Everything goes through `scripts/links.py` (standard-library Python 3.9+, `python` on Windows). It runs through
+`run_with_secrets` with `names: ["BLOG_API_KEY"]` — the marketing key — so you never see it. The API is the product's
+own (`LINKS_API_URL`, or the blog API's `…/marketing` sibling when only `BLOG_API_URL` is set). It prints JSON; the
+API's own message goes to stderr.
+
+## The rule
+
+**Every link to the product's site that you publish carries its own tag — one tag per place, never reused.** A bio,
+an about section, a pinned post, each post, each reply, each message, each video description: each gets a new one.
+Links to other sites carry none.
+
+## Before publishing
+
+`links.py new --comment "<where and why, in a few words>" --channel <platform> [--target <page>]`
+
+- `--comment`: what a person reading the report needs — "instagram bio url", "reddit reply in r/LocalLLaMA about
+  local agents", "youtube short 'Browser tabs' description".
+- `--channel`: instagram, facebook, youtube, tiktok, linkedin, x, reddit, hn, github, email, newsletter, other.
+- `--target`: the page it opens (the home page by default; a blog post's own address when the post links to it).
+
+Publish the `link` it prints, exactly. `links.py link URL TAG` adds a tag to another address without asking the API.
+
+## After publishing
+
+Once the post, reply or profile has its own address: `links.py set TAG --url <that address>`. A link whose place has
+no address of its own (a bio field) gets the profile's address. If something was never posted, `links.py delete TAG`.
+
+Where a platform shows no link in a post (TikTok, Instagram captions), the tag goes in the bio's website field, and
+the post says "link in bio".
+
+## Reading what works
+
+`links.py report --days 30`: totals and the span before, by platform (`channels`), by link (`sources`: each of our tags
+with its comment and address, and every other site), downloads by kind, sign-ups by method, countries, systems,
+pages. When asked what is working — or in a weekly summary — say it plainly: which placements brought visits,
+downloads and accounts, which brought nothing, and what to do more or less of. `links.py list --channel reddit` and
+`links.py get TAG` show one tag's numbers.
+
+## Never
+
+Put a tag on a link to someone else's site, reuse a tag in a second place, or invent numbers when the report says
+`configured: false` (nothing is being counted — say so).