abtars 0.1.0-alpha.1

package/core/skills/tools/fxtwitter/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: twitter
+description: Fetch tweets and monitor AI influencers via FXTwitter API + web search. No API keys needed for single tweets.
+user-invocable: false
+---
+
+# Twitter / X
+
+Fetch Twitter/X content without API keys using the free FXTwitter API. No timeline/search endpoint — use web search for discovery, FXTwitter for structured data.
+
+## Follow list
+
+AI influencers and researchers we track:
+- **Follow list:** `~/.abtars/workspace/twitterX/follows.json` — curated, manually maintained
+
+Read the follow list before searching to target the right accounts.
+
+## Pipeline
+
+1. Read follow list: `cat ~/.abtars/workspace/twitterX/base.follows.json`
+2. Search for recent tweets: `web_search("site:x.com from:handle 2026")`
+3. Extract tweet ID from URL: `https://x.com/{user}/status/{id}`
+4. Fetch structured data: `curl -s "https://api.fxtwitter.com/{user}/status/{id}"` → JSON with text, author, likes, retweets, views, media, createdAt
+5. Compile results
+
+## Endpoints
+
+- **Tweet:** `GET https://api.fxtwitter.com/{screen_name}/status/{tweet_id}`
+- **Tweet + translation:** `GET https://api.fxtwitter.com/{screen_name}/status/{tweet_id}/{lang_code}`
+- **User profile:** `GET https://api.fxtwitter.com/{screen_name}` → name, bio, followers, verification
+
+## Error codes
+
+200=OK, 401=private tweet, 404=deleted/not found, 500=backend error
+
+## Use cases
+
+- "What's new in AI today?" → read follow list, search recent tweets from top handles
+- "What did @karpathy say about X?" → search + fetch specific tweets
+- "Find interesting AI threads" → search follow list handles, rank by engagement
+- User shares a tweet URL → fetch via FXTwitter for structured data
+
+## Limitations
+
+- No search endpoint (use web search instead)
+- No timeline endpoint (search per handle)
+- No auth required, no posting
+- Rate limits are generous but undocumented
+
+## Full integration plan
+
+See `docs/specs/twitter-integration.plan.md` for the `abtars-tweet` CLI roadmap (rettiwt-api, daily newsletter, discovery).

package/core/skills/tools/gmail/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: gmail
+description: Read and manage Gmail via gws-cli
+user-invocable: false
+---
+
+# Gmail Access
+
+Read, search, and manage emails using `gws-cli gmail`. Auth is pre-configured.
+
+## Commands
+
+```bash
+# List unread emails
+gws-cli gmail list -q "is:unread" -n 20
+
+# Read a message by ID
+gws-cli gmail read MSG_ID
+
+# Search
+gws-cli gmail search -q "from:someone subject:invoice"
+
+# Mark as read
+gws-cli gmail mark-read MSG_ID
+
+# Mark as unread
+gws-cli gmail mark-unread MSG_ID
+```
+
+## Search query syntax
+
+Standard Gmail operators: `from:`, `to:`, `subject:`, `is:unread`, `newer_than:1d`, `has:attachment`, `label:`, `after:2026/03/01`.
+
+## When checking emails
+
+1. `gws-cli gmail list -q "is:unread" -n 20`
+2. For each unread email: `gws-cli gmail read <id>`, then send a SHORT summary to the user as a separate message (one message per email)
+3. Summary format: **From:** / **Subject:** / 1-2 sentence gist
+4. Do NOT create files, reports, or .md documents — deliver summaries directly in chat
+5. After summarizing, mark as read: `gws-cli gmail mark-read <id>`
+
+## Rules
+- Never delete or trash emails without explicit user request
+- If no unread emails, do not send any message — stay silent

