@buda-ai/connector 0.1.0 → 0.1.2

package/agent-templates/system-skills/app-builder/buda.app.schema.json

@@ -0,0 +1,165 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://buda.dev/schemas/buda.app.json",
+  "title": "Buda App Definition",
+  "description": "Declares to the Buda sandbox how to install, run dev, build, start, and optionally deploy a web app.",
+  "type": "object",
+  "required": ["name", "version", "type", "description", "framework"],
+  "additionalProperties": false,
+  "if": {
+    "required": ["framework"],
+    "properties": { "framework": { "const": "static" } }
+  },
+  "then": {
+    "description": "Static apps need no build tooling: drop files in public/ and omit scripts/port."
+  },
+  "else": {
+    "required": ["port", "scripts"]
+  },
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_]*$",
+      "description": "Machine-friendly app identifier in snake_case."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+",
+      "description": "Semantic version of the app definition."
+    },
+    "type": {
+      "type": "string",
+      "enum": ["web"],
+      "description": "App type. Currently only web is supported."
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200,
+      "description": "Short human-readable description of the app."
+    },
+    "framework": {
+      "type": "string",
+      "enum": ["static", "vite", "next"],
+      "description": "Framework identifier used by the Buda sandbox to apply framework-specific behavior. Use \"static\" for plain HTML/CSS/JS with no build step (files served from public/)."
+    },
+    "port": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 65535,
+      "description": "Dev server port number."
+    },
+    "scripts": {
+      "type": "object",
+      "required": ["install", "dev", "build", "start"],
+      "additionalProperties": false,
+      "description": "Shell commands aligned with package.json scripts.",
+      "properties": {
+        "install": {
+          "type": "string",
+          "description": "Install dependencies command (e.g. bun install)."
+        },
+        "dev": {
+          "type": "string",
+          "description": "Start the development server."
+        },
+        "build": {
+          "type": "string",
+          "description": "Production build command."
+        },
+        "start": {
+          "type": "string",
+          "description": "Start the production server or preview."
+        },
+        "lint": {
+          "type": "string",
+          "description": "Lint command (optional)."
+        }
+      }
+    },
+    "env": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      },
+      "description": "Default environment variables for the app."
+    },
+    "deploy": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Optional deployment overrides. Buda supplies Cloudflare Workers for Platforms defaults when omitted.",
+      "properties": {
+        "provider": {
+          "type": "string",
+          "enum": ["cloudflare-workers-for-platforms"],
+          "description": "Deployment provider. Defaults to Cloudflare Workers for Platforms."
+        },
+        "assets": {
+          "type": "string",
+          "description": "Static assets directory relative to the app folder. Defaults to public."
+        },
+        "entry": {
+          "type": "string",
+          "description": "Optional Worker module entry relative to the app folder. When omitted, Buda generates a static-assets Worker."
+        },
+        "compatibilityDate": {
+          "type": "string",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+          "description": "Cloudflare Worker compatibility date. Defaults to the Buda platform default."
+        },
+        "notFoundHandling": {
+          "type": "string",
+          "enum": ["single-page-application", "404-page", "none"],
+          "description": "Static asset fallback behavior. Defaults to single-page-application."
+        },
+        "scriptName": {
+          "type": "string",
+          "description": "Optional Cloudflare User Worker script name override. Buda derives a Space-scoped name when omitted."
+        }
+      }
+    }
+  },
+  "examples": [
+    {
+      "name": "my_page",
+      "version": "1.0.0",
+      "type": "web",
+      "description": "A plain static HTML page (no build step)",
+      "framework": "static"
+    },
+    {
+      "name": "my_app",
+      "version": "1.0.0",
+      "type": "web",
+      "description": "A Next.js web application",
+      "framework": "next",
+      "port": 3000,
+      "scripts": {
+        "install": "bun install",
+        "dev": "./node_modules/.bin/next dev",
+        "build": "./node_modules/.bin/next build",
+        "start": "./node_modules/.bin/next start"
+      },
+      "env": {
+        "NODE_ENV": "development"
+      }
+    },
+    {
+      "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"
+      },
+      "env": {
+        "NODE_ENV": "development"
+      }
+    }
+  ]
+}

package/agent-templates/system-skills/app-builder/evals/evals.json

