@sulala/agent-os 0.1.5 → 0.1.6

package/data/skills/gmail/references/send-email.md

@@ -0,0 +1,54 @@
+# Send email script
+
+The Gmail skill includes a script that sends email using the Gmail API with an OAuth2 access token. Use it when you have a token (e.g. from Sulala Portal) and want to send from the command line or from automation.
+
+## Prerequisites
+
+- **Access token**: Obtain from Sulala Portal (`POST connections/{connection_id}/use` with your Gmail connection), or from your own OAuth flow. Token must have `https://www.googleapis.com/auth/gmail.send` scope.
+- **Python 3.6+**: No extra pip packages; script uses only the standard library.
+
+## Usage
+
+From the skill directory (or with paths adjusted):
+
+```bash
+python3 scripts/send_email.py \
+  --token "YOUR_ACCESS_TOKEN" \
+  --to "recipient@example.com" \
+  --subject "Subject line" \
+  --body "Email body text."
+```
+
+With body from a file:
+
+```bash
+python3 scripts/send_email.py \
+  --token "YOUR_ACCESS_TOKEN" \
+  --to "recipient@example.com" \
+  --subject "Subject" \
+  --body-file path/to/body.txt
+```
+
+## Options
+
+| Option       | Required | Description                          |
+|-------------|----------|--------------------------------------|
+| `--token`   | Yes      | OAuth2 access token (Bearer).        |
+| `--to`      | Yes      | Recipient email address.             |
+| `--subject` | Yes      | Email subject line.                  |
+| `--body`    | One of   | Email body as a string.              |
+| `--body-file` | One of | Path to file containing body text.  |
+
+## Getting the token (Sulala Portal)
+
+1. Call the Portal API to list connections: `GET connections` (filter for `provider === "gmail"`).
+2. Call `POST connections/{connection_id}/use` with the Gmail connection’s `connection_id` (e.g. `conn_gmail_...`; use `connection_id` if `id` returns 404).
+3. Use the `accessToken` from the response as `--token`.
+
+## Troubleshooting
+
+| Problem              | Cause                    | Action                          |
+|----------------------|--------------------------|---------------------------------|
+| 401 Unauthorized      | Token expired or invalid | Refresh or re-issue token.      |
+| Recipient required   | Missing/invalid To       | Ensure `--to` is a valid email. |
+| Invalid To header    | Bad To format            | Use plain email, no extra text. |

