@openhands/extensions 0.0.1-alpha → 0.2.0

package/skills/discord/scripts/_http.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import random
+import time
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+import requests
+
+
+@dataclass(frozen=True)
+class DiscordRateLimitInfo:
+    retry_after: float
+    is_global: bool
+    bucket: str | None
+    remaining: str | None
+    reset_after: str | None
+
+
+class DiscordHTTPError(RuntimeError):
+    pass
+
+
+def _parse_rate_limit_info(*, status_code: int, headers: Mapping[str, str], json_body: Any) -> DiscordRateLimitInfo | None:
+    if status_code != 429:
+        return None
+
+    retry_after: float | None = None
+    is_global = False
+
+    if isinstance(json_body, dict):
+        retry_after_val = json_body.get("retry_after")
+        if isinstance(retry_after_val, (int, float, str)):
+            try:
+                retry_after = float(retry_after_val)
+            except ValueError:
+                retry_after = None
+        is_global = bool(json_body.get("global", False))
+
+    if retry_after is None:
+        hdr = headers.get("Retry-After")
+        if hdr is not None:
+            try:
+                retry_after = float(hdr)
+            except ValueError:
+                retry_after = None
+
+    if retry_after is None:
+        reset_after = headers.get("X-RateLimit-Reset-After")
+        if reset_after is not None:
+            try:
+                retry_after = float(reset_after)
+            except ValueError:
+                retry_after = None
+
+    if retry_after is None:
+        return None
+
+    return DiscordRateLimitInfo(
+        retry_after=retry_after,
+        is_global=is_global,
+        bucket=headers.get("X-RateLimit-Bucket"),
+        remaining=headers.get("X-RateLimit-Remaining"),
+        reset_after=headers.get("X-RateLimit-Reset-After"),
+    )
+
+
+def post_json(
+    *,
+    url: str,
+    headers: Mapping[str, str],
+    payload: Mapping[str, object],
+    timeout_s: float = 30,
+    max_retries: int = 3,
+    max_retry_after_s: float = 60.0,
+    jitter_s: float = 0.25,
+    redact_url_in_errors: bool = False,
+) -> dict[str, object] | None:
+    attempt = 0
+    while True:
+        attempt += 1
+        try:
+            resp = requests.post(url, headers=dict(headers), json=dict(payload), timeout=timeout_s)
+        except requests.RequestException as e:
+            raise DiscordHTTPError(f"HTTP request failed ({e}).") from e
+
+        body_text = resp.text or ""
+        json_body: Any = None
+        if body_text:
+            try:
+                json_body = resp.json()
+            except ValueError:
+                json_body = None
+
+        rl = _parse_rate_limit_info(status_code=resp.status_code, headers=resp.headers, json_body=json_body)
+        if rl is not None and attempt <= max_retries:
+            sleep_s = min(max(0.0, rl.retry_after), max_retry_after_s)
+            if jitter_s > 0:
+                sleep_s += random.uniform(0.0, jitter_s)
+            time.sleep(sleep_s)
+            continue
+
+        if resp.status_code >= 400:
+            context_bits: list[str] = []
+            if not redact_url_in_errors:
+                context_bits.append(f"url={url}")
+            if rl is not None:
+                context_bits.append(f"rate_limit_global={rl.is_global}")
+                if rl.bucket is not None:
+                    context_bits.append(f"rate_limit_bucket={rl.bucket}")
+                if rl.remaining is not None:
+                    context_bits.append(f"rate_limit_remaining={rl.remaining}")
+                if rl.reset_after is not None:
+                    context_bits.append(f"rate_limit_reset_after={rl.reset_after}")
+
+            context = (" " + " ".join(context_bits)) if context_bits else ""
+
+            msg = f"HTTP request failed (HTTP {resp.status_code}).{context}"
+            if body_text:
+                msg += f" Response: {body_text[:500]}"
+            raise DiscordHTTPError(msg)
+
+        if not body_text:
+            return None
+        if isinstance(json_body, dict):
+            return json_body
+        return {"raw": body_text}