@@ -0,0 +1,23 @@
+{
+  "skill_name": "web-app-builder",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Build me a small web app for tracking freelance invoices. I want to add clients, enter invoice amount/status, and see totals for paid vs unpaid. Use whatever frontend stack makes sense and give me a preview link.",
+      "expected_output": "Creates a working web app project with sensible stack selection, invoice/client UI, stateful interactions or local storage, build verification, and a live preview link.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "I already have a Vite React app in /agent/acme-dashboard. Add a responsive analytics dashboard page with cards, a filter, and a table. Don't rewrite the whole app.",
+      "expected_output": "Inspects existing project, preserves structure, adds dashboard components/styles, runs relevant verification, and summarizes changed files.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "做一个简单的网页应用：番茄钟 + 待办事项，能开始/暂停计时，任务可以勾选完成。要能在浏览器里打开。",
+      "expected_output": "Builds a browser-previewable pomodoro/todo app, likely static or Vite depending on complexity, with start/pause timer and task completion interactions.",
+      "files": []
+    }
+  ]
+}

package/agent-templates/system-skills/app-builder/scripts/check-preview-url.mjs

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+
+const FALLBACK_ORIGIN = "https://buda.im/";
+
+function printResult(label, value) {
+  const rendered = typeof value === "boolean" ? (value ? "yes" : "no") : value;
+  console.log(`${label}: ${rendered}`);
+}
+
+function parseUrl(input, label) {
+  try {
+    const url = new URL(input);
+    if (!/^https?:$/.test(url.protocol)) {
+      throw new Error(`Only http/https URLs are supported, got ${url.protocol}`);
+    }
+    return url;
+  } catch (error) {
+    throw new Error(`${label} is not a valid URL: ${error.message}`);
+  }
+}
+
+function extractPort(url) {
+  if (url.port) return Number(url.port);
+
+  // Buda preview URLs usually encode the local port as the hostname prefix:
+  // https://5173-t326d10d005fe029.budaapps.com -> 5173
+  const previewPort = url.hostname.match(/^(\d{2,5})-/)?.[1];
+  if (previewPort) return Number(previewPort);
+
+  return null;
+}
+
+function getHeader(headers, name) {
+  return headers.get(name) ?? "";
+}
+
+function evaluateCors(headers, requestedOrigin) {
+  const allowOrigin = getHeader(headers, "access-control-allow-origin");
+  const allowMethods = getHeader(headers, "access-control-allow-methods");
+  const allowCredentials = getHeader(headers, "access-control-allow-credentials");
+
+  return {
+    allowOrigin,
+    allowMethods,
+    allowCredentials,
+    passes:
+      allowOrigin === "*" ||
+      allowOrigin === requestedOrigin.origin ||
+      allowOrigin === requestedOrigin.href.replace(/\/$/, ""),
+  };
+}
+
+async function request(method, url, originUrl) {
+  const response = await fetch(url, {
+    method,
+    redirect: "manual",
+    headers: {
+      Origin: originUrl.origin,
+    },
+  });
+
+  return {
+    method,
+    url,
+    status: response.status,
+    ok: response.ok,
+    unauthorized: response.status === 401 || response.status === 403,
+    redirected: response.status >= 300 && response.status < 400,
+    location: getHeader(response.headers, "location"),
+    cors: evaluateCors(response.headers, originUrl),
+  };
+}
+
+function reportHttpResult(result) {
+  printResult(`${result.method} ${result.url} status`, result.status);
+  printResult(`${result.method} ${result.url} ok`, result.ok);
+  printResult(`${result.method} ${result.url} unauthorized`, result.unauthorized);
+
+  if (result.redirected) {
+    printResult(`${result.method} ${result.url} redirect location`, result.location || "(missing)");
+  }
+
+  printResult(
+    `${result.method} ${result.url} CORS allow-origin`,
+    result.cors.allowOrigin || "(none)",
+  );
+  printResult(
+    `${result.method} ${result.url} CORS allow-methods`,
+    result.cors.allowMethods || "(none)",
+  );
+  printResult(
+    `${result.method} ${result.url} CORS allow-credentials`,
+    result.cors.allowCredentials || "(none)",
+  );
+  printResult(`${result.method} ${result.url} CORS passes for origin`, result.cors.passes);
+}
+
+export async function checkUrl(targetUrlInput, options = {}) {
+  if (!targetUrlInput) {
+    throw new Error("checkUrl(url, options) requires a target URL.");
+  }
+
+  const targetUrl = parseUrl(targetUrlInput, "Target URL");
+  const originUrl = parseUrl(
+    options.origin ?? process.env.NEXT_PUBLIC_APP_URL ?? FALLBACK_ORIGIN,
+    "Origin URL",
+  );
+  const port = extractPort(targetUrl);
+  const localhostUrl = port === null ? null : `http://localhost:${port}/`;
+
+  const result = {
+    targetUrl: targetUrl.href,
+    origin: originUrl.origin,
+    port,
+    remoteHead: null,
+    localhostUrl,
+    localhostHead: null,
+  };
+
+  result.remoteHead = await request("HEAD", targetUrl.href, originUrl);
+
+  if (localhostUrl) {
+    result.localhostHead = await request("HEAD", localhostUrl, originUrl);
+  }
+
+  return result;
+}
+
+export function reportCheckResult(result) {
+  printResult("target URL", result.targetUrl);
+  printResult("origin", result.origin);
+  printResult("extracted port", result.port ?? "not found");
+
+  console.log("\nChecking remote URL with HEAD first...");
+  reportHttpResult(result.remoteHead);
+
+  if (result.remoteHead.status === 200) {
+    console.log("Remote HEAD returned 200.");
+  } else if (result.remoteHead.unauthorized) {
+    console.log("Remote URL returned unauthorized on HEAD.");
+  } else {
+    console.log(`Remote HEAD did not return 200; got ${result.remoteHead.status}.`);
+  }
+
+  if (!result.localhostUrl) {
+    console.log("\nSkipping localhost check because no port could be extracted.");
+    return;
+  }
+
+  console.log("\nChecking localhost:port with HEAD first...");
+  reportHttpResult(result.localhostHead);
+
+  if (result.localhostHead.status === 200) {
+    console.log("localhost:port is working with HEAD 200.");
+  } else if (result.localhostHead.unauthorized) {
+    console.log("localhost:port returned unauthorized on HEAD.");
+  } else {
+    console.log(`localhost:port HEAD did not return 200; got ${result.localhostHead.status}.`);
+  }
+}
+
+async function main() {
+  const targetInput = process.argv[2];
+  const originInput = process.argv[3];
+
+  if (!targetInput) {
+    console.error("Usage: node scripts/check-url.mjs <url> [origin]");
+    console.error(
+      "Example: node scripts/check-url.mjs https://5173-example.budaapps.com https://buda.im/",
+    );
+    process.exitCode = 2;
+    return;
+  }
+
+  const result = await checkUrl(targetInput, { origin: originInput });
+  reportCheckResult(result);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}

