@buda-ai/connector 0.1.1 → 0.1.2

package/agent-templates/system-skills/buda-machine-info/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: buda-machine-info
+description: "Use this skill when the user asks about their Buda sandbox environment: CPU, memory, disk, OS, kernel, or installed software versions. Trigger on direct questions (\"how much RAM?\", \"what OS?\", \"check disk space\") and indirect ones (\"can this run Docker?\", \"am I out of memory?\", \"what tools are available?\"). Also use when troubleshooting resource constraints or deciding whether the sandbox can handle a workload, even without keywords like \"system info\" or \"specs\"."
+compatibility: Requires /proc/meminfo, /etc/os-release, lscpu, df, and common CLI tools (node, git, python3). Auto-available in Buda sandboxes.
+metadata:
+  author: buda
+  version: "1.0"
+---
+
+# System & Machine Information
+
+Retrieve hardware specs, resource usage, and installed tool versions for the
+current Buda sandbox environment.
+
+## When to use this skill
+
+- User asks about CPU, memory, disk, OS, or kernel details
+- User wants to know available disk space or memory
+- User asks what software versions are installed (Node, Python, Git, etc.)
+- User says "system info", "my specs", "what machine is this", "show environment"
+- User needs to troubleshoot resource constraints (out of memory, disk full)
+- User is deciding whether the sandbox can handle a workload
+
+## Step-by-step instructions
+
+1. Run the info script:
+
+```bash
+bash scripts/get-info.sh
+```
+
+2. Parse the output and present it to the user in a clear, readable format.
+3. If the user asked about a specific resource (e.g., "how much disk space"),
+   highlight the relevant section rather than dumping everything.
+
+## Output sections
+
+The script reports the following:
+
+| Section          | What it shows                                      |
+|------------------|----------------------------------------------------|
+| Operating System | Distro name and version (from `/etc/os-release`)   |
+| Kernel           | Linux kernel version (`uname -r`)                  |
+| CPU              | Model name and vCPU count                          |
+| Memory           | Total and available RAM in GB                      |
+| Disk Usage       | Mount point, total size, free space, usage percent  |
+| Versions         | Node.js, Git, and Python versions                  |
+
+## Baseline specs (Buda sandbox defaults)
+
+For quick reference when the user asks without needing a live check:
+
+- **OS:** Debian 12 (bookworm)
+- **CPU:** Intel Xeon Platinum 8488C (8 vCPUs)
+- **Memory:** 32 GB total
+- **Disk:** /agent (200 GB)
+
+Always prefer running the script for live data — these are just defaults that
+may vary by sandbox tier.
+
+## Tips
+
+- If the user asks "can I run X here?", run the script first, then assess
+  whether the available resources are sufficient.
+- When memory or disk is low, proactively suggest cleanup actions.
+- For version checks, if a specific tool is missing from the output, note that
+  it may not be installed and suggest how to install it.

package/agent-templates/system-skills/buda-machine-info/scripts/get-info.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+# system-info script
+echo "=== System Report $(date) ==="
+
+echo -e "\n[Operating System]"
+cat /etc/os-release | grep PRETTY_NAME | cut -d= -f2 | tr -d '"'
+
+echo -e "\n[Kernel]"
+uname -r
+
+echo -e "\n[CPU]"
+lscpu | grep "Model name" | sed 's/Model name: *//'
+echo "CPU(s): $(lscpu | grep '^CPU(s):' | awk '{print $2}')"
+
+echo -e "\n[Memory]"
+echo "Total: $(grep MemTotal /proc/meminfo | awk '{print $2/1024/1024 " GB"}')"
+echo "Available: $(grep MemAvailable /proc/meminfo | awk '{print $2/1024/1024 " GB"}')"
+
+echo -e "\n[Disk Usage]"
+df -h | grep -E '/$|/agent' | awk '{print $1, $6, $2, $4, $5, "used"}'
+
+echo -e "\n[Versions]"
+echo "Node: $(node -v)"
+echo "Git: $(git --version)"
+echo "Python: $(python3 --version)"

