@mindstudio-ai/remy 0.1.8 → 0.1.10

package/dist/prompt/compiled/dev-and-deploy.md

@@ -0,0 +1,69 @@
+# Development & Deployment
+
+## How Development Works
+
+The sandbox uses the same tunnel binary and execution pipeline as local development. Code changes take effect immediately — esbuild transpiles methods per-request, no restart needed. The dev database is a disposable snapshot of production.
+
+### The Dev Inner Loop
+
+1. Edit method code in `dist/methods/src/` — next method invocation uses updated code automatically
+2. Edit frontend code in `dist/interfaces/web/src/` — HMR updates the browser instantly
+3. Add/modify table definitions — schema changes sync to the dev database automatically
+4. Run scenarios to set up specific data states for testing
+
+### Dev Database
+
+The dev session gets its own database — a snapshot of the live database at session start. Your code writes to this snapshot, not to production.
+
+- **Reset to live data** — overwrite the dev database with a fresh copy of production
+- **Truncate** — keep the schema, delete all row data (used by scenarios for a clean canvas)
+- **Schema sync** — add a field to a table interface and it's immediately available in dev
+
+The dev database is disposable. Experiment freely — there's no risk of breaking anything.
+
+### Debugging
+
+`console.log`, `console.warn`, and `console.error` in methods are captured and displayed in the terminal. They don't affect the method's return value. Every method execution is logged with full input, output, duration, and error info.
+
+## What Happens on Deploy
+
+```bash
+git push origin main
+```
+
+The platform builds and deploys automatically:
+
+1. **Parse manifest** — read `mindstudio.json` from the commit
+2. **Compile methods** — esbuild bundles each method into a single JS file
+3. **Compile interfaces** — build web SPA (`npm install && npm run build`), generate configs for API/Discord/Telegram/cron/etc.
+4. **Parse table schemas** — TypeScript AST to column definitions, diff against live database
+5. **Compute effects** — roles diff, cron diff, bot command diffs, table DDL
+6. **Apply** — create/update roles, sync bot commands, apply DDL to a staging database copy, swap the live pointer
+
+### Preview Deployments
+
+Push to a non-default branch for a preview deployment — same build pipeline, but doesn't affect the live app. Useful for testing changes before merging.
+
+### Database Migrations on Deploy
+
+Schema changes are automatic:
+- **New tables** — `CREATE TABLE` applied automatically
+- **New columns** — `ALTER TABLE ADD COLUMN` applied automatically
+- **Dropped columns** — `ALTER TABLE DROP COLUMN` applied automatically when a column is removed from the interface
+- **Dropped tables** — `DROP TABLE` applied automatically when a table file is removed from the manifest
+- **Type changes and renames** — not supported in the automatic migration path
+
+Schema changes are always applied to a clone of the live database, never directly. If DDL fails, the live database is untouched and the release is marked `failed`.
+
+### Rollback
+
+Rollback is a git revert — creates a new commit, triggers a new build. The previous release's database still exists (databases are per-release), so data isn't lost.
+
+### Common Build Failures
+
+- **Method compilation error** — TypeScript/syntax error in a method file. Error message includes file and line.
+- **Web build error** — npm install or build command failed. Check build log stdout/stderr.
+- **Table schema error** — TypeScript file couldn't be parsed. Ensure the table definition uses the `defineTable<T>()` pattern.
+- **Missing manifest fields** — method declared but path doesn't exist, or export doesn't match.
+
+Failed releases don't affect the current live release.

package/dist/prompt/compiled/interfaces.md

