@acedatacloud/skills 2026.722.2 → 2026.722.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acedatacloud/skills",
-  "version": "2026.722.2",
+  "version": "2026.722.3",
   "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/discord/SKILL.md

@@ -1,74 +1,121 @@
 ---
 name: discord
-description: Read your Discord identity and the list of servers (guilds) you belong to via the Discord API. Use when the user mentions Discord, asks which servers/guilds they are in, or wants their Discord account info.
+description: Work with the user's Discord account. Two modes, auto-selected by how they connected — OAuth (read-only identity + server list) or User Token / BYOC (full personal-account actions: list channels, read messages, send & reply). Use when the user mentions Discord, asks which servers they are in, or wants to read/post in a channel as themselves.
 when_to_use: |
-  Trigger when the user wants to read their Discord account identity
-  (username, avatar, email) or list the servers (guilds) their connected
-  Discord account belongs to. This connection is read-only identity +
-  guild list; it CANNOT read or send channel messages.
+  Trigger for anything on the user's connected Discord account. What you can do
+  depends on how they connected:
+  - OAuth connection → read-only: their identity (username, avatar, email) and
+    the list of servers (guilds) they belong to. No channel messages.
+  - User Token (BYOC) connection → full personal-account actions: list channels,
+    read recent messages, and send / reply in a channel as the user. Writes are
+    gated behind an explicit confirmation.
 connections: [discord]
 allowed_tools: [Bash]
 license: Apache-2.0
 metadata:
   author: acedatacloud
-  version: "1.0"
+  version: "2.0"
 ---
 