package/core/skills/tools/irc-chat/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: irc-chat
+description: Participate in IRC channels when the bridge has irc.json configured. Post on user request, respond to @mentions and the user, coordinate with other bots on shared channels.
+requires: abtars
+---
+
+# IRC Chat Participation
+
+You can participate in IRC channels. The bridge's IRC connections are defined in `~/.abtars/config/irc.json`. Each server entry lists channels you're configured for, with nick and mode per channel.
+
+## How to find your IRC context
+
+```bash
+cat ~/.abtars/config/irc.json
+```
+
+The file has `servers[]`, each with `id`, `host`, `nick`, and `channels{}`. For each channel:
+- `mode`: `"plain"` or `"secure"` (secure = Ed25519-signed, plain = unauthenticated)
+- `requireMention`: `true` = only respond when your nick is mentioned
+- `allowFrom`: nicks whose messages you will react to (others are ignored even if addressed to you)
+- `trustedKeys`: (secure mode only) map of nick → Ed25519 public key
+
+If no `irc.json` or no servers, IRC is inactive for this bridge.
+
+## When to post
+
+**Post only when the user explicitly asks:**
+- "post to IRC that the deploy is done"
+- "tell the #bridges channel I'm restarting"
+- "announce on IRC: ..."
+
+The platform adapter handles tool invocation — you don't call raw IRC commands. Use the same outbound message channel you'd use for any reply; the adapter routes to IRC when the user's prompt came from IRC.
+
+**Don't post proactively** unless the user configured you to (e.g. a cron'd status broadcast). Spontaneous IRC posts from an LLM are noise.
+
+## When to respond
+
+- An inbound IRC message mentioned your nick (adapter filtered it already — if it reached you, it's addressed to you)
+- The sender is in `allowFrom` for that channel (adapter filtered)
+- Keep replies short — one or two lines. IRC is a ticker, not a chat window
+
+If you're uncertain whether to respond, don't. A missed reply is recoverable; a noisy loop between bots is not.
+
+## Channel awareness
+
+You may be on multiple channels. The inbound message carries its channel — respond on the same channel unless the user says otherwise. Don't cross-post.
+
+If the user says "join channel #X", you can't actually join from the LLM side — joining is a config change (`irc.json`). Tell the user: "To join #X, add it under the appropriate server in `~/.abtars/config/irc.json` and restart. I can describe the config shape if you want."
+
+## Message format
+
+- Plain text. No markdown (IRC doesn't render it).
+- One line per message. The adapter splits long outputs automatically, but keep replies short on purpose — IRC lines above ~340 chars on secure channels get truncated.
+- No emojis unless you know the channel supports UTF-8 (most modern servers do, but older clients break).
+
+## Signatures (secure channels)
+
+Secure channels require Ed25519 signatures. **You do not sign anything manually** — the adapter layer signs every outbound message on secure channels automatically using the bot's private key from `.env`.
+
+- Secure channels are bot-to-bot (humans can't sign in their IRC client).
+- If you receive a message on a secure channel that fails verification, the adapter drops it before you see it — you'll never be tricked into replying to a spoofed sender.
+- Don't try to embed signature-like tags in your replies (`[sig:...]`). The adapter does that.
+
+## What NOT to do
+
+- Don't relay private conversations (user-to-you) to IRC without explicit instruction
+- Don't quote secrets, tokens, file paths, or PII — IRC messages may be logged or world-readable depending on server
+- Don't chat with another bot unprompted. A brief acknowledgement to coordinate is fine; small talk is not
+- Don't respond with long code blocks — commit to git and reference the SHA
+- Don't ignore `allowFrom` or `requireMention` — the adapter respects these, and if a message reached you, trust that it should be answered
+
+## Interaction with peer_ask (a2a-communication)
+
+These are separate tools for different purposes:
+
+| | peer_ask (a2a-communication) | IRC |
+|---|---|---|
+| Model | Sync RPC | Async broadcast |
+| Audience | One peer | Whole channel |
+| Visibility | Log-only | Human-watchable (via IRC client) |
+| Use when | You need an answer from a specific peer | User asks you to announce / converse on a channel |
+
+If the user says "ask <peer> what time it is" → use `peer_ask`.
+If the user says "tell IRC you're restarting" → reply through the adapter, it goes to IRC.

package/core/skills/tools/linear/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: linear
+description: Manage Linear projects, issues, and tasks via the bundled Node CLI and the official Linear API. Use when you need to read, create, update, or organize Linear issues, projects, teams, milestones, comments, cycles, labels, and documents.
+metadata: {"gracebot":{"always":false,"emoji":"📐","homepage":"https://github.com/MaTriXy/linear-skill","requires":{"bins":["node","npm"],"env":["LINEAR_API_KEY"]},"primaryEnv":"LINEAR_API_KEY","install":[{"id":"node-brew","kind":"brew","formula":"node","bins":["node","npm"],"label":"Install Node.js (brew)"}]},"clawdbot":{"always":false,"emoji":"📐","homepage":"https://github.com/MaTriXy/linear-skill","requires":{"bins":["node","npm"],"env":["LINEAR_API_KEY"]},"primaryEnv":"LINEAR_API_KEY","install":[{"id":"node-brew","kind":"brew","formula":"node","bins":["node","npm"],"label":"Install Node.js (brew)"}]}}
+---
+
+# Linear Workflow Management
+
+Manage Linear issues and projects through the bundled CLI at `{baseDir}/scripts/linear-cli.js`.
+
+## Scope and Runtime Model
+
+- This skill runs `node {baseDir}/scripts/linear-cli.js ...`.
+- The CLI uses the official `@linear/sdk`.
+- Authentication is `LINEAR_API_KEY` from the local environment.
+- Expected API destination is Linear GraphQL (`https://api.linear.app/graphql`) through the official SDK.
+
+## Prerequisites
+
+1. Node.js and npm are installed.
+2. Install script dependencies once:
+   - `cd {baseDir}/scripts && npm install`
+3. Set your API key:
+   - `export LINEAR_API_KEY="lin_api_..."`
+
+If dependencies or `LINEAR_API_KEY` are missing, stop and complete setup before issue/project operations.
+
+## Authentication and Credentials
+
+- Required credential: `LINEAR_API_KEY`.
+- Get it from `https://linear.app/settings/api`.
+- Use least-privilege access and a dedicated token for automation.
+
+## Required Workflow
+
+1. Clarify intent and scope:
+   - Team/project, labels, cycle, assignee, due date, priority.
+2. Read current state first:
+   - List/get issues, projects, statuses, labels, users, cycles.
+3. Apply mutations second:
+   - Create/update issues, comments, projects, milestones, labels.
+4. Summarize exactly what changed:
+   - Mention IDs, states, assignees, blockers, and follow-up actions.
+
+## Command Coverage
+
+- Teams and projects:
+  `teams`, `projects`, `createProject`
+- Issues:
+  `issues`, `issue`, `createIssue`, `updateIssue`
+- Comments:
+  `createComment`
+- States and labels:
+  `states`, `labels`
+- User:
+  `user`
+
+## Quick Examples
+
+```bash
+node {baseDir}/scripts/linear-cli.js teams
+node {baseDir}/scripts/linear-cli.js projects
+node {baseDir}/scripts/linear-cli.js issues
+node {baseDir}/scripts/linear-cli.js issue ENG-123
+node {baseDir}/scripts/linear-cli.js createIssue "Title" "Description" "team-id" '{"priority":2}'
+node {baseDir}/scripts/linear-cli.js updateIssue "issue-id" '{"stateId":"state-id"}'
+```
+
+## Practical Workflows
+
+- Triage urgent bugs:
+  list high-priority open issues, assign owners, move state to `In Progress`, add triage comments.
+- Sprint planning:
+  review cycle scope, create missing issues, set priorities and estimates, align assignees.
+- Release prep:
+  verify blockers, update project status, create milestone tasks, add rollout comments.
+- Documentation cleanup:
+  find stale docs/issues, open follow-up tasks, link related records.
+
+## Safety and Operational Rules
+
+- Never invent IDs; fetch and confirm before updates.
+- Prefer narrow updates over broad bulk edits.
+- For bulk edits, explain grouping logic before applying changes.
+- Do not include secrets in issue comments or descriptions.
+- Do not send data to endpoints outside Linear API scope for this skill.
+
+## References
+
+- `references/API.md` for priority values and workflow patterns.

package/core/skills/tools/mcporter/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: mcporter
+description: Call external MCP servers via the mcporter CLI. Use for accessing tools from services like Context7, Linear, GitHub, Notion, etc.
+---
+
+# mcporter — MCP Tool Access
+
+Use `mcporter` to discover and call tools on external MCP servers.
+
+## List available servers
+
+```bash
+mcporter list
+```
+
+## List tools on a specific server
+
+```bash
+mcporter list <server> --schema
+```
+
+## Call a tool
+
+```bash
+mcporter call <server>.<tool> key=value key2=value2
+```
+
+## Examples
+
+```bash
+# Resolve a library ID on Context7
+mcporter call context7.resolve-library-id libraryName=react
+
+# Get library docs
+mcporter call context7.get-library-docs context7CompatibleLibraryID=/websites/react_dev topic=hooks
+
+# Search Linear
+mcporter call linear.search_documentation query="automations"
+```
+
+## Notes
+
+- Config: `~/workspace/mcporter/config/mcporter.json`
+- Auto-imports configs from Cursor, Claude, Codex, VS Code
+- For OAuth servers, run `mcporter auth <server>` first
+- Use `--output json` for machine-readable results

package/core/skills/tools/model-scout/SKILL.md

@@ -0,0 +1,132 @@
+# Model Scout
+
+Find the best free cloud models and propose the top 3 candidates.
+
+## When to use
+User asks about model recommendations, best deals, or you need to evaluate if a better model is available.
+
+## Config files
+
+- **models.json** — `~/.abtars/config/models.json` (hot-reloaded)
+- **transport.json** — `~/.abtars/config/transport.json` (lists providers, defaults, fallbackChain)
+
+## transport.json provider fields (relevant to scouting)
+
+Each provider in `transport.json` may have:
+- **`defaults`** — `Record<agent, { model, fallbacks? }>` — preset models loaded on `/model change → provider`. Professor is required; missing subagents inherit professor's model.
+- **`fallbackChain`** — `string[]` — ordered list of always-available models tried when the configured model fails. Used by subagent runtime (not professor).
+
+When proposing new models, consider whether they should be added to a provider's `defaults` or `fallbackChain`.
+
+## models.json schema
+
+```json
+{
+  "model-id": {
+    "contextWindow": 262144,
+    "maxOutput": 16384,
+    "rank": 2,
+    "cost": { "input": 0.0, "output": 0.0 },
+    "transports": ["ollama", "openrouter"],
+    "description": "High IQ free model, top Intelligence Index score",
+    "validatedAt": "2026-04-13"
+  }
+}
+```
+
+- **rank**: 1 = frontier, 2 = strong, 3 = good, 4 = basic, 5 = minimal
+- **cost**: per million tokens in USD. `0.0` = free
+- **transports**: provider names from transport.json that can serve this model
+- **description**: why this model was added (scout writes this)
+- **validatedAt**: date when last verified alive (auto-set by script)
+
+## Scouting workflow
+
+### 1. Scan available free models
+
+```bash
+# OpenRouter free tier
+python3 {baseDir}/scout-openrouter.py
+
+# Ollama cloud models (no local, cloud only)
+python3 {baseDir}/scout-ollama.py
+```
+
+### 2. Research quality
+
+Browse leaderboards to get Intelligence Index scores:
+```bash
+abtars-browser --action navigate --url "https://artificialanalysis.ai/leaderboards/models"
+abtars-browser --action extract_text --max-chars 5000
+```
+
+Search for new cloud models on Ollama:
+```bash
+abtars-browser --action navigate --url "https://ollama.com/search?q=cloud"
+abtars-browser --action extract_text --max-chars 5000
+```
+
+### 3. Propose top 3
+
+After scanning and researching, propose exactly 3 candidates ranked by:
+
+1. **Intelligence Index** (higher = better) → determines rank
+2. **Context window** (bigger = fewer compactions)
+3. **Tool calling** (required — model must support function calling)
+4. **Throughput** (tokens/sec, matters for interactive use)
+
+Format:
+```
+🏆 Top 3 free cloud models:
+
+1. model-name (provider) — Intelligence: XX, Context: XXK
+   Why: [one sentence reason]
+
+2. model-name (provider) — Intelligence: XX, Context: XXK
+   Why: [one sentence reason]
+
+3. model-name (provider) — Intelligence: XX, Context: XXK
+   Why: [one sentence reason]
+```
+
+### 4. Add approved models
+
+After user approves, add with description explaining why:
+
+```bash
+python3 {baseDir}/scout-add-model.py \
+  "model-id" contextWindow maxOutput rank input_cost output_cost \
+  "Why this model: Intelligence XX, free, large context" \
+  ollama openrouter
+```
+
+The script automatically:
+- Backs up models.json to `.old`
+- Sets `validatedAt` to today's date
+- Validates all entries after write
+- Restores from backup if validation fails
+
+### 5. Test
+
+```
+/model change → pick provider → verify defaults loaded
+/model (check fallback chain displayed)
+```
+
+## Liveness test
+
+Before proposing, verify the model actually responds:
+
+```bash
+# Ollama cloud
+curl -s http://localhost:11434/v1/chat/completions -d '{
+  "model": "model-name",
+  "messages": [{"role":"user","content":"Say hi"}],
+  "max_tokens": 5
+}'
+
+# OpenRouter
+curl -s https://openrouter.ai/api/v1/chat/completions \
+  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
+  -d '{"model":"model-id","messages":[{"role":"user","content":"Say hi"}],"max_tokens":5}'
+```

package/core/skills/tools/model-scout/scout-add-model.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""scout-add-model.py — Add or update a model in models.json.
+
+Usage:
+  scout-add-model.py MODEL_ID CTX_WINDOW MAX_OUTPUT RANK INPUT_COST OUTPUT_COST "DESCRIPTION" TRANSPORT [TRANSPORT...]
+
+Example:
+  scout-add-model.py "nemotron-3-super:cloud" 262144 16384 2 0.0 0.0 "Nvidia 120B MoE, free" ollama openrouter
+"""
+import json, sys, shutil
+from pathlib import Path
+from datetime import date
+
+MODELS_PATH = Path.home() / ".abtars" / "config" / "models.json"
+REQUIRED = {"contextWindow", "maxOutput", "rank", "cost", "transports"}
+
+def main():
+    if len(sys.argv) < 8:
+        print(__doc__.strip(), file=sys.stderr)
+        sys.exit(2)
+
+    model_id = sys.argv[1]
+    ctx = int(sys.argv[2])
+    max_out = int(sys.argv[3])
+    rank = int(sys.argv[4])
+    in_cost = float(sys.argv[5])
+    out_cost = float(sys.argv[6])
+    desc = sys.argv[7]
+    transports = sys.argv[8:]
+
+    if not transports:
+        print("Error: at least one transport required", file=sys.stderr)
+        sys.exit(2)
+
+    backup = MODELS_PATH.with_suffix(".json.old")
+    shutil.copy2(MODELS_PATH, backup)
+
+    with open(MODELS_PATH) as f:
+        models = json.load(f)
+
+    models[model_id] = {
+        "contextWindow": ctx,
+        "maxOutput": max_out,
+        "rank": rank,
+        "cost": {"input": in_cost, "output": out_cost},
+        "transports": transports,
+        "description": desc,
+        "validatedAt": str(date.today()),
+    }
+
+    # Validate all entries
+    for mid, m in models.items():
+        missing = REQUIRED - set(m.keys())
+        if missing:
+            print(f"Validation failed: {mid} missing {missing}. Restoring backup.", file=sys.stderr)
+            shutil.copy2(backup, MODELS_PATH)
+            sys.exit(1)
+
+    with open(MODELS_PATH, "w") as f:
+        json.dump(models, f, indent=2)
+        f.write("\n")
+
+    free = "FREE" if in_cost == 0 and out_cost == 0 else f"${in_cost}/{out_cost}"
+    print(f"✓ {model_id} (rank {rank}, ctx {ctx//1024}K, {free}, via {transports})")
+
+if __name__ == "__main__":
+    main()

package/core/skills/tools/model-scout/scout-ollama.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""List Ollama cloud models (free, no local GPU needed) + local installed.
+Fetches from ollama.com library API for cloud models.
+Usage:
+  scout-ollama.py          # list only
+  scout-ollama.py --test   # list + liveness test cloud models + write status
+"""
+import json, os, sys, urllib.request
+
+config_dir = os.path.expanduser("~/.abtars/config")
+models_path = os.path.join(config_dir, "models.json")
+do_test = "--test" in sys.argv
+
+# Load current catalog
+try:
+    catalog = json.load(open(models_path))
+except Exception:
+    catalog = {}
+cataloged = {k for k in catalog if "ollama" in catalog[k].get("transports", [])}
+
+# --- Cloud models from ollama.com ---
+print("=== Ollama Cloud Models (free) ===")
+print(f"{'Model':<45} {'Status'}")
+print("-" * 60)
+
+try:
+    req = urllib.request.Request(
+        "https://ollama.com/search?c=cloud",
+        headers={"User-Agent": "abtars-scout/1.0"}
+    )
+    import re
+    html = urllib.request.urlopen(req, timeout=10).read().decode()
+    cloud_names = list(dict.fromkeys(re.findall(r'href="/library/([^"]+)"', html)))
+    cloud_models = [{"name": f"{n}:cloud"} for n in cloud_names]
+except Exception as e:
+    # Fallback: check local tags for :cloud suffix
+    cloud_models = []
+    print(f"  (ollama.com scrape failed: {e}, falling back to local tags)")
+
+# If API didn't work, check local tags for :cloud suffix
+if not cloud_models:
+    try:
+        local_data = json.loads(urllib.request.urlopen("http://localhost:11434/api/tags", timeout=5).read())
+        cloud_models = [{"name": m["name"]} for m in local_data.get("models", []) if ":cloud" in m["name"]]
+    except Exception:
+        pass
+
+from datetime import date
+today = date.today().isoformat()
+
+for m in cloud_models:
+    name = m["name"] if isinstance(m, dict) else m
+    if not name.endswith(":cloud") and ":cloud" not in name:
+        name = f"{name}:cloud"
+    status = "✓ cataloged" if name in cataloged else "NEW"
+
+    # Liveness test
+    if do_test and status == "NEW":
+        try:
+            test_data = json.dumps({"model": name, "messages": [{"role": "user", "content": "hi"}], "max_tokens": 5}).encode()
+            test_req = urllib.request.Request(
+                "http://localhost:11434/v1/chat/completions",
+                headers={"Content-Type": "application/json"},
+                data=test_data
+            )
+            resp = json.loads(urllib.request.urlopen(test_req, timeout=15).read())
+            content = resp.get("choices", [{}])[0].get("message", {}).get("content", "")
+            alive = bool(content.strip())
+        except Exception:
+            alive = False
+        status = f"{'✓ alive' if alive else '✗ dead'}"
+
+        if name not in catalog:
+            catalog[name] = {
+                "contextWindow": 262144, "maxOutput": 16384, "rank": 3,
+                "cost": {"input": 0.0, "output": 0.0},
+                "transports": ["ollama"],
+                "description": f"Ollama cloud model, scouted {today}",
+                "validatedAt": today, "status": "alive" if alive else "dead"
+            }
+        else:
+            catalog[name]["validatedAt"] = today
+            catalog[name]["status"] = "alive" if alive else "dead"
+
+    print(f"  {name:<43} {status}")
+
+# --- Local installed models ---
+print(f"\n=== Local Installed ===")
+print(f"{'Model':<45} {'Size':>8} {'Status'}")
+print("-" * 60)
+
+try:
+    local_data = json.loads(urllib.request.urlopen("http://localhost:11434/api/tags", timeout=5).read())
+    installed = local_data.get("models", [])
+except Exception:
+    installed = []
+    print("  (Ollama not reachable at localhost:11434)")
+
+try:
+    ps = json.loads(urllib.request.urlopen("http://localhost:11434/api/ps", timeout=5).read())
+    running = {m["name"] for m in ps.get("models", [])}
+except Exception:
+    running = set()
+
+for m in installed:
+    name = m["name"]
+    size_gb = m.get("size", 0) / 1e9
+    run_mark = " ▶" if name in running else ""
+    status = "✓ cataloged" if name in cataloged else "NEW"
+    print(f"  {name:<43} {size_gb:>6.1f}G{run_mark} {status}")
+
+if do_test:
+    with open(models_path, "w") as f:
+        json.dump(catalog, f, indent=2)
+        f.write("\n")
+    print(f"\n✓ models.json updated ({len(catalog)} entries)")