@@ -0,0 +1,238 @@
+# Interfaces
+
+Interfaces are projections of the backend contract into different modalities. The same methods power all of them. An interface can be as complex and polished as you want, but it's always safe — the backend contract is where anything real happens. The interface can't break business logic or corrupt data.
+
+All external service connections (Discord bot tokens, Telegram bot setup, webhook secrets, email addresses) are configured at the project level by the user through the MindStudio platform. The agent's job is to write the config files and the methods that handle the requests — not to manage API keys, OAuth flows, or service registration.
+
+## Web Interface
+
+A full web application — typically Vite + React, but any framework that produces static output works.
+
+### Project Structure
+
+```
+dist/interfaces/web/
+  web.json           ← interface config
+  package.json
+  vite.config.ts
+  index.html
+  src/
+    App.tsx
+    pages/
+    components/
+```
+
+### Config (`web.json`)
+
+```json
+{
+  "devPort": 5173,
+  "devCommand": "npm run dev"
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `devPort` | `number` | `5173` | Port for the dev server |
+| `devCommand` | `string` | `"npm run dev"` | Command to start the dev server |
+
+### Frontend SDK
+
+```typescript
+import { createClient, platform, auth } from '@mindstudio-ai/interface';
+
+// Typed RPC to backend methods — use the camelCase export function names,
+// NOT the kebab-case method IDs from mindstudio.json. The client maps
+// export names to method IDs automatically.
+const api = createClient<{
+  submitVendorRequest(input: { name: string }): Promise<{ vendorId: string }>;
+  listVendors(): Promise<{ vendors: Vendor[] }>;
+}>();
+
+const { vendorId } = await api.submitVendorRequest({ name: 'Acme' });
+const { vendors } = await api.listVendors();
+
+// File operations
+const { url } = await platform.requestFile({ type: 'image' });
+const cdnUrl = await platform.uploadFile(file);
+
+// Current user (display only)
+auth.userId;
+auth.name;
+auth.email;
+```
+
+The project uses `"jsx": "react-jsx"` (automatic JSX transform) — do not `import React from 'react'`. Only import the specific hooks and types you need (e.g., `import { useState, useEffect } from 'react'`).
+
+On deploy, the platform runs `npm install && npm run build` in the web directory and hosts the output on CDN.
+
+## API Interface
+
+Auto-generated REST endpoints. Every method becomes an API endpoint.
+
+### Config (`interface.json`)
+
+```json
+{
+  "methods": ["submit-vendor-request", "list-vendors", "get-dashboard"]
+}
+```
+
+Omit the `methods` field (or the config entirely) to expose all methods.
+
+### Usage
+
+```bash
+curl -X POST https://api.mindstudio.ai/_internal/v2/apps/{appId}/methods/submit-vendor-request/invoke \
+  -H "Authorization: Bearer sk..." \
+  -H "Content-Type: application/json" \
+  -d '{ "input": { "name": "Acme" } }'
+```
+
+Auth via API key. Returns `{ output, $releaseId, $methodId }`.
+
+### Streaming
+
+```bash
+curl -X POST ... -d '{ "input": {...}, "stream": true }'
+```
+
+Returns SSE: `data: { type: 'token', text }` chunks, then `data: { type: 'done', output }`.
+
+## Discord Bot
+
+Slash commands that invoke methods.
+
+### Config (`interface.json`)
+
+```json
+{
+  "commands": [
+    {
+      "name": "submit-vendor",
+      "description": "Request a new vendor",
+      "method": "submit-vendor-request"
+    }
+  ],
+  "loadingMessage": "Processing your request..."
+}
+```
+
+Commands are synced to Discord on deploy.
+
+## Telegram Bot
+
+Bot commands and message handling.
+
+### Config (`interface.json`)
+
+```json
+{
+  "commands": [
+    {
+      "command": "/submit",
+      "description": "Submit a vendor request",
+      "method": "submit-vendor-request"
+    }
+  ],
+  "defaultMethod": "handle-message"
+}
+```
+
+`defaultMethod` handles free-text messages that don't match a command.
+
+## Cron
+
+Scheduled method execution.
+
+### Config (`interface.json`)
+
+```json
+{
+  "jobs": [
+    {
+      "schedule": "0 9 * * 5",
+      "method": "process-weekly-payments",
+      "description": "Process approved invoices every Friday at 9am"
+    },
+    {
+      "schedule": "*/30 * * * *",
+      "method": "sync-vendor-status",
+      "description": "Sync vendor statuses every 30 minutes"
+    }
+  ]
+}
+```
+
+Standard cron expression format. Jobs are synced to the platform on deploy.
+
+## Webhook
+
+Inbound HTTP endpoints that invoke methods.
+
+### Config (`interface.json`)
+
+```json
+{
+  "endpoints": [
+    {
+      "method": "handle-payment-webhook",
+      "description": "Stripe payment notifications",
+      "secret": "whk_abc123..."
+    }
+  ]
+}
+```
+
+Endpoint URL: `https://api.mindstudio.ai/_internal/v2/webhook/{appId}/{secret}`
+
+Accepts any HTTP method. The method receives `{ method, headers, query, body }` as input.
+
+## Email
+
+Inbound email triggers.
+
+### Config (`interface.json`)
+
+```json
+{
+  "method": "handle-inbound-email"
+}
+```
+
+Register a custom address (e.g., `invoices@mindstudio-hooks.com`) via the platform. Inbound emails invoke the specified method with the email content as input.
+
+## MCP (Model Context Protocol)
+
+Expose methods as AI tools.
+
+### Config (`interface.json`)
+
+```json
+{
+  "methods": ["submit-vendor-request", "list-vendors"]
+}
+```
+
+Each listed method becomes an MCP tool. Method names and descriptions from the manifest are used as tool names and descriptions.
+
+## Manifest Declaration
+
+Each interface is declared in `mindstudio.json`:
+
+```json
+{
+  "interfaces": [
+    { "type": "web", "path": "dist/interfaces/web/web.json" },
+    { "type": "api" },
+    { "type": "cron", "path": "dist/interfaces/cron/interface.json" },
+    { "type": "discord", "path": "dist/interfaces/discord/interface.json" },
+    { "type": "telegram", "path": "dist/interfaces/telegram/interface.json" },
+    { "type": "webhook", "path": "dist/interfaces/webhook/interface.json" },
+    { "type": "email", "path": "dist/interfaces/email/interface.json" },
+    { "type": "mcp", "path": "dist/interfaces/mcp/interface.json" }
+  ]
+}
+```
+
+Some interfaces (like `api`) work without a config file — just declaring the type is enough. Others need a config for command mappings, schedules, etc. Set `"enabled": false` to skip an interface during build.