package/agent-templates/system-skills/buda-machine-info/scripts/send-file.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * send-file.mjs
+ *
+ * Resolves a file path relative to /agent and returns a [send:] marker
+ * if the file exists, or an empty string if it does not.
+ *
+ * Usage:
+ *   node scripts/send-file.mjs <path>
+ *
+ * Path rules (mirrors the system prompt convention):
+ *   - Relative path (no leading slash): resolved against /agent
+ *     e.g. "uploads/photo.jpg" → /agent/uploads/photo.jpg
+ *   - Absolute path starting with /agent: used as-is
+ *     e.g. "/agent/chart.png" → /agent/chart.png
+ *   - Any other absolute path: used as-is (escape hatch)
+ *
+ * Output:
+ *   [send:uploads/photo.jpg]   — file exists (path is relative to /agent)
+ *   (empty string)             — file does not exist
+ */
+
+import { existsSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+
+const AGENT_ROOT = "/agent";
+
+function resolveAgentPath(input) {
+  if (!input) return null;
+
+  // Strip a leading /agent prefix so the returned marker stays relative
+  if (input.startsWith("/agent/")) {
+    return { abs: input, rel: input.slice("/agent/".length) };
+  }
+
+  // Other absolute paths — use as-is, keep the full path in the marker
+  if (isAbsolute(input)) {
+    return { abs: input, rel: input };
+  }
+
+  // Relative path — resolve against /agent
+  const abs = resolve(AGENT_ROOT, input);
+  return { abs, rel: input };
+}
+
+const input = process.argv[2];
+
+if (!input) {
+  // No argument — print nothing (empty result)
+  process.exit(0);
+}
+
+const resolved = resolveAgentPath(input);
+
+if (!resolved || !existsSync(resolved.abs)) {
+  // File does not exist — return empty string
+  process.stdout.write("");
+  process.exit(0);
+}
+
+// File exists — emit the [send:] marker
+process.stdout.write(`[send:${resolved.rel}]`);

package/agent-templates/system-skills/buda-web-preview/SKILL.md

@@ -0,0 +1,462 @@
+---
+name: buda-web-preview
+description: "Use this skill when the user wants to create, view, run, or preview any web page, HTML file, game, landing page, demo, prototype, or frontend project."
+triggers: 
+  - "make a cat game"
+  - "create a landing page"
+  - "build a todo app"
+  - "Check HTML"
+  - "See HTML"
+  - "Preview HTML file"
+  - "show me a preview"
+  - "start a dev server"
+  - "run it in the background"
+  - "give me the link"
+  - "start a web server"
+  - "start http server"
+  - "serve the files"
+  - "run bun dev"
+  - "use browser"
+  - "use local browser"
+  - "open page"
+  - "做个小游戏"
+  - "做个网页"
+  - "帮我写个HTML"
+  - "打开HTML"
+  - "查看HTML"
+  - "搭个演示页面"
+  - "搭个网页应用"
+  - "使用浏览器"
+  - "本地浏览器"
+  - "打开浏览器"
+  - "启用Web服务"
+metadata:
+  author: buda
+  version: "1.3"
+---
+
+# Web Preview Skill
+
+Launch a live browser preview for any web page, game, or frontend project you create.
+
+Launch a live browser preview for any web page, HTML, when user want to use browser to check something.
+
+
+## When to use this skill
+
+Activate whenever the user wants to **see** something in a browser, not just read code:
+
+- "Make me a cat game" / "做个小猫游戏"
+- "Create a landing page" / "做个首页"
+- "Build a todo app" / "做个待办事项"
+- "Build a todo app" / "做个网页"
+- "Write me an HTML page" / "帮我写个HTML"
+- "Show me the HTML page" / "帮我查看HTML"
+- "Open Browser to open page" / " 使用浏览器去打开文件"
+- "open HTML file" / "打开HTML 文件"
+- "I want to see a demo" / "给我演示一下"
+- Any request for a game, animation, interactive component, or visual prototype
+
+## Core rule: Write files, don't paste code in chat
+
+**NEVER** return the full HTML/CSS/JS as a chat message. Always write it to real files.
+
+Users want to **see** it running — not read a code block.
+
+## Non-negotiable runtime rules
+
+1. **Always run dev servers in background**. Never run foreground commands that block the session.
+2. **Never assume a port** for framework dev servers. Parse the actual runtime output to detect it.
+3. **Call `get_preview_url`** After the server is reachable, call the `get_preview_url` tool with the detected port (and optional `path`). Buda opens the signed external preview in Local Browser. You may still print `http://localhost:PORT` in chat as a fallback.
+4. **Verify service health before announcing link**. Only print port + preview URL after a successful reachability check.
+5. **Always bind to `0.0.0.0`**, not `localhost` or `127.0.0.1`. This is required so the sandbox exposes the port to the external network, allowing users to open it in Local Browser. A server bound only to `127.0.0.1` is not reachable from outside the sandbox.
+5. **Restart means stop then start**. Kill previous process first, then launch a new one.
+6. **Use timeout-based polling**. Avoid infinite waits; fail fast with logs if startup is not ready.
+7. **Use a port between 3000 and 3999**. Always pick the preview port within the `3000`–`3999` range. If the chosen port is occupied, fall back to another free port in the same range.
+8. **Never hardcode working directory**. Derive paths relative to the project directory. Do not assume `/agent/` unless that is the actual project root.
+9. **Support multiple simultaneous dev servers**. PID/log files must be scoped per project (use a hash or sanitized project path), not a single global `/tmp/buda-preview.*`.
+10. **Read `buda.app.json` first**. If a `buda.app.json` exists in the project directory, read it to get the dev command, port, and other settings before falling back to defaults.
+
+## AI Browser vs Local Browser
+
+- Use this skill and `get_preview_url` when the user wants to preview a local dev server or generated app. Buda opens that preview in **Local Browser**.
+- Do not use AI Browser for sandbox localhost previews unless the user explicitly wants the AI-controlled CDP browser to visit the signed external preview URL.
+
+---
+
+## Step-by-step
+
+### 0. Check for `buda.app.json` (always do this first)
+
+Before starting any server, check if a `buda.app.json` exists in the project directory:
+
+```bash
+PROJECT_DIR="<absolute-path-to-project>"
+
+if [ -f "$PROJECT_DIR/buda.app.json" ]; then
+  echo "Found buda.app.json, reading config..."
+  cat "$PROJECT_DIR/buda.app.json"
+fi
+```
+
+Schema: `/system/.agents/skills/app-builder/buda.app.schema.json`
+
+
+Key fields to read for preview:
+
+| Field | Description |
+|---|---|
+| `framework` | `"static"` \| `"vite"` \| `"next"` — determines server strategy |
+| `port` | Dev server port (required for non-static) |
+| `scripts.install` | Dependency install command (e.g. `bun install`) |
+| `scripts.dev` | Dev server start command |
+
+
+Example — Vite app:
+
+```json
+{
+  "name": "my_app",
+  "version": "1.0.0",
+  "type": "web",
+  "description": "A Vite + React application",
+  "framework": "vite",
+  "port": 5173,
+  "scripts": {
+    "install": "bun install",
+    "dev": "./node_modules/.bin/vite --host 0.0.0.0",
+    "build": "./node_modules/.bin/tsc -b && ./node_modules/.bin/vite build",
+    "start": "./node_modules/.bin/vite preview --host 0.0.0.0"
+  }
+}
+```
+
+How to use it:
+
+- `framework: "static"` → serve the project directory with `npx serve`, no install step needed.
+- Otherwise → run `scripts.install` first, then `scripts.dev` as the start command.
+- Use `port` as the expected port (still verify reachability with curl).
+- If `buda.app.json` is absent, fall back to the standard detection logic below.
+
+---
+
+### Per-project runtime state files
+
+To support multiple dev servers running simultaneously, scope PID/log/URL files to the project. Use a short hash of the project path:
+
+```bash
+PROJECT_DIR="<absolute-path-to-project>"
+PROJECT_HASH="$(echo "$PROJECT_DIR" | md5sum | cut -c1-8)"
+
+PID_FILE="/tmp/buda-preview-${PROJECT_HASH}.pid"
+LOG_FILE="/tmp/buda-preview-${PROJECT_HASH}.log"
+URL_FILE="/tmp/buda-preview-${PROJECT_HASH}.url"
+```
+
+Never use a shared global `/tmp/buda-preview.pid` — doing so would cause one project's server to clobber another's.
+
+---
+
+### Stop existing preview process for a project (required before restart)
+
+```bash
+PROJECT_DIR="<absolute-path-to-project>"
+PROJECT_HASH="$(echo "$PROJECT_DIR" | md5sum | cut -c1-8)"
+PID_FILE="/tmp/buda-preview-${PROJECT_HASH}.pid"
+URL_FILE="/tmp/buda-preview-${PROJECT_HASH}.url"
+
+if [ -f "$PID_FILE" ] && kill -0 "$(cat "$PID_FILE")" 2>/dev/null; then
+  kill "$(cat "$PID_FILE")" 2>/dev/null || true
+  sleep 1
+  kill -9 "$(cat "$PID_FILE")" 2>/dev/null || true
+fi
+rm -f "$PID_FILE"
+
+# Optional: kill by previous detected port if still occupied
+if [ -f "$URL_FILE" ]; then
+  PORT="$(sed -E 's#.*:([0-9]+).*#\1#' "$URL_FILE")"
+  if [ -n "$PORT" ]; then
+    ss -ltnp "sport = :$PORT" 2>/dev/null \
+      | sed -nE 's/.*pid=([0-9]+).*/\1/p' \
+      | xargs -r kill 2>/dev/null || true
+  fi
+fi
+rm -f "$URL_FILE"
+```
+
+Run this stop block whenever:
+- user says "restart"
+- you need to re-run a server command
+- you suspect a stale preview process is still alive
+
+---
+
+### For static HTML pages (no framework needed)
+
+Use this when the user asks for a simple page, game, animation, or visual demo.
+
+**1. Write files**
+
+Write to the actual project directory. Do **not** hardcode `/agent/preview/`. Use the real path where the project lives:
+
+```
+<PROJECT_DIR>/index.html   ← always required
+<PROJECT_DIR>/style.css    ← when styling is needed
+<PROJECT_DIR>/script.js    ← when JS logic is needed
+```
+
+**2. Resolve start command and port**
+
+```bash
+PROJECT_DIR="<absolute-path-to-project>"
+PROJECT_HASH="$(echo "$PROJECT_DIR" | md5sum | cut -c1-8)"
+PID_FILE="/tmp/buda-preview-${PROJECT_HASH}.pid"
+LOG_FILE="/tmp/buda-preview-${PROJECT_HASH}.log"
+URL_FILE="/tmp/buda-preview-${PROJECT_HASH}.url"
+PORT=3000
+
+# Read buda.app.json if present
+if [ -f "$PROJECT_DIR/buda.app.json" ]; then
+  CFG_PORT="$(node -e "try{const c=require('$PROJECT_DIR/buda.app.json');process.stdout.write(String(c.port||''))}catch(e){}" 2>/dev/null)"
+  [ -n "$CFG_PORT" ] && PORT="$CFG_PORT"
+fi
+
+# Find a free port in 3000-3999 if chosen port is occupied
+while ss -ltn "sport = :$PORT" 2>/dev/null | grep -q ":$PORT"; do
+  PORT=$((PORT + 1))
+  [ "$PORT" -gt 3999 ] && PORT=3000
+done
+```
+
+**3. Start the preview server**
+
+```bash
+# Always stop old process first (restart-safe)
+if [ -f "$PID_FILE" ] && kill -0 "$(cat "$PID_FILE")" 2>/dev/null; then
+  kill "$(cat "$PID_FILE")" 2>/dev/null || true
+  sleep 1
+  kill -9 "$(cat "$PID_FILE")" 2>/dev/null || true
+fi
+ss -ltnp "sport = :$PORT" 2>/dev/null \
+  | sed -nE 's/.*pid=([0-9]+).*/\1/p' \
+  | xargs -r kill 2>/dev/null || true
+
+# Bind to 0.0.0.0 so the port is reachable from outside the sandbox
+nohup npx serve "$PROJECT_DIR" -l "0.0.0.0:$PORT" > "$LOG_FILE" 2>&1 &
+echo $! > "$PID_FILE"
+
+# Wait until reachable
+READY=0
+for _ in $(seq 1 30); do
+  if ! kill -0 "$(cat "$PID_FILE")" 2>/dev/null; then
+    echo "Preview process exited before becoming ready. Last log lines:"
+    tail -n 40 "$LOG_FILE" 2>/dev/null || true
+    break
+  fi
+  if curl -fsS --connect-timeout 2 --max-time 10 \
+      -o /dev/null "http://127.0.0.1:$PORT/"; then
+    URL="http://localhost:$PORT/"
+    echo "$URL" > "$URL_FILE"
+    echo "Preview ready on port $PORT"
+    echo "$URL"
+    READY=1
+    break
+  fi
+  sleep 1
+done
+if [ "$READY" != 1 ]; then
+  echo "Preview did not become reachable within 30s (port $PORT). Check $LOG_FILE"
+  tail -n 40 "$LOG_FILE" 2>/dev/null || true
+fi
+```
+
+**4. Open preview**
+
+Call `get_preview_url` with the detected port, for example:
+
+```json
+{ "port": 3000, "path": "/" }
+```
+
+**5. Reply**
+
+After writing files, starting the server, and calling `get_preview_url`, reply briefly:
+
+```
+✅ Preview launched!
+
+Buda opened the preview in Local Browser.
+```
+
+Then, ask the user if they'd like to deploy the web app — this feature is available on any purchased plan.
+
+Do **not** paste the full source code unless the user asks.
+
+---
+
+### For Node.js / framework projects (React, Vite, Next.js, Express...)
+
+Use this when the user asks for a React app, Express server, or any project with a `package.json`.
+
+**1. Scaffold the project**
+
+Create files under the actual project directory. Do **not** hardcode a working directory.
+
+**2. Resolve start command**
+
+```bash
+PROJECT_DIR="<absolute-path-to-project>"
+
+# Priority 1: buda.app.json
+DEV_CMD=""
+INSTALL_CMD=""
+if [ -f "$PROJECT_DIR/buda.app.json" ]; then
+  DEV_CMD="$(node -e "try{const c=require('$PROJECT_DIR/buda.app.json');process.stdout.write((c.scripts&&c.scripts.dev)||'')}catch(e){}" 2>/dev/null)"
+  INSTALL_CMD="$(node -e "try{const c=require('$PROJECT_DIR/buda.app.json');process.stdout.write((c.scripts&&c.scripts.install)||'')}catch(e){}" 2>/dev/null)"
+fi
+
+# Priority 2: package.json scripts.dev
+if [ -z "$DEV_CMD" ] && [ -f "$PROJECT_DIR/package.json" ]; then
+  HAS_DEV="$(node -e "try{const p=require('$PROJECT_DIR/package.json');process.stdout.write(p.scripts&&p.scripts.dev?'yes':'')}catch(e){}" 2>/dev/null)"
+  [ "$HAS_DEV" = "yes" ] && DEV_CMD="bun run dev"
+fi
+
+# Priority 3: fallback
+[ -z "$DEV_CMD" ] && DEV_CMD="bun run dev"
+[ -z "$INSTALL_CMD" ] && INSTALL_CMD="bun install"
+
+echo "Install: $INSTALL_CMD"
+echo "Dev:     $DEV_CMD"
+```
+
+**3. Install and start**
+
+```bash
+PROJECT_HASH="$(echo "$PROJECT_DIR" | md5sum | cut -c1-8)"
+PID_FILE="/tmp/buda-preview-${PROJECT_HASH}.pid"
+LOG_FILE="/tmp/buda-preview-${PROJECT_HASH}.log"
+URL_FILE="/tmp/buda-preview-${PROJECT_HASH}.url"
+
+cd "$PROJECT_DIR"
+$INSTALL_CMD
+
+# Always stop old process first (restart-safe)
+if [ -f "$PID_FILE" ] && kill -0 "$(cat "$PID_FILE")" 2>/dev/null; then
+  kill "$(cat "$PID_FILE")" 2>/dev/null || true
+  sleep 1
+  kill -9 "$(cat "$PID_FILE")" 2>/dev/null || true
+fi
+rm -f "$URL_FILE"
+
+nohup $DEV_CMD > "$LOG_FILE" 2>&1 &
+echo $! > "$PID_FILE"
+
+# Detect runtime URL from logs, then verify before announce
+URL=""
+for i in $(seq 1 60); do
+  URL="$(
+    sed -nE 's#.*(https?://(localhost|127\.0\.0\.1|0\.0\.0\.0):[0-9]+/?).*#\1#p' "$LOG_FILE" | tail -n 1
+  )"
+  if [ -n "$URL" ]; then
+    PORT="$(echo "$URL" | sed -E 's#.*:([0-9]+).*#\1#')"
+    if curl -fsS --connect-timeout 2 --max-time 10 -o /dev/null "http://127.0.0.1:$PORT/" \
+        || curl -fsS --connect-timeout 2 --max-time 10 -o /dev/null "$URL"; then
+      CANONICAL_URL="http://localhost:$PORT/"
+      echo "$CANONICAL_URL" > "$URL_FILE"
+      echo "Preview ready on port $PORT"
+      echo "$CANONICAL_URL"
+      break
+    fi
+  fi
+  sleep 1
+done
+
+# If no URL detected/verified, report failure with logs
+if [ -z "$URL" ]; then
+  echo "Dev server did not become ready in time. Check $LOG_FILE"
+  tail -n 40 "$LOG_FILE" 2>/dev/null || true
+fi
+```
+
+Important:
+- Do not output a preview link until a port is detected and reachable.
+- Reply with the preview link as plain text only; do not wrap it in `<code>`, or any other element, so buda can intercept it and open the preview.
+- If startup fails, share concise error + log file path.
+- For Vite, `--strictPort` may be used when you need a fixed port; otherwise parse the actual port from logs.
+- Never use `python3 http.server` as a web server.
+
+**4. Keep reply short** — same as static case.
+
+---
+
+## Common output patterns the system detects
+
+After the dev server starts (or restarts) successfully, check whether `scripts.dev` in `buda.app.json` matches the actual command used. If it differs, update it — if the file exists.
+
+After **every** dev/static server start, always print preview metadata in bash output.
+When the service restarts (manual restart, crash + restart, port switch), print it again.
+
+Required output on each (re)start:
+- `Preview time: 2026-04-14 10:32:11` (local time is fine)
+- `http://localhost:3000` ← preferred plain link line for click/open
+
+Compatible patterns the system can also detect:
+- `http://localhost:3000`
+- `Local:   http://localhost:3000` (Vite/Next.js)
+- `App listening on port 3000` (Express)
+- `Serving HTTP on 0.0.0.0 port 3000`
+
+Always make sure preview link output appears in bash logs for every (re)start, so users can click immediately.
+
+If logs don't print a URL, use a fallback probe (bounded by timeout):
+
+```bash
+for p in 3000 3001 4173 5173 8000 8080; do
+  if curl -fsS --connect-timeout 2 --max-time 10 -o /dev/null "http://127.0.0.1:$p/"; then
+    echo "Preview ready on port $p"
+    echo "http://localhost:$p/"
+    break
+  fi
+done
+```
+
+## Choosing between static vs Node
+
+| Situation                                      | Use                            |
+| ---------------------------------------------- | ------------------------------ |
+| Simple page, game, animation, landing page     | Static (npx serve)             |
+| User explicitly asks for React / Vue / Next.js | Node (bun run dev)             |
+| User asks for a backend / API                  | Node (Vite / Express / FastAPI)|
+| Prototype with vanilla JS                      | Static (npx serve)             |
+| When in doubt                                  | Ask user                       |
+
+## Updating the preview
+
+If the user wants changes:
+- Edit the file(s) directly
+- No need to restart the server for static HTML (just refresh the page)
+- For Node projects, hot reload usually handles it automatically
+
+If the user explicitly asks to restart:
+- Execute stop block first (kill old process and free old port)
+- Run startup flow again
+- Re-detect and re-verify port before replying with link
+
+## Tips
+
+- For games: use canvas or simple DOM — no framework needed
+- For landing pages: keep it self-contained in one HTML file when possible
+- Don't run `python3 http.server` as a web server
+- For complex projects: use Vite (`bun create vite`) for fast setup, always set `host: '0.0.0.0'` and `allowedHosts: true`
+- **Every server must bind to `0.0.0.0`** — this is what makes the sandbox port reachable externally so the user can open it in Local Browser
+
+```js
+// https://vite.dev/config/
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    host: '0.0.0.0',   // required — bind to all interfaces, not just localhost
+    allowedHosts: true  // required — allow sandbox external hostname
+  }
+})
+```