package/skills/discord/scripts/post_webhook.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import urllib.parse
+import urllib.request
+
+from ._http import DiscordHTTPError, post_json
+
+
+def _with_wait_param(url: str, *, wait: bool) -> str:
+    if not wait:
+        return url
+
+    parts = urllib.parse.urlsplit(url)
+    query = dict(urllib.parse.parse_qsl(parts.query, keep_blank_values=True))
+    query["wait"] = "true"
+
+    return urllib.parse.urlunsplit(
+        (parts.scheme, parts.netloc, parts.path, urllib.parse.urlencode(query), parts.fragment)
+    )
+
+
+def _request_json(url: str, payload: dict[str, object], *, wait: bool, max_retries: int) -> dict[str, object] | None:
+    request_url = _with_wait_param(url, wait=wait)
+
+    headers = {
+        "Content-Type": "application/json",
+        "User-Agent": "OpenHands-DiscordSkill/1.0 (+https://github.com/OpenHands/skills)",
+    }
+
+    return post_json(
+        url=request_url,
+        headers=headers,
+        payload=payload,
+        max_retries=max_retries,
+        redact_url_in_errors=True,
+    )
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Post a message to a Discord incoming webhook. "
+            "The webhook URL is secret; avoid printing/logging it."
+        )
+    )
+    parser.add_argument(
+        "--webhook-url",
+        default=os.getenv("DISCORD_WEBHOOK_URL"),
+        help="Incoming webhook URL (default: $DISCORD_WEBHOOK_URL)",
+    )
+    parser.add_argument(
+        "--content",
+        help="Message content (max 2000 characters). If omitted, read from stdin.",
+    )
+    parser.add_argument(
+        "--wait",
+        action="store_true",
+        help="Add ?wait=true to get the created message object.",
+    )
+    parser.add_argument(
+        "--max-retries",
+        type=int,
+        default=3,
+        help="Retries on HTTP 429 (default: 3).",
+    )
+
+    args = parser.parse_args()
+
+    if not args.webhook_url:
+        print("Missing --webhook-url (or set DISCORD_WEBHOOK_URL).", file=sys.stderr)
+        return 2
+
+    content = args.content
+    if content is None:
+        content = sys.stdin.read().strip()
+
+    if not content:
+        print("No content provided (use --content or stdin).", file=sys.stderr)
+        return 2
+
+    payload = {
+        "content": content,
+        "allowed_mentions": {"parse": []},
+    }
+
+    result = _request_json(
+        args.webhook_url,
+        payload,
+        wait=args.wait,
+        max_retries=max(0, args.max_retries),
+    )
+
+    if result is not None:
+        print(json.dumps(result, indent=2, sort_keys=True))
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/discord/scripts/send_message.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import urllib.request
+
+from ._http import DiscordHTTPError, post_json
+
+
+API_BASE = "https://discord.com/api/v10"
+
+
+def _post_message(
+    *,
+    token: str,
+    channel_id: str,
+    payload: dict[str, object],
+    max_retries: int,
+) -> dict[str, object] | None:
+    url = f"{API_BASE}/channels/{channel_id}/messages"
+
+    headers = {
+        "Authorization": f"Bot {token}",
+        "Content-Type": "application/json",
+        "User-Agent": "OpenHands-DiscordSkill/1.0 (+https://github.com/OpenHands/skills)",
+    }
+
+    try:
+        return post_json(url=url, headers=headers, payload=payload, max_retries=max_retries)
+    except DiscordHTTPError as e:
+        raise DiscordHTTPError(f"Discord API call failed. channel_id={channel_id}. {e}") from e
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Send a message to a Discord channel using a bot token.")
+    parser.add_argument(
+        "--token",
+        default=os.getenv("DISCORD_BOT_TOKEN"),
+        help="Bot token (default: $DISCORD_BOT_TOKEN)",
+    )
+    parser.add_argument(
+        "--channel-id",
+        default=os.getenv("DISCORD_CHANNEL_ID"),
+        help="Channel ID (default: $DISCORD_CHANNEL_ID)",
+    )
+    parser.add_argument(
+        "--content",
+        help="Message content (max 2000 characters). If omitted, read from stdin.",
+    )
+    parser.add_argument(
+        "--max-retries",
+        type=int,
+        default=3,
+        help="Retries on HTTP 429 (default: 3).",
+    )
+    parser.add_argument(
+        "--allow-mentions",
+        action="store_true",
+        help="Allow Discord to parse mentions. Default is safe (no mentions).",
+    )
+
+    args = parser.parse_args()
+
+    if not args.token:
+        print("Missing --token (or set DISCORD_BOT_TOKEN).", file=sys.stderr)
+        return 2
+
+    if not args.channel_id:
+        print("Missing --channel-id (or set DISCORD_CHANNEL_ID).", file=sys.stderr)
+        return 2
+
+    content = args.content
+    if content is None:
+        content = sys.stdin.read().strip()
+
+    if not content:
+        print("No content provided (use --content or stdin).", file=sys.stderr)
+        return 2
+
+    payload: dict[str, object] = {"content": content}
+    if not args.allow_mentions:
+        payload["allowed_mentions"] = {"parse": []}
+
+    result = _post_message(
+        token=args.token,
+        channel_id=args.channel_id,
+        payload=payload,
+        max_retries=max(0, args.max_retries),
+    )
+
+    if result is not None:
+        print(json.dumps(result, indent=2, sort_keys=True))
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/docker/.plugin/plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "docker",
+  "version": "1.0.0",
+  "description": "Run Docker commands within a container environment, including starting the Docker daemon and managing containers. Use when building, running, or managing Docker containers and images.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "docker",
+    "container",
+    "images"
+  ]
+}