package/dist/prompt/compiled/manifest.md

@@ -0,0 +1,107 @@
+# Manifest Reference
+
+`mindstudio.json` declares everything the platform needs to know about the app. It's read on every deploy to determine what to compile.
+
+## Example
+
+```json
+{
+  "appId": "e452fcf2-06c5-49e8-b4f1-6353563f24b0",
+  "name": "Procure-to-Pay",
+
+  "roles": [
+    { "id": "requester", "name": "Requester", "description": "Can submit vendor requests and purchase orders." },
+    { "id": "approver", "name": "Approver", "description": "Reviews and approves purchase orders." },
+    { "id": "admin", "name": "Administrator", "description": "Full access to all app functions." }
+  ],
+
+  "tables": [
+    { "name": "vendors", "path": "dist/methods/src/tables/vendors.ts", "export": "Vendors" },
+    { "name": "purchase-orders", "path": "dist/methods/src/tables/purchase-orders.ts", "export": "PurchaseOrders" }
+  ],
+
+  "methods": [
+    {
+      "id": "submit-vendor-request",
+      "name": "Submit Vendor Request",
+      "path": "dist/methods/src/submitVendorRequest.ts",
+      "export": "submitVendorRequest"
+    }
+  ],
+
+  "interfaces": [
+    { "type": "web", "path": "dist/interfaces/web/web.json" },
+    { "type": "api" },
+    { "type": "cron", "path": "dist/interfaces/cron/interface.json" }
+  ],
+
+  "scenarios": [
+    {
+      "id": "ap-overdue-invoices",
+      "name": "AP: Overdue Invoices",
+      "description": "AP user with two invoices past due date.",
+      "path": "dist/methods/.scenarios/apOverdueInvoices.ts",
+      "export": "apOverdueInvoices",
+      "roles": ["ap"]
+    }
+  ]
+}
+```
+
+## Fields
+
+### `appId` (required)
+`string` (UUID). The app's platform identifier. Found in the git remote URL: `https://git.mscdn.ai/{appId}.git`.
+
+### `name` (required)
+`string`. Display name shown in the editor and workspace.
+
+### `roles`
+`Array<{ id, name?, description? }>`. Defaults to `[]`.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | Kebab-case identifier (used in code: `auth.requireRole('admin')`) |
+| `name` | `string` | No | Display name |
+| `description` | `string` | No | What this role can do |
+
+### `tables`
+`Array<{ name, path, export }>`. Defaults to `[]`.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | `string` | Yes | Table name — snake_case, `[a-zA-Z0-9_]` only (must match `db.defineTable('name')`) |
+| `path` | `string` | Yes | Path to the TypeScript file (relative to project root) |
+| `export` | `string` | Yes | Named export from the file (e.g., `Vendors`) |
+
+### `methods` (required, at least one)
+`Array<{ id, name?, path, export }>`.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | Kebab-case identifier (used in API URLs and frontend method map) |
+| `name` | `string` | No | Display name |
+| `path` | `string` | Yes | Path to the TypeScript file |
+| `export` | `string` | Yes | Named export (the async function) |
+
+### `interfaces`
+`Array<{ type, path?, config?, enabled? }>`. Defaults to `[]`.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `type` | `string` | Yes | One of: `web`, `api`, `discord`, `telegram`, `cron`, `webhook`, `email`, `mcp` |
+| `path` | `string` | No | Path to the interface config file |
+| `config` | `object` | No | Inline config (alternative to a file) |
+| `enabled` | `boolean` | No | Default `true`. Set `false` to skip during build. |
+
+### `scenarios`
+`Array<{ id, name?, description?, path, export, roles }>`. Defaults to `[]`.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | Kebab-case identifier |
+| `name` | `string` | No | Display name |
+| `description` | `string` | No | What state this scenario creates |
+| `path` | `string` | Yes | Path to the TypeScript file |
+| `export` | `string` | Yes | Named export (the async function) |
+| `roles` | `string[]` | Yes | Roles to impersonate after seeding |

