@acedatacloud/skills 2026.703.16 → 2026.704.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acedatacloud/skills",
-  "version": "2026.703.16",
+  "version": "2026.704.1",
   "description": "Agent Skills for AceDataCloud AI services — music, image, video generation, LLM chat, web search. Compatible with Claude Code, GitHub Copilot, Gemini CLI, OpenAI Codex, and 30+ AI coding agents.",
   "keywords": [
     "agent-skills",

package/skills/bluesky/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bluesky
-description: Publish, delete and read your own posts on Bluesky via the AT Protocol (XRPC). Use when the user wants to post to their Bluesky account, cross-post an article as a short dev-focused post, delete a post, or list their own recent posts with engagement stats (reposts, likes, replies). Auth uses the user's handle plus an App Password.
+description: Publish (with optional images), delete and read your own posts on Bluesky via the AT Protocol (XRPC). Use when the user wants to post to their Bluesky account (text or 带图 / with a picture), cross-post an article as a short dev-focused post, attach an image, delete a post, or list their own recent posts with engagement stats (reposts, likes, replies). Auth uses the user's handle plus an App Password.
 when_to_use: |
   Trigger when the user wants to publish a post to their Bluesky account,
   delete one, or review their own recent posts and engagement. Bluesky runs on
@@ -12,152 +12,103 @@ allowed_tools: [Bash]
 license: Apache-2.0
 metadata:
   author: acedatacloud
-  version: "1.0"
+  version: "1.1"
 ---
 
-Call the **Bluesky AT Protocol** XRPC endpoints with `curl + jq`. Three
-connector credentials are injected: `$BLUESKY_HANDLE` (e.g. `name.bsky.social`),
-`$BLUESKY_APP_PASSWORD` (an App Password created in Bluesky **Settings →
-Privacy and Security → App Passwords**, NOT the account login password) and
-`$BLUESKY_SERVICE` (the PDS base URL, default `https://bsky.social`).
-
-Errors come back as JSON `{"error":"<name>","message":"<detail>"}` — show it
-verbatim. A `401 {"error":"AuthenticationRequired","message":"Invalid identifier
-or password"}` on session creation means the identifier or App Password is
-wrong/revoked. The **#1 cause is a bare handle**: the identifier must be the
-FULL handle (`alice.bsky.social`), a DID, or the account email — a bare
-`alice` will NOT resolve. Step 1 auto-appends `.bsky.social` to a bare handle
-on the default PDS; if it still fails, the user must re-connect the Bluesky
-connector with the full handle (or generate a fresh App Password).
-
-## Step 1 — always create a session first
-
-Everything needs a short-lived `accessJwt` and your account `did`. Do this once
-per task and reuse the values. The identifier must be a full handle, DID or
-email — normalize a bare username (no `.` / `@`) to `<name>.bsky.social` when
-using the default PDS, otherwise `createSession` returns `AuthenticationRequired`:
-
-```bash
-SVC="${BLUESKY_SERVICE:-https://bsky.social}"
-ID="$BLUESKY_HANDLE"
-# Bare username → full handle on the default bsky.social PDS. A dotted handle
-# (custom domain), a DID (`did:...`) or an email are already valid — leave them.
-case "$ID" in
-  *.* | *@* | did:*) : ;;
-  *) [ "$SVC" = "https://bsky.social" ] && ID="$ID.bsky.social" ;;
-esac
-SESSION=$(curl -sS -X POST "$SVC/xrpc/com.atproto.server.createSession" \
-  -H "Content-Type: application/json" \
-  -d "$(jq -n --arg id "$ID" --arg pw "$BLUESKY_APP_PASSWORD" \
-        '{identifier:$id, password:$pw}')")
-echo "$SESSION" | jq '{did, handle, active}'
-JWT=$(echo "$SESSION" | jq -r .accessJwt)
-DID=$(echo "$SESSION" | jq -r .did)
+Everything runs through the shipped CLI [`scripts/bluesky.py`](scripts/bluesky.py)
+— self-contained (`requests` + `Pillow`, both preinstalled in the sandbox). One
+call creates the session, auto-computes clickable **facets** (links, #hashtags,
+@mentions with correct UTF-8 byte offsets), and for image posts downloads the
+file, **resizes/recompresses it to Bluesky's ~1 MB blob limit**, `uploadBlob`s it
+and builds the `app.bsky.embed.images` embed — so there's no fragile
+`curl + jq + heredoc` to hand-assemble (the old inline recipe kept breaking on
+shell quoting, especially once an image + facets were involved).
+
+Three connector credentials are injected: `$BLUESKY_HANDLE`
+(e.g. `name.bsky.social`), `$BLUESKY_APP_PASSWORD` (an App Password from Bluesky
+**Settings → Privacy and Security → App Passwords**, NOT the login password) and
+`$BLUESKY_SERVICE` (PDS base URL, default `https://bsky.social`). The CLI reads
+them from the env — never echo them.
+
+```sh
+BSKY="$SKILL_DIR/scripts/bluesky.py"
+python3 "$BSKY" whoami          # verify the session → {did, handle, service}
 ```
 
-If `JWT` / `DID` are empty or `null`, print the raw `$SESSION` (it contains the
-error) and stop — do not continue to post. On `AuthenticationRequired`, tell the
-user to reconnect the connector using their **full** handle (e.g.
-`name.bsky.social`, not `name`) and a valid App Password.
-
-## Post to Bluesky
-
-**Confirm the text with the user before posting.** Text is limited to **300
-graphemes**; longer text → `400 {"error":"InvalidRequest"}`. `createdAt` must be
-an ISO-8601 UTC timestamp.
-
-```bash
-TEXT="Hello Bluesky 👋 shipping with the AT Protocol"
-NOW=$(date -u +%Y-%m-%dT%H:%M:%S.000Z)
-curl -sS -X POST "$SVC/xrpc/com.atproto.repo.createRecord" \
-  -H "Authorization: Bearer $JWT" \
-  -H "Content-Type: application/json" \
-  -d "$(jq -n --arg did "$DID" --arg text "$TEXT" --arg now "$NOW" \
-        '{repo:$did, collection:"app.bsky.feed.post",
-          record:{ "$type":"app.bsky.feed.post", text:$text, createdAt:$now, langs:["en"] }}')" \
-  | jq '{uri, cid}'
+If `whoami` fails with `session_failed` / `AuthenticationRequired`, the
+identifier or App Password is wrong. The **#1 cause is a bare handle** — the CLI
+auto-appends `.bsky.social` to a bare username on the default PDS, but if it
+still fails the user must reconnect the connector with their **full** handle
+(`name.bsky.social`, a custom domain, a DID, or the account email) and a valid
+App Password.
+
+## Post — text, images and links in one call
+
+**Confirm the text with the user before posting** (it publishes as their real
+account). Text ≤ **300 graphemes**. Clickable links / #hashtags / @mentions are
+turned into facets automatically — just write them in the text, no byte-offset
+math needed.
+
+```sh
+# plain text post
+python3 "$BSKY" post --text "Hello Bluesky 👋 shipping with the AT Protocol"
+
+# 带图发送 / post WITH an image (URL or local path) — the image is downloaded,
+# resized to fit the blob limit, uploaded and embedded automatically:
+python3 "$BSKY" post \
+  --text "Stop wiring 3 image APIs. One endpoint → posters, cards, mockups. https://platform.acedata.cloud/documents/openai-images-generations-integration #AI #API" \
+  --image "https://cdn.acedata.cloud/xxxx.png" --alt "AI image API hero"
+
+# up to 4 images, each with its own --alt (paired by order)
+python3 "$BSKY" post --text "gallery" --image a.png --alt "one" --image b.png --alt "two"
 ```
 
-The returned `uri` looks like `at://did:plc:xxxx/app.bsky.feed.post/<rkey>`. The
-public web URL is `https://bsky.app/profile/$ID/post/<rkey>` where `$ID` is the
-normalized handle from Step 1 (or use the `did`) and `<rkey>` is the last path
-segment of the `uri`.
-
-### Clickable links, mentions and hashtags (facets)
-
-Plain URLs/hashtags in `text` are shown but **not clickable** — Bluesky needs
-`facets` with UTF-8 **byte** offsets. Add a hashtag link like this (byteStart/
-byteEnd are byte indices into the UTF-8 text, not character indices):
-
-```bash
-# text = "New post about #ai" — "#ai" starts at byte 15, ends at byte 18
-curl -sS -X POST "$SVC/xrpc/com.atproto.repo.createRecord" \
-  -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \
-  -d "$(jq -n --arg did "$DID" --arg now "$NOW" '
-    {repo:$did, collection:"app.bsky.feed.post",
-     record:{ "$type":"app.bsky.feed.post", text:"New post about #ai", createdAt:$now,
-       facets:[ { index:{byteStart:15, byteEnd:18},
-                  features:[{ "$type":"app.bsky.richtext.facet#tag", tag:"ai" }] } ] }}')" \
-  | jq '{uri, cid}'
+Multi-line text or lots of emoji? Skip shell-quoting headaches by writing the
+text to a file and using `--text-file` (or pipe via `--text -`):
+
+```sh
+cat > /tmp/post.txt <<'EOF'
+Line one 🎨
+
+Line two with a link https://platform.acedata.cloud #AI
+EOF
+python3 "$BSKY" post --text-file /tmp/post.txt --image "https://cdn.acedata.cloud/xxxx.png"
 ```
 
-For a link, use feature `app.bsky.richtext.facet#link` with a `uri` field; for a
-mention, `app.bsky.richtext.facet#mention` with a `did`. Compute byte offsets
-with e.g. `printf '%s' "$prefix" | wc -c`.
+Success prints
+`{"posted":true,"uri":"at://…","url":"https://bsky.app/profile/<handle>/post/<rkey>", ...}`.
+The `url` is the public, shareable link — hand it to the user verbatim.
 
 ## List my recent posts + engagement
 
-```bash
-curl -sS "$SVC/xrpc/app.bsky.feed.getAuthorFeed?actor=$DID&limit=20&filter=posts_no_replies" \
-  -H "Authorization: Bearer $JWT" \
-  | jq '.feed[] | {uri: .post.uri,
-                   text: .post.record.text,
-                   reposts: .post.repostCount,
-                   likes: .post.likeCount,
-                   replies: .post.replyCount,
-                   at: .post.indexedAt}'
+```sh
+python3 "$BSKY" list --limit 20                    # default filter: posts_no_replies
+python3 "$BSKY" list --limit 50 --filter posts_with_media
 ```
 
-`limit` max 100. `filter` options: `posts_with_replies`, `posts_no_replies`,
-`posts_with_media`, `posts_and_author_threads`.
+`--filter`: `posts_no_replies` | `posts_with_replies` | `posts_with_media` |
+`posts_and_author_threads`. `--limit` max 100.
 
 ## Delete a post
 
-`deleteRecord` needs the `rkey` (the last path segment of the post `uri`):
-
-```bash
-POST_URI="at://$DID/app.bsky.feed.post/3kabc123xyz"
-RKEY="${POST_URI##*/}"
-curl -sS -X POST "$SVC/xrpc/com.atproto.repo.deleteRecord" \
-  -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \
-  -d "$(jq -n --arg did "$DID" --arg rkey "$RKEY" \
-        '{repo:$did, collection:"app.bsky.feed.post", rkey:$rkey}')" \
-  | jq '{deleted: true, rkey: "'"$RKEY"'"}'
+```sh
+python3 "$BSKY" delete --uri "at://did:plc:xxxx/app.bsky.feed.post/3kabc123xyz"
 ```
 
-An empty `{}` response is success. `400 {"error":"InvalidRequest"}` usually
-means the record is already gone or the `rkey` is wrong.
-
-## Attaching images (optional)
-
-Upload each image via `POST $SVC/xrpc/com.atproto.repo.uploadBlob`
-(`Content-Type: image/jpeg`, raw bytes body, Bearer `$JWT`) → returns a `blob`
-object. Then set `record.embed` to
-`{ "$type":"app.bsky.embed.images", images:[{ alt:"<desc>", image:<blob> }] }`.
-Max 4 images per post; each blob ≲ 1 MB (resize/compress first).
+Pass the full `at://…` post `uri` (from `list` or a prior `post`); the CLI
+extracts the `rkey`. An empty result / `deleted:true` is success.
 
 ## Gotchas
 
 - **App Password, not account password:** creating a session with the real
   login password may be rejected or trip 2FA. Always the App Password from
   Settings → App Passwords.
-- **Byte offsets, not char offsets:** facet `byteStart`/`byteEnd` are UTF-8
-  byte indices — emoji and CJK take multiple bytes. Get them wrong and the
-  link highlights the wrong span.
+- **Facets & image resizing are automatic** — the CLI computes link/#tag/@mention
+  byte offsets and shrinks oversized images to the ~1 MB blob limit for you.
 - **300 graphemes**, counted as user-perceived characters (emoji = 1).
 - **Rate limits:** the PDS rate-limits writes per account; space out bulk posts
   or you'll get `429 {"error":"RateLimitExceeded"}`.
 - **Self-hosted PDS:** if the user runs their own PDS, `$BLUESKY_SERVICE` points
   there; all XRPC calls target that host, not `bsky.social`.
-- The `accessJwt` is short-lived (~2h). For a single task it's fine; if it
-  expires mid-task, just re-run Step 1.
+- The CLI creates a fresh short-lived session on **every** invocation, so an
+  expiring `accessJwt` is never a concern — just run the command again.

package/skills/bluesky/scripts/bluesky.py

@@ -0,0 +1,345 @@
+#!/usr/bin/env python3
+"""Bluesky (AT Protocol / XRPC) CLI shipped with the `bluesky` skill.
+
+Deps: `requests` + `Pillow` (both preinstalled in the sandbox). One command does
+the whole publish flow that previously had to be hand-assembled from curl + jq +
+python heredocs (and kept breaking on shell quoting):
+
+- create a session (handle normalized to a full handle on the default PDS)
+- auto-compute richtext `facets` (clickable links, #hashtags, @mentions) with
+  correct UTF-8 byte offsets
+- attach images: download the URL/path, resize/recompress to Bluesky's ~1 MB
+  blob limit, `uploadBlob`, and build the `app.bsky.embed.images` embed
+- `createRecord`, then print the public post URL
+
+Secrets ($BLUESKY_APP_PASSWORD) are read from the env and never printed.
+"""
+
+import argparse
+import io
+import json
+import os
+import re
+import sys
+from datetime import datetime, timezone
+
+import requests
+from PIL import Image
+
+# bsky.social's uploadBlob rejects images over ~1 MB; stay safely under it.
+BLOB_LIMIT = 976_560
+URL_RE = re.compile(r"https?://[^\s\]\)]+")
+TAG_RE = re.compile(r"(?<!\w)#([A-Za-z0-9_]+)")
+# A mention target must be a dotted handle (name.bsky.social / custom domain);
+# each dot-separated segment is non-empty so a trailing sentence dot isn't eaten.
+MENTION_RE = re.compile(r"(?<!\w)@([A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)+)")
+
+
+def out(o):
+    print(json.dumps(o, ensure_ascii=False))
+
+
+def die(o):
+    out(o)
+    sys.exit(1)
+
+
+def env_service():
+    return os.environ.get("BLUESKY_SERVICE", "https://bsky.social").rstrip("/")
+
+
+def normalize_identifier(handle, svc):
+    # A dotted handle, an email or a DID is already valid; a bare username needs
+    # `.bsky.social` on the default PDS or createSession returns AuthRequired.
+    if any(c in handle for c in ".@") or handle.startswith("did:"):
+        return handle
+    if svc == "https://bsky.social":
+        return f"{handle}.bsky.social"
+    return handle
+
+
+def create_session(svc):
+    handle = os.environ["BLUESKY_HANDLE"]
+    pw = os.environ["BLUESKY_APP_PASSWORD"]
+    ident = normalize_identifier(handle, svc)
+    try:
+        r = requests.post(
+            f"{svc}/xrpc/com.atproto.server.createSession",
+            json={"identifier": ident, "password": pw},
+            timeout=30,
+        )
+    except requests.RequestException as e:
+        die({"error": "session_request_failed", "detail": str(e)})
+    data = r.json() if r.content else {}
+    if r.status_code != 200 or not data.get("accessJwt"):
+        die({
+            "error": "session_failed",
+            "status": r.status_code,
+            "detail": data,
+            "hint": "reconnect the Bluesky connector with your FULL handle "
+                    "(e.g. name.bsky.social) and a valid App Password",
+        })
+    return data["accessJwt"], data["did"], ident
+
+
+def byte_index(text, char_index):
+    return len(text[:char_index].encode("utf-8"))
+
+
+def resolve_handle(svc, handle):
+    try:
+        r = requests.get(
+            f"{svc}/xrpc/com.atproto.identity.resolveHandle",
+            params={"handle": handle},
+            timeout=15,
+        )
+        if r.status_code == 200:
+            return r.json().get("did")
+    except requests.RequestException:
+        pass
+    return None
+
+
+def build_facets(text, svc):
+    """Compute link / hashtag / mention facets with UTF-8 byte offsets."""
+    facets = []
+    url_spans = []  # char ranges already claimed by a link facet
+    for m in URL_RE.finditer(text):
+        uri = m.group(0).rstrip(".,;:)]}'\"")  # drop trailing punctuation
+        c_start, c_end = m.start(), m.start() + len(uri)
+        url_spans.append((c_start, c_end))
+        facets.append({
+            "index": {"byteStart": byte_index(text, c_start),
+                      "byteEnd": byte_index(text, c_end)},
+            "features": [{"$type": "app.bsky.richtext.facet#link", "uri": uri}],
+        })
+
+    def inside_url(pos):
+        # Skip #frag / @x that live inside a URL (e.g. https://x.com/#a) so
+        # facets never overlap — atproto rejects overlapping richtext ranges.
+        return any(s <= pos < e for s, e in url_spans)
+
+    for m in TAG_RE.finditer(text):
+        if inside_url(m.start()):
+            continue
+        facets.append({
+            "index": {"byteStart": byte_index(text, m.start()),
+                      "byteEnd": byte_index(text, m.end())},
+            "features": [{"$type": "app.bsky.richtext.facet#tag", "tag": m.group(1)}],
+        })
+    for m in MENTION_RE.finditer(text):
+        if inside_url(m.start()):
+            continue
+        did = resolve_handle(svc, m.group(1))
+        if did:
+            facets.append({
+                "index": {"byteStart": byte_index(text, m.start()),
+                          "byteEnd": byte_index(text, m.end())},
+                "features": [{"$type": "app.bsky.richtext.facet#mention", "did": did}],
+            })
+    return facets
+
+
+def fetch_bytes(src):
+    if re.match(r"^https?://", src):
+        r = requests.get(src, timeout=120, headers={"User-Agent": "Mozilla/5.0 (bluesky-skill)"})
+        r.raise_for_status()
+        return r.content
+    with open(src, "rb") as f:
+        return f.read()
+
+
+def compress_to_limit(raw):
+    """Return (bytes, mime) within BLOB_LIMIT, recompressing/resizing if needed."""
+    known = {"JPEG": "image/jpeg", "PNG": "image/png", "WEBP": "image/webp", "GIF": "image/gif"}
+    try:
+        fmt = Image.open(io.BytesIO(raw)).format
+    except Exception:
+        die({"error": "image_decode_failed", "detail": "could not read the image bytes"})
+    # Small AND a format Bluesky handles as-is → upload untouched (keeps PNG
+    # transparency / animated GIF). Otherwise fall through and re-encode to JPEG
+    # so the blob's bytes always match its declared mimeType.
+    if len(raw) <= BLOB_LIMIT and fmt in known:
+        return raw, known[fmt]
+
+    img = Image.open(io.BytesIO(raw))
+    if img.mode not in ("RGB", "L"):
+        img = img.convert("RGB")
+    max_side = max(img.size)
+    buf = io.BytesIO()
+    for target_side in (max_side, 2048, 1600, 1280, 1024, 800, 640):
+        if target_side < max_side:
+            ratio = target_side / max_side
+            work = img.resize((max(1, int(img.width * ratio)), max(1, int(img.height * ratio))))
+        else:
+            work = img
+        for quality in (90, 85, 80, 70, 60, 50, 40):
+            buf = io.BytesIO()
+            work.save(buf, format="JPEG", quality=quality, optimize=True)
+            if buf.tell() <= BLOB_LIMIT:
+                return buf.getvalue(), "image/jpeg"
+    # Couldn't get under the limit; return the smallest attempt and let the API decide.
+    return buf.getvalue(), "image/jpeg"
+
+
+def upload_blob(svc, jwt, raw, mime):
+    r = requests.post(
+        f"{svc}/xrpc/com.atproto.repo.uploadBlob",
+        data=raw,
+        headers={"Authorization": f"Bearer {jwt}", "Content-Type": mime},
+        timeout=120,
+    )
+    data = r.json() if r.content else {}
+    if r.status_code != 200 or "blob" not in data:
+        die({"error": "uploadBlob_failed", "status": r.status_code, "detail": data})
+    return data["blob"]
+
+
+def read_text(a):
+    if a.text_file:
+        with open(a.text_file, encoding="utf-8") as f:
+            return f.read().rstrip("\n")
+    if a.text == "-":
+        return sys.stdin.read().rstrip("\n")
+    if a.text is not None:
+        return a.text
+    return ""  # no text source; caller allows this when images are attached
+
+
+def cmd_post(a):
+    svc = env_service()
+    text = read_text(a)
+    images = a.image or []
+    if len(images) > 4:
+        die({"error": "too_many_images", "detail": "Bluesky allows at most 4 images per post"})
+    if not text and not images:
+        die({"error": "empty_post", "detail": "a post needs --text/--text-file or at least one --image"})
+    jwt, did, ident = create_session(svc)
+    record = {
+        "$type": "app.bsky.feed.post",
+        "text": text,
+        "createdAt": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.000Z"),
+        "langs": [a.lang],
+    }
+    facets = build_facets(text, svc)
+    if facets:
+        record["facets"] = facets
+
+    if images:
+        alts = a.alt or []
+        embed_images = []
+        for i, src in enumerate(images):
+            try:
+                raw = fetch_bytes(src)
+            except (requests.RequestException, OSError) as e:
+                die({"error": "image_fetch_failed", "src": src, "detail": str(e)})
+            blob_bytes, mime = compress_to_limit(raw)
+            blob = upload_blob(svc, jwt, blob_bytes, mime)
+            # Missing alt defaults to empty (never reuse another image's alt).
+            alt = alts[i] if i < len(alts) else ""
+            embed_images.append({"alt": alt, "image": blob})
+        record["embed"] = {"$type": "app.bsky.embed.images", "images": embed_images}
+
+    r = requests.post(
+        f"{svc}/xrpc/com.atproto.repo.createRecord",
+        headers={"Authorization": f"Bearer {jwt}", "Content-Type": "application/json"},
+        json={"repo": did, "collection": "app.bsky.feed.post", "record": record},
+        timeout=60,
+    )
+    data = r.json() if r.content else {}
+    if r.status_code != 200 or "uri" not in data:
+        die({"error": "createRecord_failed", "status": r.status_code, "detail": data})
+    rkey = data["uri"].rsplit("/", 1)[-1]
+    out({
+        "posted": True,
+        "uri": data["uri"],
+        "cid": data.get("cid"),
+        "url": f"https://bsky.app/profile/{ident}/post/{rkey}",
+        "images": len(images),
+        "facets": len(facets),
+    })
+
+
+def cmd_list(a):
+    svc = env_service()
+    jwt, did, _ = create_session(svc)
+    r = requests.get(
+        f"{svc}/xrpc/app.bsky.feed.getAuthorFeed",
+        params={"actor": did, "limit": a.limit, "filter": a.filter},
+        headers={"Authorization": f"Bearer {jwt}"},
+        timeout=30,
+    )
+    data = r.json() if r.content else {}
+    if r.status_code != 200:
+        die({"error": "getAuthorFeed_failed", "status": r.status_code, "detail": data})
+    out([
+        {
+            "uri": it["post"]["uri"],
+            "text": it["post"]["record"].get("text", ""),
+            "reposts": it["post"].get("repostCount", 0),
+            "likes": it["post"].get("likeCount", 0),
+            "replies": it["post"].get("replyCount", 0),
+            "at": it["post"].get("indexedAt"),
+        }
+        for it in data.get("feed", [])
+    ])
+
+
+def cmd_delete(a):
+    svc = env_service()
+    jwt, did, _ = create_session(svc)
+    rkey = a.uri.rsplit("/", 1)[-1]
+    r = requests.post(
+        f"{svc}/xrpc/com.atproto.repo.deleteRecord",
+        headers={"Authorization": f"Bearer {jwt}", "Content-Type": "application/json"},
+        json={"repo": did, "collection": "app.bsky.feed.post", "rkey": rkey},
+        timeout=30,
+    )
+    if r.status_code != 200:
+        die({"error": "deleteRecord_failed", "status": r.status_code,
+             "detail": r.json() if r.content else {}})
+    out({"deleted": True, "rkey": rkey})
+
+
+def cmd_whoami(a):
+    svc = env_service()
+    jwt, did, ident = create_session(svc)
+    out({"did": did, "handle": ident, "service": svc, "session": bool(jwt)})
+
+
+def main():
+    p = argparse.ArgumentParser(prog="bluesky", description="Bluesky AT Protocol CLI")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    pp = sub.add_parser("post", help="publish a post (text + optional images + auto facets)")
+    pp.add_argument("--text", help='post text (use "-" to read from stdin)')
+    pp.add_argument("--text-file", help="read post text from a file (safest for multi-line/emoji)")
+    pp.add_argument("--image", action="append", help="image URL or local path (repeatable, max 4)")
+    pp.add_argument("--alt", action="append", help="alt text per image (repeatable, paired by order)")
+    pp.add_argument("--lang", default="en", help="BCP-47 language tag (default: en)")
+    pp.set_defaults(func=cmd_post)
+
+    pl = sub.add_parser("list", help="list my recent posts with engagement")
+    pl.add_argument("--limit", type=int, default=20)
+    pl.add_argument("--filter", default="posts_no_replies",
+                    help="posts_no_replies | posts_with_replies | posts_with_media | posts_and_author_threads")
+    pl.set_defaults(func=cmd_list)
+
+    pd = sub.add_parser("delete", help="delete one of my posts by its at:// uri")
+    pd.add_argument("--uri", required=True)
+    pd.set_defaults(func=cmd_delete)
+
+    pw = sub.add_parser("whoami", help="verify the session and show did/handle")
+    pw.set_defaults(func=cmd_whoami)
+
+    a = p.parse_args()
+    try:
+        a.func(a)
+    except SystemExit:
+        raise
+    except Exception as e:
+        die({"error": f"{type(e).__name__}", "detail": str(e)})
+
+
+if __name__ == "__main__":
+    main()

package/skills/telegram/SKILL.md

@@ -13,7 +13,7 @@ allowed_tools: [Bash]
 license: Apache-2.0
 metadata:
   author: acedatacloud
-  version: "1.1"
+  version: "1.2"
 ---
 
 We drive **personal** Telegram over MTProto with [Telethon](https://docs.telethon.dev/) —
@@ -27,227 +27,26 @@ Credentials are injected as env vars by the connector:
 - `TELEGRAM_SESSION_STRING` — Telethon `StringSession` = **full account access. Never log,
   echo, or print it.** Treat it like the account password.
 
-## Setup — write the helper once per session
+## CLI
 
-`telethon` is preinstalled in the sandbox. The helper is written to `./tg.py` **in the current
-working directory** (the per-session workdir) — not a shared global path — so concurrent
-sessions never race.
+The skill ships [`scripts/tg.py`](scripts/tg.py) — self-contained (the only third-party dep is
+`telethon`, preinstalled in the sandbox). Point a var at the shipped path and call it; no heredoc
+to re-create per turn, so a multi-step flow (dry-run → confirm) can't lose the helper between calls:
+
+```sh
+TG="$SKILL_DIR/scripts/tg.py"
+python3 "$TG" whoami
+```
 
 Every state-changing command (`send`, `reply`, `send-file`, `forward`, `edit`, `delete`,
 `react`, `mark-read`) is **gated**: without a trailing `--confirm` it only DRY-RUNS (prints what
 it would do, changes nothing). Read commands run directly. `--confirm` is honored **only as the
 last argument** so a message/caption that merely contains "--confirm" can never silently confirm.
 
-```sh
-python3 -c "import telethon" 2>/dev/null || pip install --user --quiet telethon 2>/dev/null || true
-
-cat > ./tg.py <<'PY'
-import os, sys, json, asyncio
-from telethon import TelegramClient
-from telethon.sessions import StringSession
-from telethon.tl import functions
-from telethon.tl.types import ReactionEmoji
-
-API_ID = int(os.environ["TELEGRAM_API_ID"])
-API_HASH = os.environ["TELEGRAM_API_HASH"]
-SESSION = os.environ["TELEGRAM_SESSION_STRING"]
-
-_raw = sys.argv[1:]
-# --confirm is only honored as the LAST token, and only one is stripped, so a
-# message/caption that merely contains "--confirm" cannot silently confirm a write.
-CONFIRM = bool(_raw) and _raw[-1] == "--confirm"
-a = _raw[:-1] if CONFIRM else list(_raw)
-cmd = a[0] if a else "help"
-args = a[1:]
-GATED = {"send", "reply", "send-file", "forward", "edit", "delete", "react", "mark-read"}
-
-
-def out(o):
-    print(json.dumps(o, ensure_ascii=False, default=str))
-
-
-async def resolve(client, target):
-    # 1) try direct resolve; 2) fall back to scanning dialogs by id or exact name
-    #    (StringSession doesn't persist the entity cache, so a numeric id from a
-    #    previous invocation may need the dialog scan to recover its access hash).
-    for attempt in (lambda: client.get_entity(int(target)), lambda: client.get_entity(target)):
-        try:
-            return await attempt()
-        except Exception:
-            pass
-    ti = None
-    try:
-        ti = int(target)
-    except (ValueError, TypeError):
-        pass
-    async for d in client.iter_dialogs():
-        if (ti is not None and d.id == ti) or d.name == target:
-            return d.entity
-    raise ValueError(f"could not resolve target: {target}")
-
-
-def msg_row(m):
-    return {"id": m.id, "date": str(m.date), "out": m.out, "sender_id": m.sender_id,
-            "text": m.message, "media": bool(m.media)}
-
-
-def need(n):
-    if len(args) < n:
-        raise ValueError(f"{cmd} needs {n} argument(s), got {len(args)}")
-
-
-async def run():
-    if cmd in GATED and not CONFIRM:
-        out({"dry_run": True, "command": cmd, "args": args,
-             "note": "re-run with --confirm as the LAST argument to actually perform this write"})
-        return
-    async with TelegramClient(StringSession(SESSION), API_ID, API_HASH) as cl:
-        if cmd == "whoami":
-            me = await cl.get_me()
-            out({"id": me.id, "username": me.username,
-                 "name": ((me.first_name or "") + " " + (me.last_name or "")).strip(), "phone": me.phone})
-
-        elif cmd == "list-chats":
-            limit = int(args[0]) if args and args[0].lstrip("-").isdigit() else 20
-            unread_only = "unread-only" in args
-            res = []
-            async for d in cl.iter_dialogs(limit=limit):
-                if unread_only and not d.unread_count:
-                    continue
-                res.append({"name": d.name, "id": d.id, "group": d.is_group,
-                            "channel": d.is_channel, "user": d.is_user, "unread": d.unread_count})
-            out(res)
-
-        elif cmd == "unread":
-            res = []
-            async for d in cl.iter_dialogs():
-                if d.unread_count:
-                    res.append({"name": d.name, "id": d.id, "unread": d.unread_count,
-                                "group": d.is_group, "channel": d.is_channel})
-            out(sorted(res, key=lambda x: -x["unread"]))
-
-        elif cmd == "get-messages":
-            need(1); ent = await resolve(cl, args[0])
-            n = int(args[1]) if len(args) > 1 else 50
-            rows = [msg_row(m) async for m in cl.iter_messages(ent, limit=n)]
-            rows.reverse()
-            out(rows)
-
-        elif cmd == "search":
-            need(2); ent = await resolve(cl, args[0])
-            q = args[1]; n = int(args[2]) if len(args) > 2 else 30
-            out([msg_row(m) async for m in cl.iter_messages(ent, search=q, limit=n)])
-
-        elif cmd == "search-global":
-            need(1); q = args[0]; n = int(args[1]) if len(args) > 1 else 30
-            rows = []
-            async for m in cl.iter_messages(None, search=q, limit=n):
-                r = msg_row(m); r["chat_id"] = m.chat_id
-                rows.append(r)
-            out(rows)
-
-        elif cmd == "contacts":
-            res = await cl(functions.contacts.GetContactsRequest(hash=0))
-            out([{"id": u.id, "username": u.username,
-                  "name": ((u.first_name or "") + " " + (u.last_name or "")).strip(), "phone": u.phone}
-                 for u in res.users])
-
-        elif cmd == "chat-info":
-            need(1); ent = await resolve(cl, args[0])
-            info = {"id": ent.id, "type": type(ent).__name__,
-                    "title": getattr(ent, "title", None),
-                    "name": ((getattr(ent, "first_name", "") or "") + " " + (getattr(ent, "last_name", "") or "")).strip() or None,
-                    "username": getattr(ent, "username", None)}
-            try:
-                info["participants"] = (await cl.get_participants(ent, limit=1)).total
-            except Exception:
-                pass
-            out(info)
-
-        elif cmd == "message-link":
-            need(2); ent = await resolve(cl, args[0]); mid = int(args[1])
-            try:
-                r = await cl(functions.channels.ExportMessageLinkRequest(channel=ent, id=mid))
-                out({"link": r.link})
-            except Exception as e:
-                out({"error": f"links only available for channels/supergroups: {e}"})
-
-        elif cmd == "download-media":
-            need(2); ent = await resolve(cl, args[0]); mid = int(args[1])
-            outdir = args[2] if len(args) > 2 else "./tg_downloads"
-            os.makedirs(outdir, exist_ok=True)
-            m = await cl.get_messages(ent, ids=mid)
-            if not m or not m.media:
-                out({"error": "no media on that message"}); return
-            path = await cl.download_media(m, file=outdir)
-            out({"downloaded": path})
-
-        # ---- gated writes (need trailing --confirm) ----
-        elif cmd == "send":
-            need(2); ent = await resolve(cl, args[0])
-            m = await cl.send_message(ent, args[1])
-            out({"sent": True, "id": m.id})
-
-        elif cmd == "reply":
-            need(3); ent = await resolve(cl, args[0])
-            m = await cl.send_message(ent, args[2], reply_to=int(args[1]))
-            out({"sent": True, "id": m.id, "reply_to": int(args[1])})
-
-        elif cmd == "send-file":
-            need(2); ent = await resolve(cl, args[0])
-            caption = args[2] if len(args) > 2 else None
-            m = await cl.send_file(ent, args[1], caption=caption)
-            out({"sent": True, "id": m.id})
-
-        elif cmd == "forward":
-            need(3); src = await resolve(cl, args[0]); mid = int(args[1]); dst = await resolve(cl, args[2])
-            fwd = await cl.forward_messages(dst, mid, src)
-            out({"forwarded": True, "id": getattr(fwd, "id", None) or [x.id for x in fwd]})
-
-        elif cmd == "edit":
-            need(3); ent = await resolve(cl, args[0])
-            m = await cl.edit_message(ent, int(args[1]), args[2])
-            out({"edited": True, "id": m.id})
-
-        elif cmd == "delete":
-            need(2); ent = await resolve(cl, args[0])
-            await cl.delete_messages(ent, int(args[1]))
-            out({"deleted": True, "id": int(args[1])})
-
-        elif cmd == "react":
-            need(3); ent = await resolve(cl, args[0]); mid = int(args[1]); emoji = args[2]
-            await cl(functions.messages.SendReactionRequest(
-                peer=ent, msg_id=mid, reaction=[ReactionEmoji(emoticon=emoji)]))
-            out({"reacted": True, "id": mid, "emoji": emoji})
-
-        elif cmd == "mark-read":
-            need(1); ent = await resolve(cl, args[0])
-            await cl.send_read_acknowledge(ent)
-            out({"marked_read": True})
-
-        else:
-            out({"error": f"unknown command: {cmd}"}); sys.exit(1)
-
-
-async def main():
-    try:
-        await run()
-    except SystemExit:
-        raise
-    except Exception as e:
-        out({"error": f"{type(e).__name__}: {e}"})
-        sys.exit(1)
-
-
-asyncio.run(main())
-PY
-echo "helper ready"
-```
-
 ## Verify the connection first
 
 ```sh
-python3 ./tg.py whoami
+python3 "$TG" whoami
 # → {"id": 8367450178, "username": "GermeyAce", "name": "Germey", "phone": "..."}
 ```
 
@@ -258,14 +57,14 @@ https://auth.acedata.cloud/user/connections.
 
 | Goal | Command |
 |---|---|
-| Recent conversations | `python3 ./tg.py list-chats 20` |
-| Only chats with unread (ranked) | `python3 ./tg.py unread` |
-| A chat's history (oldest→newest) | `python3 ./tg.py get-messages <target> 50` |
-| Search inside one chat | `python3 ./tg.py search <target> "kw" 30` |
-| Search across ALL chats | `python3 ./tg.py search-global "kw" 30` |
-| List contacts | `python3 ./tg.py contacts` |
-| Info about a chat/user | `python3 ./tg.py chat-info <target>` |
-| t.me link to a message | `python3 ./tg.py message-link <target> <msg_id>` |
+| Recent conversations | `python3 "$TG" list-chats 20` |
+| Only chats with unread (ranked) | `python3 "$TG" unread` |
+| A chat's history (oldest→newest) | `python3 "$TG" get-messages <target> 50` |
+| Search inside one chat | `python3 "$TG" search <target> "kw" 30` |
+| Search across ALL chats | `python3 "$TG" search-global "kw" 30` |
+| List contacts | `python3 "$TG" contacts` |
+| Info about a chat/user | `python3 "$TG" chat-info <target>` |
+| t.me link to a message | `python3 "$TG" message-link <target> <msg_id>` |
 
 `<target>` = numeric id (most reliable — from `list-chats`), `@username`, phone, or exact chat
 name. In message rows, `out:true` = sent by the user; `media:true` = has an attachment.
@@ -277,11 +76,16 @@ each → summarize. Don't dump 20k messages; sample the most-unread / most-relev
 
 ```sh
 # Download an attachment from a message → returns the saved path
-python3 ./tg.py download-media <target> <msg_id> ./tg_downloads
-# Send a local file or a URL (optional caption) — GATED
-python3 ./tg.py send-file <target> /path/or/https-url "caption" --confirm
+python3 "$TG" download-media <target> <msg_id> ./tg_downloads
+# Send a local file OR an http(s) URL (optional caption) — GATED
+python3 "$TG" send-file <target> /path/or/https-url "caption" --confirm
 ```
 
+An `http(s)` URL is downloaded to a real local file first (with the right
+extension from the URL / `Content-Type`) and then uploaded, so a remote image
+lands as a **photo** — not a document, and not a silent failure. This is the
+reliable way to "发图": pass the CDN URL straight to `send-file`.
+
 To hand a downloaded file back to the user as a link, upload it to the CDN (see the
 `cos-upload` skill) after `download-media`.
 
@@ -292,13 +96,13 @@ exactly what will happen, get an explicit "yes", then re-run with `--confirm` as
 argument**. Never bulk-send.
 
 ```sh
-python3 ./tg.py send    <target> "text"                          # → dry_run; add --confirm to send
-python3 ./tg.py reply   <target> <msg_id> "text" --confirm
-python3 ./tg.py forward <from_target> <msg_id> <to_target> --confirm
-python3 ./tg.py edit    <target> <msg_id> "new text" --confirm   # own messages
-python3 ./tg.py delete  <target> <msg_id> --confirm              # destructive
-python3 ./tg.py react   <target> <msg_id> "👍" --confirm
-python3 ./tg.py mark-read <target> --confirm                     # sends read receipts
+python3 "$TG" send    <target> "text"                          # → dry_run; add --confirm to send
+python3 "$TG" reply   <target> <msg_id> "text" --confirm
+python3 "$TG" forward <from_target> <msg_id> <to_target> --confirm
+python3 "$TG" edit    <target> <msg_id> "new text" --confirm   # own messages
+python3 "$TG" delete  <target> <msg_id> --confirm              # destructive
+python3 "$TG" react   <target> <msg_id> "👍" --confirm
+python3 "$TG" mark-read <target> --confirm                     # sends read receipts
 ```
 
 The dry run returns `{"dry_run": true, "command": ..., "args": [...]}` — present that to the

package/skills/telegram/scripts/tg.py

@@ -0,0 +1,270 @@
+#!/usr/bin/env python3
+"""Personal Telegram (MTProto / Telethon) CLI — shipped with the `telegram` skill.
+
+Self-contained: the only third-party dep is `telethon` (preinstalled in the
+sandbox). URL downloads for `send-file` use the stdlib only, so a remote image
+is fetched to a real local file before upload — Telethon sending a bare remote
+URL is unreliable and often lands the media as a document (or fails outright).
+
+Secrets (`TELEGRAM_API_HASH`, `TELEGRAM_SESSION_STRING`) are read from the env
+and never printed.
+"""
+
+import asyncio
+import json
+import mimetypes
+import os
+import sys
+import tempfile
+import urllib.request
+from urllib.parse import urlparse
+
+from telethon import TelegramClient
+from telethon.sessions import StringSession
+from telethon.tl import functions
+from telethon.tl.types import ReactionEmoji
+
+API_ID = int(os.environ["TELEGRAM_API_ID"])
+API_HASH = os.environ["TELEGRAM_API_HASH"]
+SESSION = os.environ["TELEGRAM_SESSION_STRING"]
+
+_raw = sys.argv[1:]
+# --confirm is only honored as the LAST token, and only one is stripped, so a
+# message/caption that merely contains "--confirm" cannot silently confirm a write.
+CONFIRM = bool(_raw) and _raw[-1] == "--confirm"
+a = _raw[:-1] if CONFIRM else list(_raw)
+cmd = a[0] if a else "help"
+args = a[1:]
+GATED = {"send", "reply", "send-file", "forward", "edit", "delete", "react", "mark-read"}
+
+
+def out(o):
+    print(json.dumps(o, ensure_ascii=False, default=str))
+
+
+def _ext_from_content_type(ct):
+    ct = (ct or "").split(";")[0].strip().lower()
+    if not ct:
+        return ""
+    return mimetypes.guess_extension(ct) or ""
+
+
+def materialize_file(src):
+    """Return (local_path, cleanup) for `src`.
+
+    If `src` is an http(s) URL, download it to a temp file with a sensible
+    extension (so Telethon detects images/videos as media, not documents).
+    Local paths are returned unchanged with a no-op cleanup.
+    """
+    parsed = urlparse(src)
+    if parsed.scheme not in ("http", "https"):
+        return src, (lambda: None)
+
+    # Pick an extension from the URL path first, then the response Content-Type.
+    _, url_ext = os.path.splitext(parsed.path)
+    req = urllib.request.Request(src, headers={"User-Agent": "Mozilla/5.0 (telegram-skill)"})
+    with urllib.request.urlopen(req, timeout=120) as resp:  # noqa: S310 - user-supplied media URL
+        ext = url_ext or _ext_from_content_type(resp.headers.get("Content-Type"))
+        fd, path = tempfile.mkstemp(suffix=ext or ".bin", prefix="tg_send_")
+
+        def cleanup():
+            try:
+                os.remove(path)
+            except OSError:
+                pass
+
+        try:
+            with os.fdopen(fd, "wb") as f:
+                while True:
+                    chunk = resp.read(65536)
+                    if not chunk:
+                        break
+                    f.write(chunk)
+        except BaseException:
+            cleanup()  # don't orphan the temp file if the download fails mid-stream
+            raise
+
+    return path, cleanup
+
+
+async def resolve(client, target):
+    # 1) try direct resolve; 2) fall back to scanning dialogs by id or exact name
+    #    (StringSession doesn't persist the entity cache, so a numeric id from a
+    #    previous invocation may need the dialog scan to recover its access hash).
+    for attempt in (lambda: client.get_entity(int(target)), lambda: client.get_entity(target)):
+        try:
+            return await attempt()
+        except Exception:
+            pass
+    ti = None
+    try:
+        ti = int(target)
+    except (ValueError, TypeError):
+        pass
+    async for d in client.iter_dialogs():
+        if (ti is not None and d.id == ti) or d.name == target:
+            return d.entity
+    raise ValueError(f"could not resolve target: {target}")
+
+
+def msg_row(m):
+    return {"id": m.id, "date": str(m.date), "out": m.out, "sender_id": m.sender_id,
+            "text": m.message, "media": bool(m.media)}
+
+
+def need(n):
+    if len(args) < n:
+        raise ValueError(f"{cmd} needs {n} argument(s), got {len(args)}")
+
+
+async def run():
+    if cmd in GATED and not CONFIRM:
+        out({"dry_run": True, "command": cmd, "args": args,
+             "note": "re-run with --confirm as the LAST argument to actually perform this write"})
+        return
+    async with TelegramClient(StringSession(SESSION), API_ID, API_HASH) as cl:
+        if cmd == "whoami":
+            me = await cl.get_me()
+            out({"id": me.id, "username": me.username,
+                 "name": ((me.first_name or "") + " " + (me.last_name or "")).strip(), "phone": me.phone})
+
+        elif cmd == "list-chats":
+            limit = int(args[0]) if args and args[0].lstrip("-").isdigit() else 20
+            unread_only = "unread-only" in args
+            res = []
+            async for d in cl.iter_dialogs(limit=limit):
+                if unread_only and not d.unread_count:
+                    continue
+                res.append({"name": d.name, "id": d.id, "group": d.is_group,
+                            "channel": d.is_channel, "user": d.is_user, "unread": d.unread_count})
+            out(res)
+
+        elif cmd == "unread":
+            res = []
+            async for d in cl.iter_dialogs():
+                if d.unread_count:
+                    res.append({"name": d.name, "id": d.id, "unread": d.unread_count,
+                                "group": d.is_group, "channel": d.is_channel})
+            out(sorted(res, key=lambda x: -x["unread"]))
+
+        elif cmd == "get-messages":
+            need(1); ent = await resolve(cl, args[0])
+            n = int(args[1]) if len(args) > 1 else 50
+            rows = [msg_row(m) async for m in cl.iter_messages(ent, limit=n)]
+            rows.reverse()
+            out(rows)
+
+        elif cmd == "search":
+            need(2); ent = await resolve(cl, args[0])
+            q = args[1]; n = int(args[2]) if len(args) > 2 else 30
+            out([msg_row(m) async for m in cl.iter_messages(ent, search=q, limit=n)])
+
+        elif cmd == "search-global":
+            need(1); q = args[0]; n = int(args[1]) if len(args) > 1 else 30
+            rows = []
+            async for m in cl.iter_messages(None, search=q, limit=n):
+                r = msg_row(m); r["chat_id"] = m.chat_id
+                rows.append(r)
+            out(rows)
+
+        elif cmd == "contacts":
+            res = await cl(functions.contacts.GetContactsRequest(hash=0))
+            out([{"id": u.id, "username": u.username,
+                  "name": ((u.first_name or "") + " " + (u.last_name or "")).strip(), "phone": u.phone}
+                 for u in res.users])
+
+        elif cmd == "chat-info":
+            need(1); ent = await resolve(cl, args[0])
+            info = {"id": ent.id, "type": type(ent).__name__,
+                    "title": getattr(ent, "title", None),
+                    "name": ((getattr(ent, "first_name", "") or "") + " " + (getattr(ent, "last_name", "") or "")).strip() or None,
+                    "username": getattr(ent, "username", None)}
+            try:
+                info["participants"] = (await cl.get_participants(ent, limit=1)).total
+            except Exception:
+                pass
+            out(info)
+
+        elif cmd == "message-link":
+            need(2); ent = await resolve(cl, args[0]); mid = int(args[1])
+            try:
+                r = await cl(functions.channels.ExportMessageLinkRequest(channel=ent, id=mid))
+                out({"link": r.link})
+            except Exception as e:
+                out({"error": f"links only available for channels/supergroups: {e}"})
+
+        elif cmd == "download-media":
+            need(2); ent = await resolve(cl, args[0]); mid = int(args[1])
+            outdir = args[2] if len(args) > 2 else "./tg_downloads"
+            os.makedirs(outdir, exist_ok=True)
+            m = await cl.get_messages(ent, ids=mid)
+            if not m or not m.media:
+                out({"error": "no media on that message"}); return
+            path = await cl.download_media(m, file=outdir)
+            out({"downloaded": path})
+
+        # ---- gated writes (need trailing --confirm) ----
+        elif cmd == "send":
+            need(2); ent = await resolve(cl, args[0])
+            m = await cl.send_message(ent, args[1])
+            out({"sent": True, "id": m.id})
+
+        elif cmd == "reply":
+            need(3); ent = await resolve(cl, args[0])
+            m = await cl.send_message(ent, args[2], reply_to=int(args[1]))
+            out({"sent": True, "id": m.id, "reply_to": int(args[1])})
+
+        elif cmd == "send-file":
+            need(2); ent = await resolve(cl, args[0])
+            caption = args[2] if len(args) > 2 else None
+            # Download remote URLs to a real local file first so images/videos
+            # upload as media instead of failing or landing as a document.
+            path, cleanup = materialize_file(args[1])
+            try:
+                m = await cl.send_file(ent, path, caption=caption)
+            finally:
+                cleanup()
+            out({"sent": True, "id": m.id})
+
+        elif cmd == "forward":
+            need(3); src = await resolve(cl, args[0]); mid = int(args[1]); dst = await resolve(cl, args[2])
+            fwd = await cl.forward_messages(dst, mid, src)
+            out({"forwarded": True, "id": getattr(fwd, "id", None) or [x.id for x in fwd]})
+
+        elif cmd == "edit":
+            need(3); ent = await resolve(cl, args[0])
+            m = await cl.edit_message(ent, int(args[1]), args[2])
+            out({"edited": True, "id": m.id})
+
+        elif cmd == "delete":
+            need(2); ent = await resolve(cl, args[0])
+            await cl.delete_messages(ent, int(args[1]))
+            out({"deleted": True, "id": int(args[1])})
+
+        elif cmd == "react":
+            need(3); ent = await resolve(cl, args[0]); mid = int(args[1]); emoji = args[2]
+            await cl(functions.messages.SendReactionRequest(
+                peer=ent, msg_id=mid, reaction=[ReactionEmoji(emoticon=emoji)]))
+            out({"reacted": True, "id": mid, "emoji": emoji})
+
+        elif cmd == "mark-read":
+            need(1); ent = await resolve(cl, args[0])
+            await cl.send_read_acknowledge(ent)
+            out({"marked_read": True})
+
+        else:
+            out({"error": f"unknown command: {cmd}"}); sys.exit(1)
+
+
+async def main():
+    try:
+        await run()
+    except SystemExit:
+        raise
+    except Exception as e:
+        out({"error": f"{type(e).__name__}: {e}"})
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())