package/skills/docker/README.md

@@ -0,0 +1,34 @@
+# Docker
+
+Run Docker commands within a container environment, including starting the Docker daemon and managing containers. Use when building, running, or managing Docker containers and images.
+
+## Triggers
+
+This skill is activated by the following keywords:
+
+- `docker`
+- `container`
+
+## Details
+
+# Docker Usage Guide
+
+## Starting Docker in Container Environments
+
+Please check if docker is already installed. If so, to start Docker in a container environment:
+
+```bash
+# Start Docker daemon in the background
+sudo dockerd > /tmp/docker.log 2>&1 &
+
+# Wait for Docker to initialize
+sleep 5
+```
+
+## Verifying Docker Installation
+
+To verify Docker is working correctly, run the hello-world container:
+
+```bash
+sudo docker run hello-world
+```

package/skills/docker/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: docker
+description: Run Docker commands within a container environment, including starting the Docker daemon and managing containers. Use when building, running, or managing Docker containers and images.
+triggers:
+- docker
+- container
+---
+
+# Docker Usage Guide
+
+## Starting Docker in Container Environments
+
+Please check if docker is already installed. If so, to start Docker in a container environment:
+
+```bash
+# Start Docker daemon in the background
+sudo dockerd > /tmp/docker.log 2>&1 &
+
+# Wait for Docker to initialize
+sleep 5
+```
+
+## Verifying Docker Installation
+
+To verify Docker is working correctly, run the hello-world container:
+
+```bash
+sudo docker run hello-world
+```

package/skills/evidence-based-citations/.plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "evidence-based-citations",
+  "version": "1.0.0",
+  "description": "Back factual claims and field values with official, verifiable sources. Use when the user asks to fill fields, answer questions, or make claims that must be supported by an exact quote and an official link.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "evidence",
+    "citations",
+    "sources",
+    "verification",
+    "documentation",
+    "official"
+  ]
+}

package/skills/evidence-based-citations/README.md

@@ -0,0 +1,31 @@
+# Evidence-Based Citations
+
+Back factual claims and field values with official, verifiable sources. Use when the user asks to fill fields, answer questions, or make claims that must be supported by an exact quote and an official link.
+
+## Triggers
+
+This skill is activated by the following keywords:
+
+- `evidence-based`
+- `cite source` / `cite sources`
+- `official source` / `official link` / `official links`
+- `official docs` / `official documentation`
+- `verifiable source`
+
+## What it does
+
+When activated, the agent reports every field value or factual claim using four labeled lines:
+
+- **Field** - the field name or short claim description
+- **Value** - the value being assigned
+- **Quote** - the verbatim text from the source supporting the value
+- **Source** - the official URL where the quote can be found
+
+## Source rules
+
+- Prefer primary sources (official docs, RFCs, API references, source code).
+- Fall back to secondary sources (blogs, forums) only when necessary, and label them.
+- The quote must appear verbatim at the source URL.
+- If no official source can be found, say `Source: No official source found.` rather than fabricating a reference.
+
+See [`SKILL.md`](./SKILL.md) for the full prompt the agent loads when this skill is triggered.