package/dist/prompt/compiled/media-cdn.md

@@ -0,0 +1,51 @@
+# Images and Media CDN
+
+MindStudio has three CDN hosts:
+
+- **Images:** `i.mscdn.ai`
+- **Videos:** `v.mscdn.ai`
+- **Files:** `f.mscdn.ai`
+
+Always use CDN transform parameters to request appropriately sized images
+rather than CSS-scaling full-resolution originals.
+
+## CDN Image Transforms
+
+Combine freely as query string parameters:
+
+| Param | Example | Effect |
+|-------|---------|--------|
+| `w` | `?w=400` | Max width in pixels |
+| `h` | `?h=300` | Max height in pixels |
+| `fit` | `?fit=crop` | Resize mode: scale-down, contain, cover, crop, pad |
+| `crop` | `?crop=face` | Face-aware crop (fit=crop + face detection) |
+| `fm` | `?fm=webp` | Output format: avif, webp, jpeg, auto |
+| `dpr` | `?dpr=2` | Device pixel ratio (auto-set to 3 when w/h specified) |
+| `q` | `?q=80` | Quality (1-100) |
+| `blur` | `?blur=10` | Blur radius |
+| `sharpen` | `?sharpen=1` | Sharpen amount |
+
+Example: `https://i.mscdn.ai/.../image.png?w=200&h=200&fit=crop&fm=avif`
+
+## Video Thumbnails
+
+Append `/thumbnail.png` or `/thumbnail.jpg` to any video URL:
+
+```
+https://v.mscdn.ai/{orgId}/videos/{videoId}.mp4/thumbnail.png?ts=last&w=400
+```
+
+The `ts` param selects the frame: a number (seconds) or `last`. Image CDN
+resize params also work on video thumbnails.
+
+## Media Metadata
+
+Append `.json` to any CDN URL to get metadata (dimensions, duration, mime
+type, orientation, etc.).
+
+## General Rules
+
+- Always set explicit width/height or aspect-ratio on images to prevent
+  layout shift.
+- Always load fonts directly from CDNs, never self-host font packages
+  in the application.

package/dist/prompt/compiled/methods.md