package/data/skills/gmail/scripts/send_email.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""Send email via Gmail API using an OAuth access token.
+
+Use when you have a token from Sulala Portal (connections/:id/use) or another source.
+No local OAuth files required; pass the token on the command line.
+
+Usage:
+  python3 send_email.py --token TOKEN --to recipient@example.com --subject "Subject" --body "Body text"
+  python3 send_email.py --token TOKEN --to recipient@example.com --subject "Subject" --body-file body.txt
+
+Requires: Python 3.6+. No extra pip packages (uses urllib and base64 from stdlib).
+"""
+
+import argparse
+import base64
+import json
+import sys
+import urllib.request
+import urllib.error
+
+GMAIL_SEND_URL = "https://gmail.googleapis.com/gmail/v1/users/me/messages/send"
+
+
+def base64url_encode(data: bytes) -> str:
+    """Encode bytes to base64url (RFC 4648): no +/ padding, use -_."""
+    b64 = base64.b64encode(data).decode("ascii")
+    return b64.replace("+", "-").replace("/", "_").rstrip("=")
+
+
+def build_rfc2822(to: str, subject: str, body: str) -> str:
+    """Build a minimal RFC 2822 message (CRLF line endings)."""
+    lines = [
+        f"To: {to}",
+        f"Subject: {subject}",
+        "Content-Type: text/plain; charset=UTF-8",
+        "",
+        body,
+    ]
+    return "\r\n".join(lines)
+
+
+def send(token: str, to: str, subject: str, body: str) -> None:
+    rfc2822 = build_rfc2822(to, subject, body)
+    raw = base64url_encode(rfc2822.encode("utf-8"))
+    body_json = json.dumps({"raw": raw}).encode("utf-8")
+
+    req = urllib.request.Request(
+        GMAIL_SEND_URL,
+        data=body_json,
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+        },
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req) as resp:
+            if resp.status != 200:
+                sys.stderr.write(f"Unexpected status: {resp.status}\n")
+                sys.exit(1)
+            print("Email sent successfully.")
+    except urllib.error.HTTPError as e:
+        sys.stderr.write(f"Gmail API error: {e.code} {e.reason}\n")
+        if e.fp:
+            body = e.fp.read().decode("utf-8", errors="replace")
+            sys.stderr.write(body)
+            sys.stderr.write("\n")
+        sys.exit(1)
+    except OSError as e:
+        sys.stderr.write(f"Request failed: {e}\n")
+        sys.exit(1)
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="Send email via Gmail API with an access token.")
+    ap.add_argument("--token", required=True, help="OAuth2 access token (e.g. from Sulala Portal)")
+    ap.add_argument("--to", required=True, help="Recipient email address")
+    ap.add_argument("--subject", required=True, help="Email subject")
+    group = ap.add_mutually_exclusive_group(required=True)
+    group.add_argument("--body", help="Email body (plain text)")
+    group.add_argument("--body-file", help="Path to file containing email body")
+    args = ap.parse_args()
+
+    if args.body is not None:
+        body = args.body
+    else:
+        with open(args.body_file, "r", encoding="utf-8") as f:
+            body = f.read()
+
+    send(args.token, args.to, args.subject, body)
+
+
+if __name__ == "__main__":
+    main()

package/data/skills/hash/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: hash
+description: Compute or verify file checksums (SHA-256, MD5). Use when the user asks "checksum of this file", "SHA256 of …", "verify the digest", "hash of file", "MD5 of …".
+metadata:
+  clawdbot:
+    emoji: "🔐"
+    requires:
+      bins:
+        - sha256sum
+        - md5sum
+---
+
+# Hash / checksum
+
+Use **sha256sum** or **md5sum** via the **exec** tool to compute or verify file digests. Run from the workspace or pass an absolute path.
+
+## SHA-256
+
+```bash
+sha256sum path/to/file
+sha256sum ./package.json
+```
+
+Output: `hexdigest  path/to/file`. Use `-c` to verify a list of digests from stdin or a file.
+
+## MD5
+
+```bash
+md5sum path/to/file
+md5sum ./image.png
+```
+
+## Verify a checksum
+
+User gives expected digest; compute and compare:
+
+```bash
+sha256sum -c - <<< "expected_hex  path/to/file"
+# Or: echo "expected_hex  file" | sha256sum -c
+```
+
+## On macOS
+
+macOS uses different names; use one of:
+
+```bash
+shasum -a 256 path/to/file
+md5 path/to/file
+```
+
+`shasum -a 256` is equivalent to `sha256sum`. Prefer `shasum -a 256` if `sha256sum` is not available.
+
+## Tips
+
+- Path can be relative (to workspace) or absolute (e.g. `~/Downloads/file.zip`).
+- For "checksum of this file" or "verify this digest", run the command and compare output to what the user provided.

package/data/skills/jq/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: jq
+description: Parse, filter, and transform JSON (via jq). Use when the user wants to "parse this JSON", "extract field from this response", "filter JSON", or "get X from this API output".
+metadata:
+  clawdbot:
+    emoji: "📋"
+    requires:
+      bins:
+        - jq
+---
+
+# JSON with jq
+
+Use **jq** via the **exec** tool to parse, extract, and filter JSON. Pipe JSON from a file or from stdin (e.g. curl output).
+
+## Parse and pretty-print
+
+```bash
+echo '{"a":1,"b":2}' | jq .
+cat response.json | jq .
+```
+
+## Extract a field
+
+```bash
+echo '{"name":"Alice","age":30}' | jq -r '.name'
+# Output: Alice
+```
+
+```bash
+curl -s "https://api.example.com/data" | jq -r '.items[0].title'
+```
+
+## Extract multiple fields
+
+```bash
+echo '{"a":1,"b":2,"c":3}' | jq '{a, b}'
+# Output: {"a":1,"b":2}
+```
+
+## Array slice and filter
+
+```bash
+echo '[1,2,3,4,5]' | jq '.[:3]'
+echo '[{"x":1},{"x":2},{"x":3}]' | jq '.[] | select(.x > 1)'
+```
+
+## Keys or length
+
+```bash
+echo '{"a":1,"b":2}' | jq 'keys'
+echo '[1,2,3]' | jq 'length'
+```
+
+## From a file in the workspace
+
+```bash
+jq -r '.config.version' ./package.json
+jq '.data[] | {id, name}' ./data.json
+```
+
+## Tips
+
+- Use `-r` for raw string output (no quotes).
+- Use `jq -c` for compact one-line output.
+- If jq is not installed, the skill cannot be used; document that `jq` is required (e.g. `apt install jq` / `brew install jq`).

package/data/skills/markdown-to-html/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: markdown-to-html
+description: Convert Markdown to HTML (via pandoc or a simple converter). Use when the user says "convert this markdown to HTML", "render this .md as HTML", "markdown to HTML".
+metadata:
+  clawdbot:
+    emoji: "📝"
+    requires:
+      bins:
+        - pandoc
+---
+
+# Markdown to HTML
+
+Use **pandoc** via the **exec** tool to convert Markdown to HTML. Input can be a file path or stdin.
+
+## Convert a file
+
+```bash
+pandoc input.md -o output.html
+pandoc input.md -f markdown -t html -o output.html
+```
+
+## Stdout (no output file)
+
+```bash
+pandoc input.md -f markdown -t html
+cat input.md | pandoc -f markdown -t html
+```
+
+## Standalone HTML (with basic document shell)
+
+```bash
+pandoc input.md -s -o output.html
+# -s = standalone (adds <!DOCTYPE html>, <head>, <body>)
+```
+
+## From stdin (e.g. paste or pipe)
+
+```bash
+echo "# Hello" | pandoc -f markdown -t html
+```
+
+## Tips
+
+- Input path can be relative (workspace) or absolute. Output path is relative to exec cwd (workspace) unless absolute.
+- If pandoc is not installed: `brew install pandoc` (macOS), `apt install pandoc` (Linux).
+- For "convert this markdown to HTML", run pandoc on the file or pipe the content to pandoc and return the HTML (or write to a file in the workspace and tell the user the path).

package/data/skills/memory/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: memory
+description: Store and retrieve long-term memories about the user and conversations (preferences, profile, important facts).
+tools:
+  - id: memory_write
+    description: Store a fact in long-term memory. Pass body with agent_id (your current agent id), text (the fact in natural language), optional user_id and tags (e.g. ["profile"]).
+    method: POST
+    path: /api/memory/write
+  - id: memory_search
+    description: Search long-term memory. Pass query params q (search string), optional agent_id, user_id, limit (default 10). Use semantic=1 for meaning-based search.
+    method: GET
+    path: /api/memory/search
+---
+
+# Memory Skill
+
+Use this skill to **remember** important facts and **recall** them later.
+
+## When to use this skill
+
+**You MUST call this skill when:**
+
+- The user says anything like:
+  - "Remember that I …" / "Can you remember that …" / "Please save this about me …"
+  - "My [X] is …" (e.g. "My DOB is 25 May 1997", "My name is …", "I live in …")
+- The user asks:
+  - "What do I love?" / "Where do I live?" / "What do you remember about me?" / "What did I tell you about X?"
+
+**Flow:**
+
+- For **new information to store**: call **memory_write** (POST) with a clear `text` fact.
+- For **recall**: call **memory_search** (GET) with `q` set to relevant keywords, then answer from the results.
+
+## Write memory (store a fact)
+
+- **Method**: `POST`
+- **Path**: `/api/memory/write`
+- **Body (JSON)**:
+  - `agent_id` (string, required) — your current agent id (e.g. from the run context)
+  - `text` (string, required) — the fact in natural language (e.g. "User's date of birth is 25 May 1997")
+  - `user_id` (string, optional)
+  - `tags` (array of strings, optional) — e.g. `["profile"]`, `["preference"]`
+
+**Example — user says "save my dob is 25 may 1997":**
+
+```json
+{
+  "body": {
+    "agent_id": "personal_agent",
+    "text": "User's date of birth is 25 May 1997.",
+    "tags": ["profile"]
+  }
+}
+```
+
+Use the correct `agent_id` for the current agent. Write a clear, standalone sentence in `text`.
+
+## Search memory
+
+- **Method**: `GET`
+- **Path**: `/api/memory/search`
+- **Query**: `q` (search string), optional `agent_id`, `user_id`, `limit` (default 10). Add `semantic=1` for similarity search when embeddings are available.
+
+The server base URL is configured at runtime (e.g. set `AGENT_OS_SKILL_BASE_URL` to `http://127.0.0.1:3010` when running locally).

package/data/skills/qr-code/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: qr-code
+description: Generate a QR code from URL or text (via qrencode or API). Use when the user says "generate a QR code for this URL", "QR code for …", "make a QR code".
+metadata:
+  clawdbot:
+    emoji: "📱"
+    requires:
+      bins:
+        - qrencode
+---
+
+# QR code
+
+Generate a QR code from a URL or text. Use **qrencode** via the **exec** tool, or a public API as fallback.
+
+## qrencode (terminal / PNG)
+
+**Output as PNG file:**
+
+```bash
+qrencode -o qr.png "https://example.com"
+qrencode -o ~/Downloads/qr.png "https://example.com"
+```
+
+**Output to stdout (ASCII art in terminal):**
+
+```bash
+qrencode -t ANSIUTF8 "https://example.com"
+qrencode -t UTF8 "Hello world"
+```
+
+**Options:**
+
+- `-o file` — write PNG to file (path can be in workspace or e.g. `~/Downloads/qr.png`)
+- `-t ANSIUTF8` or `-t UTF8` — print QR as blocks in the terminal (no file)
+- `-s 10` — module size (pixels per module) for PNG
+
+## If qrencode is not installed
+
+**macOS:** `brew install qrencode`  
+**Linux:** `apt install qrencode` or `yum install qrencode`
+
+**Fallback (curl to API, no local binary):**
+
+```bash
+# Example: API that returns PNG (many exist). Use -o with a path the user can find.
+curl -s "https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=URL_ENCODED_TEXT" -o ~/Downloads/qr.png
+```
+
+URL-encode the `data` parameter (e.g. `https%3A%2F%2Fsulala.ai` for `https://sulala.ai`).
+
+## Where the file is saved
+
+Exec runs with **cwd = agent workspace**: `~/.agent-os/workspaces/<agent_id>/`. So:
+
+- **Relative path** (e.g. `-o sulala_ai.png`) → file is at `~/.agent-os/workspaces/<agent_id>/sulala_ai.png`. The user may not know this path.
+- **Absolute path** (e.g. `-o ~/Downloads/sulala_ai.png`) → file is in Downloads and easy to find.
+
+**Prefer saving to a user-visible location** when the user will want to open the file: use `-o ~/Downloads/filename.png` (or tell the user the full workspace path: `~/.agent-os/workspaces/<agent_id>/filename.png`).
+
+## Tips
+
+- For "QR code for this URL", use the URL as the only argument (in quotes). For the API, URL-encode it in the `data=` parameter.
+- Prefer `-o ~/Downloads/qr.png` (or similar) so the user can find the file; if you use a relative path, tell them the full path: `~/.agent-os/workspaces/<agent_id>/filename.png`.
+- For "show me a QR code" without saving, use qrencode `-t ANSIUTF8` (terminal art), or generate PNG to `~/Downloads` and give the path.

package/data/skills/rss/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: rss
+description: Fetch RSS or Atom feed content from a URL. Use when the user asks "latest from this blog", "what's new on …", "recent posts from [URL]", "RSS feed", "feed from …".
+metadata:
+  clawdbot:
+    emoji: "📰"
+    requires:
+      bins:
+        - curl
+---
+
+# RSS / Atom feed
+
+Fetch a feed URL via **curl**; the response is XML (RSS or Atom). Use the **exec** tool. Optionally trim output with `head -c` so the agent gets a manageable chunk to summarize.
+
+## Fetch feed (raw XML)
+
+```bash
+curl -sL "https://example.com/feed.xml"
+curl -sL "https://blog.example.com/rss"
+```
+
+## Limit size (feeds can be large)
+
+```bash
+curl -sL "https://example.com/feed.xml" | head -c 50000
+# First 50 KB is often enough for recent items.
+```
+
+## With a user-agent (some feeds require it)
+
+```bash
+curl -sL -A "Mozilla/5.0 (compatible; Agent/1.0)" "https://example.com/feed.xml" | head -c 50000
+```
+
+## Tips
+
+- Feed URLs often end in `/feed`, `/rss`, `/feed.xml`, or `/atom.xml`. If the user gives a site URL, try appending `/feed` or `/rss`.
+- Output is XML; the agent can summarize titles and links from `<title>`, `<link>`, `<item>` (RSS) or `<entry>` (Atom).
+- For "latest posts" or "recent from …", fetch the feed and report the first few items (title + link).

package/data/skills/sulala-portal/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: sulala-portal
+description: Use your Sulala Portal connections (Gmail, Google Docs, etc.) via the Portal Gateway API. List and use OAuth-connected accounts.
+base_url_env: PORTAL_GATEWAY_URL
+credentials:
+  - PORTAL_API_KEY
+auth_scheme: Bearer
+auth_location: header
+auth_param: Authorization
+---
+
+# Sulala Portal Connection Skill
+
+**For listing connections, Gmail, or any Portal Gateway request: use the tool `sulala-portal_request` only.** Do not use other tools whose names end in `_request` (e.g. weather-geocode_request) for connections or Portal — they call different APIs and will return 404.
+
+When the user says "list connection(s)" or "list connections": call **sulala-portal_request** with `{ "method": "GET", "path": "connections" }` immediately. Do not use echo, memory_search, or memory_write for this — only sulala-portal_request returns the actual Portal connections.
+
+## How to call
+
+Use the generic request tool for this skill:
+
+- **Tool id**: `sulala-portal_request`
+- **Method**: `GET` (list) or `POST` (connect, get token, provider actions)
+- **Path**: relative to the gateway base (e.g. `connections`, `connections/{id}/use`). No leading slash.
+- **Query** (optional): object, e.g. `{ "provider": "gmail" }` if the API supports filtering.
+- **Body** (optional): for POST, e.g. `{ "provider": "gmail" }` for connect, or provider-specific payload.
+
+Example — list all connections:
+
+```json
+{
+  "method": "GET",
+  "path": "connections"
+}
+```
+
+Example — list connections (filter by provider if supported):
+
+```json
+{
+  "method": "GET",
+  "path": "connections",
+  "query": { "provider": "gmail" }
+}
+```
+
+Example — get access token: use the connection’s `id` (UUID) from the list in the path. If you get 404, try the connection’s `connection_id` (e.g. `conn_gmail_...`) in the path instead.
+
+```json
+{
+  "method": "POST",
+  "path": "connections/{id}/use"
+}
+```
+
+## Configuration (runtime)
+
+Set these in your environment or in the agent/skill config (e.g. `~/.agent-os/configs/sulala-portal.json` or env vars):
+
+- **PORTAL_GATEWAY_URL** — Base URL of the Portal Gateway (e.g. `https://portal.sulala.ai/api/gateway`). No trailing slash.
+- **PORTAL_API_KEY** — Your Portal API key used to authenticate requests.
+
+Get **PORTAL_API_KEY** from [portal.sulala.ai](https://portal.sulala.ai) → Account / Developer / Settings → create or copy an API key. Connections (Gmail, Docs, etc.) are managed in the same portal; connect accounts there, then use this skill to list and use them via the API.
+
+---
+
+## Portal Gateway API reference
+
+All paths below are relative to the gateway base (PORTAL_GATEWAY_URL). Use them in the `path` field of sulala-portal_request.
+
+### Connections
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `connections` | List the tenant's connections. Response: `{ connections: Array<{ id, connection_id, provider, created_at }> }`. |
+| POST | `connect` | Start OAuth for a provider. Body: `{ "provider": string, "redirect_success"?: string }` (e.g. provider `"gmail"`, `"github"`). Response: `{ authUrl, connectionId }`. Redirect user to authUrl. 402 = free plan limit. |
+| POST | `connections/:id/use` | Get an access token for a connection (for agent or backend). Response: `{ connectionId, provider, accessToken, scopes }`. 404 = not found or not owned. **If 404, try `connection_id` from the list in the path instead of `id`.** |
+| DELETE | `connections/:id` | Disconnect and remove the connection. Response: `{ ok: true }`. 404 = not found or access denied. |
+
+### Provider-specific actions (same auth)
+
+| Method | Path | Body | Description |
+|--------|------|------|-------------|
+| POST | `connections/:id/bsky-create-post` | `{ text, imageBase64?, imageMimeType?, alt? }` | Create a Bluesky post. |
+| POST | `connections/:id/bsky-request` | As required by integrations API | Bluesky XRPC proxy (DPoP-bound). |
+| POST | `connections/:id/youtube-upload` | `{ title, description?, privacyStatus?, video_url }` | Upload a video to YouTube. |
+
+All return integration-specific success/error payloads; 404 if connection not found or not owned. After listing, filter the `connections` array by `provider === "gmail"` (or use query if the API supports it).
+
+## Base URL
+
+The base URL is **not** set in the skill. Configure **PORTAL_GATEWAY_URL** where the agent runs (e.g. `https://portal.sulala.ai/api/gateway`). The loader uses that value at runtime so the skill never contains a hardcoded integration URL.

package/data/skills/translate/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: translate
+description: Translate text to another language (e.g. via LibreTranslate). Use when the user says "translate this to [language]", "translate the above to Spanish", "translate to French", "how do you say X in Y".
+metadata:
+  clawdbot:
+    emoji: "🌐"
+    requires:
+      bins:
+        - curl
+---
+
+# Translate
+
+Use **curl** to call a translation API. **LibreTranslate** is free and open; public instances exist. No API key for many instances.
+
+## LibreTranslate (POST)
+
+Most instances use the same API. Replace `https://libretranslate.com` with another instance if needed.
+
+**Translate text:**
+
+```bash
+curl -s -X POST "https://libretranslate.com/translate" \
+  -H "Content-Type: application/json" \
+  -d '{"q":"Hello world","source":"en","target":"es"}'
+```
+
+Response: `{"translatedText":"Hola mundo"}`. Use **jq** to extract: `... | jq -r '.translatedText'`.
+
+**Parameters:**
+
+- `q` — text to translate
+- `source` — source language code (e.g. `en`, `fr`, `auto` for auto-detect)
+- `target` — target language code (e.g. `es`, `de`, `ja`)
+
+**Example with jq:**
+
+```bash
+curl -s -X POST "https://libretranslate.com/translate" \
+  -H "Content-Type: application/json" \
+  -d '{"q":"Hello world","source":"en","target":"es"}' | jq -r '.translatedText'
+```
+
+## Language codes (common)
+
+`en` English · `es` Spanish · `fr` French · `de` German · `it` Italian · `pt` Portuguese · `ja` Japanese · `zh` Chinese · `ko` Korean · `ar` Arabic · `ru` Russian.
+
+## Tips
+
+- Escape quotes in the JSON body for the shell (e.g. `\"` or use single quotes around the string and escape only inner quotes).
+- If the default instance is rate-limited, try another public LibreTranslate instance or document an optional config for API URL/key.
+- For "translate this to Spanish", set `target` to `es` and put the user's text in `q`; use `source: "auto"` if the source language is unknown.