package/skills/evidence-based-citations/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: evidence-based-citations
+description: Back factual claims and field values with official, verifiable sources. Use when the user asks to fill fields, answer questions, or make claims that must be supported by an exact quote and an official link.
+triggers:
+- evidence-based
+- cite source
+- cite sources
+- official source
+- official link
+- official links
+- official docs
+- official documentation
+- verifiable source
+---
+
+The user wants every field value or factual claim you produce in the current response to be backed by an official, verifiable source. Apply this skill to the response that triggered it; do not assume it stays active for the rest of the conversation unless the user clearly asks for it to.
+
+## Output format
+
+For each field or claim, respond with exactly these four labeled lines:
+
+- **Field**: the field name (or a short description of the claim)
+- **Value**: the value you are assigning (or the claim itself)
+- **Quote**: the exact verbatim text from the source that supports the value
+- **Source**: the official URL where the quote can be found
+
+When there are multiple fields, repeat the block once per field. Keep blocks separated by a blank line.
+
+## Source selection rules
+
+1. Prefer primary sources, in this order:
+   - Official product / project documentation
+   - Standards documents (RFCs, W3C specs, ISO standards)
+   - Official API references
+   - Source code in the project's own repository
+2. Accept secondary sources (blog posts, Stack Overflow, forum threads, news articles, third-party tutorials) only as a last resort, and clearly label them as such in **Source**.
+3. The **Quote** field must contain text that actually appears at the **Source** URL. Do not paraphrase inside the quote, and do not stitch together text from different parts of the page without making the cut explicit (e.g. with ` … `).
+4. If you cannot find an official source for a value, say so explicitly:
+   - **Source**: `No official source found.`
+   Then either omit the value, mark it as unverified, or ask the user how to proceed. Never invent a quote or URL.
+
+## When to fetch
+
+- If you have a browser / fetch tool available, retrieve the source page and copy the quote directly from it before responding.
+- If you do not have a fetch tool, always respond with `Source: No official source found.` rather than citing URLs from memory. LLMs cannot reliably verify URL accuracy or quote fidelity without actually fetching the page, even when a URL feels familiar.
+
+## Example
+
+> User: What HTTP status code indicates a successful request, per the HTTP semantics RFC?
+
+- **Field**: HTTP status code for a successful request (per RFC 9110)
+- **Value**: 200 (OK)
+- **Quote**: "The 200 (OK) status code indicates that the request has succeeded."
+- **Source**: https://www.rfc-editor.org/rfc/rfc9110.html#section-15.3.1
+
+## What this skill is not
+
+- It is not a general "be careful with facts" reminder. Apply the strict four-field format only when the user has invoked this skill or is clearly asking for evidence-backed answers.
+- It does not change how you write code, edit files, or run tools. It only governs how you report values and claims back to the user.

package/skills/flarglebargle/.plugin/plugin.json

@@ -0,0 +1,16 @@
+{
+  "name": "flarglebargle",
+  "version": "1.0.0",
+  "description": "A test skill that responds to the magic word 'flarglebargle' with a compliment. Use for testing skill activation and trigger functionality.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "test",
+    "demo"
+  ]
+}

package/skills/flarglebargle/README.md

@@ -0,0 +1,14 @@
+# Flarglebargle
+
+A test skill that responds to the magic word "flarglebargle" with a compliment. Use for testing skill activation and trigger functionality.
+
+## Triggers
+
+This skill is activated by the following keywords:
+
+- `flarglebargle`
+
+## Details
+
+IMPORTANT! The user has said the magic word "flarglebargle". You must
+only respond with a message telling them how smart they are

package/skills/flarglebargle/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: flarglebargle
+description: A test skill that responds to the magic word "flarglebargle" with a compliment. Use for testing skill activation and trigger functionality.
+triggers:
+- flarglebargle
+---
+
+IMPORTANT! The user has said the magic word "flarglebargle". You must
+only respond with a message telling them how smart they are

package/skills/frontend-design/.plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "frontend-design",
+  "version": "1.0.0",
+  "description": "Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications. Generates c...",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "frontend",
+    "design",
+    "ui",
+    "web",
+    "react",
+    "html",
+    "css"
+  ]
+}