@@ -0,0 +1,225 @@
+# Methods
+
+A method is a named async function that runs on the platform. It's the universal unit of backend logic — every interface (web, API, Discord, cron, webhook) invokes methods. Methods run in isolated sandboxes. One file per method, one named export.
+
+## Writing a Method
+
+```typescript
+// dist/methods/src/submitVendorRequest.ts
+
+import { db, auth } from '@mindstudio-ai/agent';
+import { Vendors } from './tables/vendors';
+
+export async function submitVendorRequest(input: {
+  name: string;
+  contactEmail: string;
+  taxId: string;
+}) {
+  auth.requireRole('requester');
+
+  const vendor = await Vendors.push({
+    name: input.name,
+    contactEmail: input.contactEmail,
+    taxId: input.taxId,
+    status: 'pending',
+    requestedBy: auth.userId,
+  });
+
+  return { vendorId: vendor.id, status: vendor.status };
+}
+```
+
+### Manifest Entry
+
+```json
+{
+  "id": "submit-vendor-request",
+  "name": "Submit Vendor Request",
+  "path": "dist/methods/src/submitVendorRequest.ts",
+  "export": "submitVendorRequest"
+}
+```
+
+- `id` — kebab-case, used in API URLs (the platform maps these internally)
+- **Important:** the frontend `createClient` uses the camelCase `export` name, not the kebab-case `id`. Call `api.submitVendorRequest()`, not `api['submit-vendor-request']()`.
+- `path` — relative to project root
+- `export` — must match the function name
+
+### Input and Output
+
+Methods receive a single `input` parameter (an object) and return an object. Both are JSON-serializable. If no input is needed, the parameter can be omitted or typed as `{}`.
+
+```typescript
+export async function getDashboard(input: {
+  period?: 'week' | 'month' | 'quarter';
+}) {
+  const period = input.period || 'month';
+  // ...
+  return {
+    pendingApprovals,
+    recentOrders,
+    stats: { totalSpend, vendorCount },
+  };
+}
+```
+
+## Platform Capabilities
+
+The `@mindstudio-ai/agent` SDK provides access to 200+ AI models and 1,000+ actions (email, SMS, web scraping, file uploads, third-party integrations, and more). Inside a method, create an instance and call actions directly. No constructor arguments needed — credentials are picked up automatically from the execution environment:
+
+```typescript
+import { MindStudioAgent } from '@mindstudio-ai/agent';
+
+const agent = new MindStudioAgent();
+
+// AI text generation
+const { content } = await agent.generateText({
+  message: 'Summarize this invoice...',
+});
+
+// AI image generation
+const { imageUrl } = await agent.generateImage({
+  prompt: 'A professional headshot placeholder',
+});
+
+// Send email
+await agent.sendEmail({
+  to: 'user@example.com',
+  subject: 'Your invoice',
+  body: content,
+});
+
+// Upload files
+const { url } = await agent.uploadFile({
+  data: buffer,
+  fileName: 'report.pdf',
+});
+
+// Web scraping
+const { markdown } = await agent.scrapeUrl({
+  url: 'https://example.com',
+});
+
+// Resolve user display info
+const { displayName, email } = await agent.resolveUser({
+  userId,
+});
+```
+
+No separate API keys needed — the platform routes to the correct provider (OpenAI, Anthropic, Google, etc.) automatically.
+
+## Error Handling
+
+Throw errors with messages that make sense to end users — these may surface in the UI:
+
+```typescript
+export async function approveVendor(input: { vendorId: string }) {
+  auth.requireRole('admin', 'grc');
+
+  const vendor = await Vendors.get(input.vendorId);
+  if (!vendor) {
+    throw new Error('Vendor not found.');
+  }
+
+  if (vendor.status !== 'pending') {
+    throw new Error('This vendor has already been reviewed.');
+  }
+
+  // ...
+}
+```
+
+`auth.requireRole()` throws a 403 automatically if the user doesn't have the required role.
+
+## Common Patterns
+
+### CRUD Method
+
+```typescript
+export async function listVendors(input: {
+  status?: string;
+  search?: string;
+}) {
+  const vendors = await Vendors
+    .filter(v => {
+      if (input.status && v.status !== input.status) return false;
+      if (input.search && !v.name.includes(input.search)) return false;
+      return true;
+    })
+    .sortBy(v => v.name);
+
+  return { vendors };
+}
+```
+
+### Role-Gated Operation
+
+```typescript
+export async function deleteVendor(input: { vendorId: string }) {
+  auth.requireRole('admin');
+
+  const vendor = await Vendors.get(input.vendorId);
+  if (!vendor) throw new Error('Vendor not found.');
+
+  await Vendors.remove(input.vendorId);
+  return { success: true };
+}
+```
+
+### Multi-Table Transaction
+
+```typescript
+export async function createPurchaseOrder(input: {
+  vendorId: string;
+  lineItems: Array<{ description: string; amount: number }>;
+}) {
+  auth.requireRole('requester');
+
+  const vendor = await Vendors.get(input.vendorId);
+  if (!vendor || vendor.status !== 'approved') {
+    throw new Error('Vendor must be approved before creating a PO.');
+  }
+
+  const total = input.lineItems.reduce((sum, li) => sum + li.amount, 0);
+
+  const po = await PurchaseOrders.push({
+    vendorId: input.vendorId,
+    requestedBy: auth.userId,
+    lineItems: input.lineItems,
+    totalAmountCents: total,
+    status: 'pending_approval',
+  });
+
+  return { purchaseOrderId: po.id, total };
+}
+```
+
+## Shared Helpers
+
+Code shared between methods goes in `dist/methods/src/common/`. Helpers are not listed in the manifest — they're internal, imported by methods but not directly invocable.
+
+```typescript
+// dist/methods/src/common/getApprovalState.ts
+export function getApprovalState(approvals: Approval[]) {
+  const allApproved = approvals.every(a => a.status === 'approved');
+  const anyRejected = approvals.some(a => a.status === 'rejected');
+  // ...
+}
+```
+
+## Streaming
+
+Methods can stream token-by-token output (useful for AI-generated content):
+
+```typescript
+// Frontend
+const result = await api.generateReport(
+  { month: 'march' },
+  {
+    stream: true,
+    onToken: (text) => setPreview(text),
+  },
+);
+```
+
+The platform handles the SSE transport. The method returns normally — streaming is managed by the SDK and platform, not by your method code.