package/agent-templates/system-skills/buda-automations/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: buda-automations
+description: "Use this skill when the user wants to schedule, list, or delete recurring agent tasks in Buda. Trigger on explicit requests (\"create a daily automation\", \"set up a cron job\", \"show my scheduled tasks\", \"delete this automation\") and indirect signals (\"every morning\", \"once a day\", \"remind me weekly\", \"check every hour\", \"run this automatically\"). Also trigger when the user describes a repeated or timed action without using the word \"automation\"."
+compatibility: Requires the built-in Buda automation tools (create_automation, list_automations, delete_automation) — auto-injected in Buda sandboxes.
+metadata:
+  author: buda
+  version: "1.0"
+---
+
+# Automation Management
+
+Manage scheduled automations in the user's Buda workspace. An automation is a
+recurring (or one-time) task that triggers an agent session with a predefined
+prompt on a schedule.
+
+## When to use this skill
+
+- User asks to **create** a scheduled/recurring task ("Check the news for me every morning at 9am")
+- User asks to **list** existing automations ("What scheduled tasks do I have?")
+- User asks to **delete** an automation ("Remove the xxx scheduled task, I don't need it anymore")
+- Any mention of cron, interval, timer, reminder, periodic, recurring, daily,
+  weekly, hourly, or similar scheduling concepts
+
+## How it works
+
+Use the built-in Buda tools (`create_automation`, `list_automations`,
+`delete_automation`) — do **not** run the shell scripts in `scripts/`.
+The tools are always available in the sandbox and handle auth automatically.
+
+All operations are scoped to the current agent's workspace — you cannot
+accidentally touch other workspaces.
+
+**CRITICAL — timezone rule**: When using `--schedule-type cron`, write the cron expression in the user's local time and pass `--timezone` with the user's IANA timezone. The scheduler interprets the cron expression in that timezone and stores `nextRunAt` as an absolute timestamp.
+
+Example: user says "every day at 14:00" in Asia/Shanghai → `--cron "0 14 * * *" --timezone "Asia/Shanghai"`.
+
+## Subscription Limits
+
+Buda has different subscription plans that restrict how automations can be used. When a user tries to create an automation that exceeds their plan's limits, the API will return an error. You should be aware of these limits:
+
+| Plan | Cron Support (`allowCron`) | Max Automations (`maxCount`) | Minimum Interval (`minInterval`) |
+|------|----------------------------|------------------------------|----------------------------------|
+| **Free** | No (`false`) | 5 | 120 minutes |
+| **Plus** | Yes (`true`) | 20 | 30 minutes |
+| **Pro** | Yes (`true`) | 100 | 5 minutes |
+| **Enterprise**| Yes (`true`) | Unlimited | 1 minute |
+
+If a user hits a plan limit (e.g., they ask for a cron schedule or an interval less than 120 minutes on a Free plan), **do not just report the error**. You MUST offer actionable solutions:
+1. **Suggest an alternative that fits their current plan** (e.g., "Since you are on the Free plan, we can't use a specific time of day (cron). Would you like me to set this up to run every 120 minutes instead?").
+2. **Offer an upgrade path** (e.g., "If you need this to run at exactly 9am every day, you can upgrade your subscription to Plus or Pro in your Workspace Settings -> Billing").
+
+## Available operations
+
+| Operation | Tool                  | Description                          |
+|-----------|-----------------------|--------------------------------------|
+| List      | `list_automations`    | List all automations in workspace    |
+| Create    | `create_automation`   | Create a new scheduled automation    |
+| Delete    | `delete_automation`   | Delete an automation by ID           |
+
+## Step-by-step instructions
+
+### Creating an automation
+
+1. Parse the user's request to determine:
+   - **What** the task should do → becomes `taskTemplate.prompt` (the `name` is also used as `taskTemplate.title` automatically)
+   - **When** it should run → becomes `scheduleType` + schedule config
+   - **How to deliver result**:
+     - Default to current automation session (`delivery.mode: "session"`)
+     - Do **not** use `delivery.mode: "notify"` just because the task is scheduled, recurring, or uses cron
+     - Use `delivery.mode: "notify"` only when the user explicitly asks to notify/push/send the result to a connected channel
+     - Set `delivery.sessionId` to target the exact connected chat/group/DM whenever it is available
+     - `delivery.channelId` is a legacy fallback only; do not prefer it over `delivery.sessionId`
+2. Choose the right schedule type (see [Schedule types](#schedule-types) below)
+3. Call the `create_automation` tool. Example for an interval schedule:
+   - `name`: "Daily News Briefing"
+   - `scheduleType`: "interval"
+   - `intervalMinutes`: 1440
+   - `taskTemplate.prompt`: "Search today's financial news and generate a summary"
+   - `taskTemplate.delivery.mode`: "session"
+
+   Example for a cron schedule:
+   - `name`: "Morning News"
+   - `scheduleType`: "cron"
+   - `cronExpression`: "0 9 * * *"
+   - `timezone`: "Asia/Shanghai"
+   - `taskTemplate.prompt`: "Search today's financial news and generate a summary"
+   - `taskTemplate.delivery.mode`: "session"
+
+   Example only when the user explicitly asks to push results to a connected chat/group/DM:
+   - `name`: "Morning News to Team Group"
+   - `scheduleType`: "cron"
+   - `cronExpression`: "0 9 * * *"
+   - `timezone`: "Asia/Shanghai"
+   - `taskTemplate.prompt`: "Search today's financial news and generate a summary"
+   - `taskTemplate.delivery.mode`: "notify"
+   - `taskTemplate.delivery.sessionId`: "tsk_xxxxxxxxxxxxxxxx"
+
+4. Report the result to the user, including the automation name and next run time.
+
+### Listing automations
+
+Call the `list_automations` tool. Present the results in a readable format including name, schedule description, enabled status, and next run time.
+
+### Updating an automation
+
+To update an automation, delete the old one and create a new one with the updated settings. Always pass `timezone` when using `scheduleType: "cron"`.
+
+### Deleting an automation
+
+1. If the user refers to an automation by name, first call `list_automations` to find the matching ID.
+2. Confirm with the user before deleting.
+3. Call the `delete_automation` tool with the automation `id`.
+4. Confirm deletion to the user.
+
+## Schedule types
+
+| Type       | When to use                                    | Required flag            | Example                                    |
+|------------|------------------------------------------------|--------------------------|--------------------------------------------|
+| `interval` | Simple recurring ("every N minutes/hours")     | `--interval-minutes N`   | `--interval-minutes 60` (hourly)           |
+| `cron`     | Complex schedules ("weekdays at 9am")          | `--cron "expr"`          | `--cron "0 9 * * 1-5"` with `--timezone "Asia/Shanghai"` |
+| `once`     | One-time future execution                      | `--scheduled-at ISO8601` | `--scheduled-at 2026-03-25T10:00:00Z`      |
+
+**Important**: For `cron` type, the cron expression must be in the user's local time. Always pass `--timezone` with the user's IANA timezone. If the user's timezone is unknown, ask them.
+
+### Natural language → schedule mapping
+
+| User says                  | Schedule type | Config (Asia/Shanghai example)                              |
+|----------------------------|---------------|-------------------------------------------------------------|
+| "every hour"               | interval      | `--interval-minutes 60`                                     |
+| "daily" / "once a day"     | interval      | `--interval-minutes 1440`                                   |
+| "daily at 9am"             | cron          | `--cron "0 9 * * *" --timezone "Asia/Shanghai"`             |
+| "weekdays at 9am"          | cron          | `--cron "0 9 * * 1-5" --timezone "Asia/Shanghai"`           |
+| "every Monday"             | cron          | `--cron "0 9 * * 1" --timezone "Asia/Shanghai"`             |
+| "every 5 minutes"          | interval      | `--interval-minutes 5`                                      |
+| "1st of each month"        | cron          | `--cron "0 9 1 * *" --timezone "Asia/Shanghai"`             |
+| "tomorrow at 3pm"          | once          | `--scheduled-at <ISO8601>`                                  |
+
+### Common cron expressions
+
+```
+* * * * *       Every minute
+*/5 * * * *     Every 5 minutes
+0 * * * *       Every hour (at :00)
+0 9 * * *       Daily at 9:00 AM in the specified timezone
+0 9 * * 1-5     Weekdays at 9:00 AM in the specified timezone
+0 9 * * 1       Every Monday at 9:00 AM in the specified timezone
+0 0 * * *       Daily at midnight in the specified timezone
+0 9 1 * *       1st of each month at 9:00 AM in the specified timezone
+```
+
+## Error handling
+
+- If the tool returns a plan limit error (e.g., `FORBIDDEN` about plan limits), you **must** offer an actionable solution (e.g., fallback to interval, or suggest upgrading in Workspace Settings -> Billing).
+- If the tool returns a validation error (e.g., `BAD_REQUEST`), explain exactly which field is wrong and suggest a fix.
+- For invalid cron expressions, suggest a valid alternative.
+
+## Language & Terminology
+
+When communicating with users in Chinese, it's critical to use the exact UI terminology found in the product to avoid confusion.
+
+- **Automation / Scheduled Task**: Translate as "定时任务" (do not use "自动化" directly if confusing).
+- **Plan (Free / Plus / Pro / Enterprise)**: Translate as "订阅" (e.g. "Free plan" -> "免费版", "Upgrade plan" -> "升级订阅").
+- **Cron**: Can be kept as "Cron 计划" or translated naturally as "指定时间运行".
+
+Example Chinese response for a Free plan limit:
+"因为您当前处于**免费订阅 (Free)**，不支持指定具体时间（Cron）执行。您是否希望我帮您设置为每 xxx 分钟执行一次？如果您需要每天固定时间执行，可以前往**工作区设置 -> 账单**中升级您的订阅至 Plus 或更高版本。"
+
+## Tips
+
+- When the user's intent is ambiguous about timing, ask for clarification
+  before creating. For example, "check the news for me daily" — ask whether
+  they want a specific time (cron) or just every 24 hours (interval).
+- The `prompt` field is what the agent will receive as its task when the
+  automation triggers. Make it specific and actionable.
+- Automation names should be descriptive so the user can identify them later.