-We drive the [Discord API](https://discord.com/developers/docs/reference)
-with `curl + jq`. The user's OAuth bearer token is in `$DISCORD_TOKEN`;
-every call needs it as `Authorization: Bearer $DISCORD_TOKEN`. Use the
-versioned base URL `https://discord.com/api/v10`.
+# discord — work with the user's Discord account
 
-Discord returns standard JSON. Errors look like
-`{"code": <n>, "message": "<reason>"}`. A `401 Unauthorized` means the
-token expired or the connection was revoked — tell the user to re-connect
-Discord at `auth.acedata.cloud/user/connections`. A `429` carries a
-`retry_after` (seconds) field — sleep that long, then retry; never
-parallelize.
+This skill has **two modes**, picked automatically by which credential the
+connector injected. Check the environment first and follow the matching section:
 
-**Scope is read-only `identify` + `email` + `guilds`.** This OAuth
-connection can ONLY read the account's identity and the list of guilds it
-belongs to. It CANNOT read/send channel messages, list a guild's channels
-or members, or manage anything — those require a **Discord Bot** (bot
-token + gateway), which this connector does not provide. Do not call
-`/guilds/{id}/channels`, `/channels/...`, or `/guilds/{id}/members` — they
-return 401/403 with a user OAuth token. If the user asks for those, say it
-needs a Discord bot integration, which isn't set up.
-
-## Recipes
-
-### Verify auth + identity (always run first)
+- **`$DISCORD_USER_TOKEN` is set** → **User Token (BYOC) mode**: full
+  personal-account actions via the `scripts/discord_user.py` CLI (list channels, read
+  messages, send / reply). This acts as the user's **real account**.
+- **only `$DISCORD_TOKEN` is set** → **OAuth mode**: read-only identity + server
+  list via `curl`. Channel messages are **not** available in this mode.
 
 ```sh
-curl -sS -H "Authorization: Bearer $DISCORD_TOKEN" \
-  "https://discord.com/api/v10/users/@me" \
-  | jq '{id, username, global_name, email, avatar}'
+if [ -n "$DISCORD_USER_TOKEN" ]; then echo "mode: user-token (full)"; \
+elif [ -n "$DISCORD_TOKEN" ]; then echo "mode: oauth (read-only)"; \
+else echo "no Discord connection — connect at https://auth.acedata.cloud/user/connections"; fi
 ```
 
-### List the servers (guilds) the user is in
+Both tokens are **secret — full account access. Never echo or print them.** On
+`401`, the token expired or was revoked — tell the user to reconnect at
+`auth.acedata.cloud/user/connections`. On `429`, sleep the `retry_after`
+seconds, then retry; never parallelize.
+
+---
+
+## User Token (BYOC) mode — full actions
+
+When `$DISCORD_USER_TOKEN` is set, drive the user's real account through
+[`discord.py-self`](https://github.com/dolfies/discord.py-self) via the CLI at
+`scripts/discord_user.py` (run with `python3`). It logs in with the token only (no
+gateway) and prints JSON.
+
+`discord.py-self` is preinstalled in the hosted sandbox (import name `discord`).
+Do **not** `pip install` it at runtime; if import fails, report that the sandbox
+image is missing the dependency and stop.
+
+**Writes (`send` / `reply`) are gated by a trailing `--confirm`.** Without it
+they dry-run and print what they *would* send. **Confirm the exact channel and
+content with the user before sending** — it's irreversible and public. Only
+append `--confirm` (as the very last argument) once the user approves.
 
 ```sh
-curl -sS -H "Authorization: Bearer $DISCORD_TOKEN" \
-  "https://discord.com/api/v10/users/@me/guilds" \
-  | jq 'map({id, name, owner, approximate_member_count})'
+# identity (always run first)
+python3 scripts/discord_user.py whoami
+# list the servers (guilds) the account is in
+python3 scripts/discord_user.py guilds
+# list text channels in a server
+python3 scripts/discord_user.py channels --guild 1133012399448928276
+# read recent messages in a channel
+python3 scripts/discord_user.py messages --channel 1133012400174534792 --limit 20
+# send — dry-run first, then re-run with a trailing --confirm
+python3 scripts/discord_user.py send --channel 1133012400174534792 --text "hello"
+python3 scripts/discord_user.py send --channel 1133012400174534792 --text "hello" --confirm
+# reply to a specific message
+python3 scripts/discord_user.py reply \
+  --channel 1133012400174534792 --message 987654321098765432 --text "on it" --confirm
 ```
 
-Add `?with_counts=true` to include `approximate_member_count` /
-`approximate_presence_count`:
+`--confirm` is honored ONLY as the final argument (one strip), so a message body
+that merely contains the text `--confirm` can never silently trigger a send. IDs
+are numeric Discord snowflakes. A proxy can be forced via `DISCORD_PROXY` (falls
+back to `HTTPS_PROXY` / `ALL_PROXY`) if the sandbox needs one to reach
+`discord.com`.
+
+---
+
+## OAuth mode — read-only
+
+When only `$DISCORD_TOKEN` is set, drive the
+[Discord API](https://discord.com/developers/docs/reference) with `curl + jq`.
+Auth header is `Authorization: Bearer $DISCORD_TOKEN`; base URL
+`https://discord.com/api/v10`.
+
+**Scope is read-only `identify` + `email` + `guilds`.** This mode can ONLY read
+the account's identity and its guild list. It CANNOT read/send channel messages,
+list a guild's channels or members, or manage anything — `/guilds/{id}/channels`,
+`/channels/...`, `/guilds/{id}/members` return 401/403 with an OAuth token. If the
+user needs those, they must connect Discord with a **User Token** (the BYOC mode
+above), or use a **Discord Bot** (`discordbot` connection) to act as a bot.
 
 ```sh
+# identity (always run first)
+curl -sS -H "Authorization: Bearer $DISCORD_TOKEN" \
+  "https://discord.com/api/v10/users/@me" \
+  | jq '{id, username, global_name, email, avatar}'
+
+# the servers (guilds) the user is in (add ?with_counts=true for member counts)
 curl -sS -H "Authorization: Bearer $DISCORD_TOKEN" \
   "https://discord.com/api/v10/users/@me/guilds?with_counts=true" \
   | jq 'map({id, name, owner, members: .approximate_member_count})'
 ```
 
+---
+
 ## Notes
 
-- A "server" in the UI is a "guild" in the API. `owner: true` means the
-  user owns that guild.
-- Guild icon URL (when `icon` is non-null):
-  `https://cdn.discordapp.com/icons/<guild_id>/<icon>.png` (use `.gif` if
-  the icon hash starts with `a_`).
-- The guild list paginates at 200; the typical user is in far fewer, so a
-  single call is usually enough. If you ever hit 200, paginate with
-  `?after=<last_guild_id>`.
+- A "server" in the UI is a "guild" in the API; messages live in channels inside
+  guilds. In User Token mode: `guilds` → `channels --guild <id>` → act on a
+  channel id. Don't invent ids.
+- In OAuth mode, `owner: true` means the user owns that guild. Guild icon URL
+  (when `icon` is non-null): `https://cdn.discordapp.com/icons/<guild_id>/<icon>.png`
+  (use `.gif` if the hash starts with `a_`). The guild list paginates at 200;
+  paginate with `?after=<last_guild_id>` if you ever hit it.

package/skills/discord/scripts/discord_user.py

@@ -0,0 +1,229 @@
+#!/usr/bin/env python3
+"""
+discord_user.py — act on Discord with the user's own account (BYOC user-token path).
+
+This is the **BYOC** half of the `discord` skill. It runs only when the user
+connected Discord with a personal user token (env ``DISCORD_USER_TOKEN``); the
+OAuth half of the skill uses plain ``curl`` and is documented in SKILL.md.
+
+Drives Discord's user API through `discord.py-self`
+(https://github.com/dolfies/discord.py-self). This acts as the user's REAL
+account, so every state-changing command (send / reply) is GATED by a trailing
+``--confirm`` — without it, the command dry-runs.
+
+The connector injects the token as env var ``DISCORD_USER_TOKEN``. It is full
+account access — NEVER echo or print it.
+
+Examples:
+  python3 discord_user.py whoami
+  python3 discord_user.py guilds
+  python3 discord_user.py channels --guild 1133012399448928276
+  python3 discord_user.py messages --channel 1133012400174534792 --limit 20
+  python3 discord_user.py send --channel 1133012400174534792 --text "hello" --confirm
+  python3 discord_user.py reply --channel 1133012400174534792 --message 987654321 --text "on it" --confirm
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import os
+import sys
+
+_RAW = sys.argv[1:]
+# --confirm is honored ONLY as the last token, and only one is stripped, so a
+# message body that merely contains "--confirm" can never silently confirm a write.
+CONFIRM = bool(_RAW) and _RAW[-1] == "--confirm"
+ARGV = _RAW[:-1] if CONFIRM else list(_RAW)
+
+# State-changing commands — dry-run unless the invocation ends with --confirm.
+GATED = {"send", "reply"}
+
+
+def out(obj) -> None:
+    print(json.dumps(obj, ensure_ascii=False, indent=2, default=str))
+
+
+def die(msg: str, code: int = 1) -> None:
+    out({"error": msg})
+    sys.exit(code)
+
+
+def load_token() -> str:
+    tok = os.environ.get("DISCORD_USER_TOKEN")
+    if not tok:
+        die("DISCORD_USER_TOKEN is not set — connect Discord (User Token) at "
+            "https://auth.acedata.cloud/user/connections, then retry.")
+    return tok.strip()
+
+
+def proxy() -> str | None:
+    return (
+        os.environ.get("DISCORD_PROXY")
+        or os.environ.get("HTTPS_PROXY") or os.environ.get("https_proxy")
+        or os.environ.get("ALL_PROXY") or os.environ.get("all_proxy")
+        or None
+    )
+
+
+def channel_id(args) -> int:
+    try:
+        return int(args.channel)
+    except (TypeError, ValueError):
+        die("--channel must be a numeric Discord channel id")
+
+
+def guild_id(args) -> int:
+    try:
+        return int(args.guild)
+    except (TypeError, ValueError):
+        die("--guild must be a numeric Discord guild (server) id")
+
+
+async def messageable_channel(client, args):
+    """Fetch a channel and confirm it can hold messages (not a category/forum)."""
+    import discord.abc
+    ch = await client.fetch_channel(channel_id(args))
+    if not isinstance(ch, discord.abc.Messageable):
+        die(f"channel {ch.id} is a {ch.type} channel, which can't hold messages — "
+            "pass a text/voice channel id (see `channels --guild <id>`)")
+    return ch
+
+
+# ── commands ──────────────────────────────────────────────────────────────
+async def cmd_whoami(client, args):
+    u = client.user
+    out({"id": str(u.id), "username": u.name, "global_name": getattr(u, "global_name", None),
+         "bot": u.bot})
+
+
+async def cmd_guilds(client, args):
+    guilds = await client.fetch_guilds(with_counts=True)
+    out([{"id": str(g.id), "name": g.name,
+          "members": getattr(g, "approximate_member_count", None)} for g in guilds])
+
+
+async def cmd_channels(client, args):
+    import discord
+    guild = await client.fetch_guild(guild_id(args))
+    channels = await guild.fetch_channels()
+    text = [c for c in channels if isinstance(c, (discord.TextChannel,))]
+    out([{"id": str(c.id), "name": c.name, "type": str(c.type)} for c in text])
+
+
+async def cmd_messages(client, args):
+    ch = await messageable_channel(client, args)
+    msgs = [m async for m in ch.history(limit=args.limit)]
+    out([{"id": str(m.id), "author": m.author.name, "author_id": str(m.author.id),
+          "ts": m.created_at, "content": m.content} for m in msgs])
+
+
+async def cmd_send(client, args):
+    ch = await messageable_channel(client, args)
+    if not CONFIRM:
+        out({"dry_run": True, "would_send": {"channel": str(ch.id),
+             "channel_name": getattr(ch, "name", None), "text": args.text},
+             "hint": "re-run with a trailing --confirm to actually send"})
+        return
+    msg = await ch.send(args.text)
+    out({"sent": True, "channel": str(ch.id), "message_id": str(msg.id)})
+
+
+async def cmd_reply(client, args):
+    import discord
+    ch = await messageable_channel(client, args)
+    try:
+        target = int(args.message)
+    except (TypeError, ValueError):
+        die("--message must be a numeric Discord message id")
+    if not CONFIRM:
+        out({"dry_run": True, "would_reply": {"channel": str(ch.id),
+             "reply_to": str(target), "text": args.text},
+             "hint": "re-run with a trailing --confirm to actually send"})
+        return
+    ref = discord.MessageReference(message_id=target, channel_id=ch.id,
+                                   guild_id=getattr(ch, "guild", None) and ch.guild.id)
+    msg = await ch.send(args.text, reference=ref)
+    out({"sent": True, "channel": str(ch.id), "message_id": str(msg.id),
+         "reply_to": str(target)})
+
+
+HANDLERS = {
+    "whoami": cmd_whoami, "guilds": cmd_guilds, "channels": cmd_channels,
+    "messages": cmd_messages, "send": cmd_send, "reply": cmd_reply,
+}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="discord_user.py", description="Discord user-token CLI")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("whoami", help="verify the token and show the logged-in account")
+    sub.add_parser("guilds", help="list the servers (guilds) the account is in")
+
+    sp = sub.add_parser("channels", help="list text channels in a server")
+    sp.add_argument("--guild", required=True)
+
+    sp = sub.add_parser("messages", help="read recent messages in a channel")
+    sp.add_argument("--channel", required=True)
+    sp.add_argument("--limit", type=int, default=20)
+
+    sp = sub.add_parser("send", help="send a message to a channel (GATED by trailing --confirm)")
+    sp.add_argument("--channel", required=True)
+    sp.add_argument("--text", required=True)
+
+    sp = sub.add_parser("reply", help="reply to a message (GATED by trailing --confirm)")
+    sp.add_argument("--channel", required=True)
+    sp.add_argument("--message", required=True)
+    sp.add_argument("--text", required=True)
+    return p
+
+
+async def run(args) -> None:
+    import discord
+    client = discord.Client(proxy=proxy())
+    try:
+        await client.login(load_token())
+        await HANDLERS[args.cmd](client, args)
+    finally:
+        # close() is safe even if login() failed (no session opened).
+        await client.close()
+
+
+def main() -> None:
+    args = build_parser().parse_args(ARGV)
+    if args.cmd in GATED and not CONFIRM:
+        # Still resolve the channel for the dry-run preview, but never write.
+        pass
+    try:
+        import discord
+        from discord.errors import (
+            LoginFailure, Forbidden, NotFound, HTTPException,
+        )
+    except Exception as e:  # discord.py-self not importable
+        die(f"discord.py-self is not available in the sandbox image: {e}. "
+            "Deploy the sandbox skill dependencies image; do not pip-install it at runtime.")
+    try:
+        asyncio.run(run(args))
+    except LoginFailure as e:
+        die("auth failed — the Discord user token is wrong or expired. Reconnect "
+            f"at https://auth.acedata.cloud/user/connections. ({e})")
+    except Forbidden as e:
+        die(f"forbidden by Discord (no access to that channel/server, or blocked): {e}")
+    except NotFound as e:
+        die(f"not found — check the channel / guild / message id: {e}")
+    except HTTPException as e:
+        # 429 rate limits and other API errors land here.
+        status = getattr(e, "status", None)
+        if status == 429:
+            retry = getattr(e, "retry_after", None)
+            die(f"rate limited by Discord — wait {retry or 'a bit'}s and retry; never parallelize. ({e})")
+        die(f"Discord API error (HTTP {status}): {e}")
+    except Exception as e:
+        die(f"Discord request failed ({type(e).__name__}: {e}). Likely an expired "
+            "token — reconnect at https://auth.acedata.cloud/user/connections.")
+
+
+if __name__ == "__main__":
+    main()