@dypai-ai/mcp 1.4.3 → 1.4.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dypai-ai/mcp",
-  "version": "1.4.3",
+  "version": "1.4.6",
   "description": "DYPAI MCP Server — AI agent toolkit for building and deploying full-stack apps",
   "type": "module",
   "main": "src/index.js",

package/src/api.js

@@ -63,9 +63,21 @@ export function request(method, path, body) {
       res.on("end", () => {
         if (res.statusCode >= 200 && res.statusCode < 300) {
           try { resolve(JSON.parse(buf)) } catch { resolve(buf) }
-        } else {
-          reject(new Error(`HTTP ${res.statusCode}: ${buf.slice(0, 500)}`))
+          return
         }
+        // Build a richer error for quota-specific 429s so MCP tools can surface
+        // them to the agent without parsing raw HTTP strings.
+        let parsedBody = null
+        try { parsedBody = JSON.parse(buf) } catch {}
+        const err = new Error(`HTTP ${res.statusCode}: ${buf.slice(0, 500)}`)
+        err.statusCode = res.statusCode
+        err.body = parsedBody
+        const detail = parsedBody && parsedBody.detail
+        if (detail && typeof detail === "object" && detail.error) {
+          err.code = detail.error
+          err.detail = detail
+        }
+        reject(err)
       })
     })
     req.on("error", reject)

package/src/auto-update.js

@@ -21,6 +21,11 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_PATH = join(__dirname, "..", "package.json");
 const PKG_NAME = "@dypai-ai/mcp";
 const REGISTRY_URL = `https://registry.npmjs.org/${PKG_NAME}/latest`;
+// Dist-tags endpoint is tiny (<200B) — used to check if there's a CRITICAL
+// release the user must upgrade to immediately, bypassing the 6h throttle.
+// To mark a version as critical after publish:
+//   npm dist-tag add @dypai-ai/mcp@1.4.5 critical
+const DIST_TAGS_URL = `https://registry.npmjs.org/-/package/${PKG_NAME}/dist-tags`;
 const CHECK_TIMEOUT_MS = 2000;
 const THROTTLE_HOURS = 6;
 const STATE_FILE = join(tmpdir(), "dypai-mcp-update-state.json");
@@ -68,6 +73,32 @@ async function fetchLatestManifest() {
   }
 }
 
+/**
+ * Fetch the `critical` dist-tag (if published). Used to bypass the 6h throttle
+ * when a release is important enough that users must upgrade on next spawn.
+ *
+ * Returns the critical version string (e.g. "1.4.5") or null if no critical
+ * tag is set, the registry is unreachable, or the response is malformed.
+ *
+ * Cost: one tiny JSON fetch (~200 bytes) per spawn. Adds ~50-150ms to startup
+ * but runs in parallel with the rest of the MCP init, so wall-clock impact is
+ * usually zero.
+ */
+async function fetchCriticalVersion() {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), CHECK_TIMEOUT_MS);
+  try {
+    const res = await fetch(DIST_TAGS_URL, { signal: ctrl.signal });
+    if (!res.ok) return null;
+    const tags = await res.json();
+    return typeof tags?.critical === "string" ? tags.critical : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 /**
  * After npm publish there's a 30s–2min window where the registry knows the
  * version but the tarball is not yet replicated across the CDN. If we clear
@@ -145,7 +176,19 @@ export async function checkForUpdates({ force = false } = {}) {
   const current = getCurrentVersion();
   if (!current) return { skipped: "no current version" };
 
-  // Throttle
+  // ── Critical release check (bypasses the 6h throttle) ────────────────────
+  // If an ops person has run `npm dist-tag add @dypai-ai/mcp@X.Y.Z critical`,
+  // every spawn picks that up and forces an upgrade regardless of when the
+  // last normal check ran. Used for security / data-loss bug fixes where
+  // 6-24h propagation is too slow.
+  const criticalVersion = await fetchCriticalVersion();
+  const hasCritical = criticalVersion && compareVersions(criticalVersion, current) > 0;
+  if (hasCritical) {
+    log(`CRITICAL update required: ${current} → ${criticalVersion} (bypassing throttle)`);
+    force = true;
+  }
+
+  // Throttle (skipped when force or critical)
   if (!force) {
     const state = readState();
     if (state.lastCheckAt) {

package/src/index.js

@@ -54,6 +54,7 @@ import { dypaiPullTool, dypaiDiffTool, dypaiPushTool, dypaiValidateTool, dypaiTe
 import { proxyToolCall } from "./tools/proxy.js"
 import { enrichSuccess, enrichError } from "./tools/enrich.js"
 import { maybeRefreshSchemaAfterExecuteSql } from "./tools/sql-side-effects.js"
+import { maybeOffloadSearchLogs } from "./tools/search-logs-offload.js"
 import { withProjectContext, invalidateProjectContext } from "./tools/project-context.js"
 // summarizeDypaiTraceResponse (from ./tools/trace-summarize.js) is kept on
 // disk for when dypai_trace is re-enabled, but not imported here.
@@ -110,7 +111,7 @@ const REMOTE_TOOLS = [
   // Note: `get_app_tables` is intentionally NOT exposed — dypai/schema.sql already
   // caches table info locally (auto-refreshed on DDL). For ad-hoc introspection,
   // use execute_sql against information_schema.
-  { name: "execute_sql", description: "Executes any SQL query on the project database (PostgreSQL). Supports SELECT, INSERT, UPDATE, DELETE, CREATE TABLE, ALTER TABLE, DROP TABLE. Platform schemas (system, auth, storage) are read-only for security. DDL on public.* auto-refreshes dypai/schema.sql.", inputSchema: { type: "object", properties: { project_id: { type: "string" }, sql: { type: "string", description: "SQL query to execute" } }, required: ["sql"] } },
+  { name: "execute_sql", description: "BACKEND ONLY — executes any SQL query on the project database (PostgreSQL). Supports SELECT, INSERT, UPDATE, DELETE, CREATE TABLE, ALTER TABLE, DROP TABLE. Platform schemas (system, auth, storage) are read-only for security. DDL on public.* auto-refreshes dypai/schema.sql. Note: DDL applies IMMEDIATELY to the live database (no draft stage) — for destructive DDL like DROP TABLE / TRUNCATE, summarize the impact and get the user's explicit OK before calling.", inputSchema: { type: "object", properties: { project_id: { type: "string" }, sql: { type: "string", description: "SQL query to execute" } }, required: ["sql"] } },
 
   // ── API Endpoints ─────────────────────────────────────────────────────────
   // Full CRUD + exploration goes through the git-first flow:
@@ -230,6 +231,56 @@ Operations:
     },
   },
 
+  // ── Drafts (production-only staging area) ────────────────────────────────
+  // manage_drafts wraps the cloud SDK that talks to /api/engine/{id}/endpoints/
+  // Single tool, three ops (list / publish / discard) — same shape as
+  // manage_users / manage_roles / manage_storage so the agent's mental
+  // model stays uniform. Every project starts in draft-publish mode by
+  // default: dypai_push stages mutations as drafts and the user (or
+  // agent on their behalf) publishes when ready.
+  {
+    name: "manage_drafts",
+    description: `BACKEND ONLY — inspect, publish, or discard pending backend changes (drafts).
+
+Mental model: every change made by \`dypai_push\` (endpoints, webhooks,
+crons, realtime policies) is staged as a DRAFT first. Drafts do NOT
+affect live traffic; they only show up in the live config once the user
+publishes them. This is the universal default — works the same on every
+project, no environment flags to worry about. The frontend is a separate
+stack — use \`manage_frontend(deploy)\` to publish frontend changes.
+
+Operations:
+- list:    Return pending drafts grouped by resource type. Read-only,
+           no confirmation. Run this BEFORE publish/discard so the user
+           sees exactly what will ship or be thrown away.
+- publish: Atomically apply ALL pending drafts to live (creates, updates,
+           deletions) and invalidate affected caches. Requires confirm:true.
+- discard: Drop pending drafts without applying. By default discards
+           every draft; pass resource_names:[...] to scope the discard
+           to specific endpoints. Requires confirm:true.
+
+Typical flow:
+  1. dypai_push                                          → changes saved as drafts
+  2. manage_drafts(operation:'list')                     → show user what's pending
+  3. (optional) test the draft from local dev / preview
+  4. manage_drafts(operation:'publish', confirm:true)    → make it live
+     OR manage_drafts(operation:'discard', confirm:true) → throw it away`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id:     { type: "string", description: "Project UUID. Required for user tokens; auto-detected for project tokens." },
+        operation:      { type: "string", enum: ["list", "publish", "discard"], description: "Operation to perform." },
+        confirm:        { type: "boolean", description: "Required true for publish and discard. Without it the tool returns a confirmation_required hint instead of mutating.", default: false },
+        resource_names: { type: "array", items: { type: "string" }, description: "Optional. For discard: scope to drafts whose resource_name matches one of these. Ignored by list/publish." },
+      },
+      required: ["operation"],
+      allOf: [
+        { if: { properties: { operation: { const: "publish" } }, required: ["operation"] }, then: { required: ["confirm"] } },
+        { if: { properties: { operation: { const: "discard" } }, required: ["operation"] }, then: { required: ["confirm"] } },
+      ],
+    },
+  },
+
   // ── Storage ───────────────────────────────────────────────────────────────
   // manage_storage covers BOTH bucket-level and object-level operations.
   // The remote also accepts the legacy name `list_buckets` (alias) so older
@@ -397,6 +448,26 @@ endpoint YAML and \`dypai_push\`. This tool does NOT modify the definition.`,
     },
   },
 
+  // ── Observability ─────────────────────────────────────────────────────────
+  {
+    name: "search_logs",
+    description: "Search recent errors and warnings for the current project. ALWAYS call this FIRST when the user reports any error, bug, or 'this isn't working' — don't guess from the code; check what actually broke. Returns a unified, time-ordered list mixing failed workflow executions and warn/error log lines from the engine. Defaults to the last 24h. Data retention: 7 days.\n\nWorkflow:\n  1) Call with no args (or just `since:'1h'`) → see recent failures.\n  2) Pick the relevant entry → call again with `endpoint` + tighter `query` to narrow down.\n  3) For the full step-by-step debug trace of a specific failure, set `include_trace:true` (response is much larger; you'll likely get a `file_path` to read the full JSON from disk).\n\nUse `environment:'live'` when investigating a production user complaint (excludes draft test runs). Use `environment:'draft'` when the user says 'I just tested X locally and it failed' (their local UI hits the draft overlay).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id: { type: "string", description: "Project UUID. Auto-detected for project tokens." },
+        query: { type: "string", description: "Optional substring to match (case-insensitive) in error messages and log lines. e.g. 'timeout', 'OpenAI', 'permission denied'." },
+        endpoint: { type: "string", description: "Optional endpoint name filter (e.g. 'create-order')." },
+        since: { type: "string", default: "24h", description: "Time window: relative ('15m', '1h', '24h', '7d') or ISO 8601 timestamp. Default 24h. Hard cap: 7d (retention)." },
+        level: { type: "string", enum: ["error", "warn", "all"], default: "all", description: "Filter by severity. 'error' includes failed/timeout executions + error logs. 'warn' is warning logs. 'all' (default) returns both." },
+        environment: { type: "string", enum: ["live", "draft", "all"], default: "all", description: "live = production traffic only (excludes draft overlay test runs). draft = only requests through dev-<project_id>.dypai.dev. all = both. Use 'live' for real user bug reports." },
+        limit: { type: "integer", default: 50, minimum: 1, maximum: 200, description: "Max items to return. Default 50, max 200." },
+        include_trace: { type: "boolean", default: false, description: "Attach the full step-by-step debug trace per failed execution. Verbose — combine with `query`/`endpoint` filters and a low `limit`. If the response gets large, the local proxy writes it to disk and returns a file_path you can Read." }
+      },
+      required: []
+    }
+  },
+
   // ── Knowledge ─────────────────────────────────────────────────────────────
   { name: "search_docs", description: "Search DYPAI documentation. Use this when unsure about SDK usage, auth patterns, workflow nodes, or platform features. Returns relevant documentation chunks.", inputSchema: { type: "object", properties: { query: { type: "string", description: "What you want to learn about" } }, required: ["query"] } },
   { name: "search_workflow_templates", description: "Search workflow templates by description. Returns ready-to-use workflow code for common patterns: CRUD operations, payment gateways, email sending, AI chatbots, data pipelines, etc.", inputSchema: { type: "object", properties: { query: { type: "string", description: "What the workflow should do (e.g. 'send email', 'stripe payment')" }, category: { type: "string", description: "Optional: AI, Database, Payments, Communication, Logic, Storage" } }, required: ["query"] } },
@@ -405,7 +476,153 @@ endpoint YAML and \`dypai_push\`. This tool does NOT modify the definition.`,
 
 // ── Server Instructions ──────────────────────────────────────────────────────
 
-const SERVER_INSTRUCTIONS = `You are building full-stack applications on the DYPAI platform. You handle backend (endpoints, database, auth, realtime) AND frontend (SDK integration, UI code).
+const SERVER_INSTRUCTIONS = `You are building full-stack applications on the DYPAI platform. You handle BACKEND (workflow endpoints, database, auth, realtime) and FRONTEND (SDK integration, React/Vite/Next code).
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# QUICK START — read this section even if you skip everything else
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## What you ship — two completely separate stacks
+
+| Stack | What it is | Where it lives | How you change it | How you publish |
+|---|---|---|---|---|
+| **BACKEND** | Workflow endpoints (HTTP, cron, webhook, telegram), DB schema, realtime policies | \`dypai/\` folder | Edit YAMLs / SQL files / realtime.yaml on disk | \`dypai_push\` (saves draft) → \`manage_drafts(publish, confirm:true)\` |
+| **FRONTEND** | React/Vite/Next bundle (UI, SDK calls) | \`src/\`, \`public/\`, \`package.json\` | Edit React code | \`manage_frontend(deploy, confirm:true)\` |
+
+Two things to internalize:
+1. The two stacks are SHIPPED INDEPENDENTLY. Editing backend never touches frontend, and vice versa.
+2. Backend has a draft stage; frontend does NOT. Both publish operations require \`confirm:true\`.
+
+## Backend lifecycle — "save" = \`dypai_push\` (this is the rule that trips up new agents)
+
+Editing files inside \`dypai/\` only changes YOUR DISK. The platform doesn't see them, the draft overlay doesn't serve them, the local frontend can't call them. There are exactly **three** states and only \`dypai_push\` and \`manage_drafts(publish)\` move you between them:
+
+\`\`\`
+  ┌────────────┐  edit YAML / SQL / md   ┌────────────┐  dypai_push   ┌────────────┐  manage_drafts(publish, confirm:true)   ┌────────────┐
+  │   LIVE     │ ──────────────────────► │ LOCAL DISK │ ────────────► │   DRAFT    │ ──────────────────────────────────────► │   LIVE     │
+  │ (engine)   │  (no platform impact)   │ (your edit)│ (stages it)   │ (overlay)  │  (atomic, all drafts at once)           │ (engine)   │
+  └────────────┘                         └────────────┘               └────────────┘                                         └────────────┘
+                                                                            ▲
+                                                              draft overlay │ served at https://dev-<project_id>.dypai.dev
+                                                                            │ (what the user's local frontend points to)
+\`\`\`
+
+Practical consequences — internalize these:
+- **After EVERY meaningful change set, call \`dypai_push\`.** Don't batch a session's worth of edits hoping to push at the end — if you forget, the user tests the local UI and sees the OLD behavior, gets confused, and you waste a debug round-trip blaming the code. The push is cheap, idempotent, and creates ONE draft per resource (subsequent pushes overwrite the draft, not stack new ones).
+- **\`dypai_push\` is the "save" button. It is NOT a publish.** Live traffic is untouched. You can push 20 times in a row without affecting a single user. Tell the user that explicitly when they ask "did it ship?" — push = staged draft, publish = live.
+- **The draft overlay (\`dev-<project_id>.dypai.dev\`) only sees what you've pushed.** A change still on disk is invisible to the local frontend. If the user says "I tested it locally and nothing changed", your first check is "did I run \`dypai_push\` after the last edit?".
+- **\`dypai_validate\` before \`dypai_push\`** — push runs validate as a pre-flight, but running it explicitly first gives you the lint output without committing. Cheap insurance.
+- **Order during a multi-step feature**: edit → \`dypai_validate\` → \`dypai_push\` → \`dypai_test_endpoint(mode:'draft')\` (or tell the user to test their local UI). Repeat per change. ONLY at the end, when the user signs off, do \`manage_drafts(operation:'list')\` → \`manage_drafts(operation:'publish', confirm:true)\`.
+- **DDL is the exception**: \`execute_sql\` with CREATE / ALTER / DROP TABLE applies to live IMMEDIATELY (no draft stage for schema). Drafts only exist for endpoints / webhooks / crons / realtime policies. Summarize destructive DDL to the user before running it.
+
+## User intent → tool to call (decision table)
+
+Use this BEFORE picking a tool. If unsure which row matches, ask the user.
+
+| If the user asks to... | First call | Then |
+|---|---|---|
+| "Create a new project" | \`search_project_templates\` (find a starter) | \`create_project(template_slug: ...)\` |
+| "Show me what we have" / "I want to work on existing project X" | \`list_projects\` → \`dypai_pull\` (backend) + \`manage_frontend(sync)\` (frontend) | Read \`dypai/\` files + \`src/\` |
+| "Add/change a backend endpoint, table, cron, webhook, agent, integration" | Edit files in \`dypai/\` | \`dypai_validate\` → \`dypai_push\` |
+| "Publish my backend changes" / "make it live" | \`manage_drafts(operation:'list')\` to show what's pending | \`manage_drafts(operation:'publish', confirm:true)\` |
+| "Test an endpoint before publishing" | \`dypai_test_endpoint(mode:'local')\` (your edits) or \`(mode:'draft')\` (after push) | — |
+| "Test the new endpoint from my local frontend, end-to-end, before publishing" | Tell user: their local frontend already points to \`https://dev-<project_id>.dypai.dev\` (set by \`manage_frontend(sync)\`), which serves drafts on top of live. So after \`dypai_push\` the local UI hits the draft overlay automatically — nothing else to do. | — |
+| "Throw away my backend changes" | \`manage_drafts(operation:'discard', confirm:true)\` | — |
+| "Change the UI / change colors / add a page" | Edit files in \`src/\` | \`manage_frontend(deploy, confirm:true)\` |
+| "Publish the new UI" / "ship the frontend" | \`manage_frontend(deploy, confirm:true)\` | (deploy is the publish — there is no separate step) |
+| "Roll back" | Backend: \`get_endpoint_versions\` then write old code back. Frontend: re-deploy older source. | — |
+| "Upload a file / a CSV / seed data" | \`bulk_upsert\` (data) or \`manage_storage(upload_file)\` (binary) | — |
+| "X is broken" / "I'm getting an error" / "this doesn't work" / "users are reporting Y" | \`search_logs\` FIRST (don't guess from the code) | If a specific failure is found → \`search_logs(include_trace:true, query:'...')\` for the full step-by-step trace |
+
+## Confirm rules — the ONLY operations that need \`confirm:true\`
+
+There are exactly THREE write operations that mutate live state and require explicit user approval (return a \`confirmation_required\` hint without it):
+
+1. **\`manage_drafts(operation:'publish', confirm:true)\`** — promotes backend drafts to live.
+2. **\`manage_drafts(operation:'discard', confirm:true)\`** — throws away pending backend drafts.
+3. **\`manage_frontend(operation:'deploy', confirm:true)\`** — replaces the live frontend bundle.
+
+Everything else (\`dypai_push\`, \`execute_sql\`, \`bulk_upsert\`, all read tools) does NOT require confirm. \`dypai_push\` is safe by design: it stages drafts, so you can iterate freely without affecting the live site.
+
+When you receive a \`confirmation_required\` response: SUMMARIZE the change to the user in plain language (what will go live, any warnings about pending backend drafts), wait for an explicit "yes" / "go ahead", then re-call with \`confirm:true\`.
+
+## End-to-end example — adding a feature that touches BOTH backend and frontend
+
+User: "Add a /api/list-tasks endpoint that returns the current user's tasks, and show them on the dashboard."
+
+\`\`\`
+1. dypai_pull(project_id)                        # materialize backend if not already on disk
+2. manage_frontend(operation:'sync', ...)        # materialize frontend if not already on disk
+3. # Backend: create the endpoint
+   Write dypai/endpoints/list-tasks.yaml         # trigger.http_api auth_mode:jwt + dypai_database query
+4. dypai_validate                                # catch typos before push
+5. dypai_push                                    # stages as draft, NOT live yet
+6. dypai_test_endpoint(name:'list-tasks', mode:'draft', as_user:'<uuid>')   # verify the staged version
+7. manage_drafts(operation:'list')               # show pending changes to user
+8. # ASK USER: "Ready to publish list-tasks to live?"
+9. manage_drafts(operation:'publish', confirm:true)   # backend now live ✅
+10. # Frontend: call the new endpoint from React
+    Edit src/pages/Dashboard.tsx                 # useEndpoint('list-tasks')
+11. # ASK USER: "Ready to deploy the dashboard UI?"
+12. manage_frontend(operation:'deploy', sourceDirectory, confirm:true)   # frontend now live ✅
+\`\`\`
+
+**Order matters**: publish backend BEFORE deploying frontend. Otherwise the new UI calls an endpoint that doesn't exist on live yet → 404s for users. The \`manage_frontend(deploy)\` confirmation hint will warn you if backend drafts are still pending.
+
+## Debugging user-reported errors — \`search_logs\` is your starting point
+
+**Rule**: whenever the user says any of these — "X is broken", "this isn't working", "I'm getting an error", "users are reporting Y", "the page is white", "nothing happens when I click" — **call \`search_logs\` BEFORE reading any code**. The engine's logs are the ground truth; the code is your hypothesis. Trying to debug from the source first is how you waste 20 minutes solving the wrong problem.
+
+### The standard flow
+
+\`\`\`
+1. search_logs({ since: "1h", level: "error" })
+   → Quick scan of recent failures. If empty, widen to "24h".
+
+2. # Did the user say "I just tested this in my local UI"?
+   #   → add environment: "draft"   (their UI hits the draft overlay)
+   # Did they say "production users are reporting..."?
+   #   → add environment: "live"    (excludes their own draft test runs)
+
+3. # Found the relevant entry? Narrow down:
+   search_logs({ endpoint: "create-order", query: "stripe", since: "1h" })
+
+4. # For the full step-by-step trace of one specific failure:
+   search_logs({
+     endpoint: "create-order",
+     query: "<a unique substring from the error message>",
+     include_trace: true,
+     limit: 5
+   })
+   → If the response is large the local proxy writes it to a temp file
+     and returns a \`file_path\`. Read that file with the Read tool ONLY
+     when you need fields beyond the inline summary.
+
+5. # Now you know exactly which node failed and why → fix the code.
+\`\`\`
+
+### What \`search_logs\` returns
+
+Each item has \`type\` (\`execution_failed\` | \`log\`), \`level\` (\`error\` | \`warn\`), \`time\`, \`endpoint\`, \`message\`, and \`environment\` (\`live\` | \`draft\` | null for legacy rows). Failed executions also include \`status\` (\`error\` | \`timeout\`) and \`duration_ms\`. With \`include_trace:true\` they also include \`trace\` — a per-node log of inputs, outputs, errors, and stacks.
+
+### Common pitfalls
+
+- **Don't skip this and read code first.** The bug is almost never where you'd guess. Logs tell you exactly which node blew up and the exact error string.
+- **Don't dump every error you see at the user.** Filter, summarize, then propose ONE fix.
+- **\`environment\` matters.** A draft test failure is the user testing pending changes — fixing the draft is fine. A live failure is real users hitting production — fix urgently and follow up with backend publish.
+- **Retention is 7 days.** If the user reports a bug from "last week", the data is likely gone. Tell them.
+
+## What you do NOT have to think about
+
+- "Development vs production environment" — the user never sees this. Backend changes always go through draft-and-publish. Frontend changes always go through deploy. That's the whole model.
+- "Create auth endpoints" — auth is built into the SDK. \`dypai.auth.signInWithPassword()\` works out of the box. NEVER write a login/signup workflow.
+- "RLS / row-level security" — there is none. You filter by \`\${current_user_id}\` in your SQL WHERE clauses. Forgetting this is the #1 multi-tenancy bug.
+- "Rate limiting / CORS / JWT verification" — handled by the engine.
+- "Promoting projects to production" — every new project already has the draft-publish flow enabled. \`manage_project(promote_to_production)\` is legacy and you should never need it.
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# DEEP REFERENCE — the rest of this document
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 ## Getting Started
 1. list_projects() → pick project_id.
@@ -431,14 +648,15 @@ Mental translations:
 ## Build Backend (git-first workflow)
 Endpoints live in ./dypai/ — there is NO create_endpoint / update_endpoint / add_node tool.
 
-1. Tables: \`execute_sql\` for DDL. \`schema.sql\` auto-refreshes.
-2. Endpoints:
+1. Tables: \`execute_sql\` for DDL. \`schema.sql\` auto-refreshes. **DDL is the only backend mutation that bypasses drafts — it hits live immediately.**
+2. Endpoints / realtime / webhooks / crons:
    - Edit/Write YAMLs in \`dypai/endpoints/<group>/<name>.yaml\`.
    - Long SQL / prompts / code go in \`dypai/sql/\`, \`dypai/prompts/\`, \`dypai/code/\` (referenced via \`query_file\`, \`system_prompt_file\`, \`code_file\`).
-   - \`dypai_validate\` → catches placeholder / schema / credential / node-param errors.
+   - \`dypai_validate\` → catches placeholder / schema / credential / node-param errors. Run before push (push also runs it as pre-flight).
    - \`dypai_diff\` → preview changes (read-only).
-   - \`dypai_push\` → apply.
-3. \`dypai_test_endpoint\` to run the LOCAL YAML against the engine. Iterate edit → test → push.
+   - \`dypai_push\` → **stages your edits as drafts on the platform**. This is the "save" step. NOT a publish. Run after every meaningful change set, not just at the end of a session — until you push, neither the engine nor the local frontend (which talks to the draft overlay) can see your edits.
+   - \`manage_drafts(operation:'publish', confirm:true)\` → ONLY when the user signs off. Promotes ALL pending drafts atomically to live.
+3. \`dypai_test_endpoint\` to execute an endpoint against the engine. Three sources via \`mode\`: \`local\` (default — your YAML on disk, BEFORE push, fastest while iterating), \`draft\` (the version staged by \`dypai_push\` but not yet published — what live will look like after \`manage_drafts(publish)\`), \`live\` (currently deployed). Canonical loop: edit → \`dypai_validate\` → \`dypai_test_endpoint(mode:'local')\` → \`dypai_push\` → \`dypai_test_endpoint(mode:'draft')\` (or user tests local UI on the draft overlay) → \`manage_drafts(publish, confirm:true)\`.
 
 ## Picking nodes — catalog-first
 
@@ -494,10 +712,17 @@ Any endpoint can be flagged \`tool: true\` to be callable by \`agent\` nodes. Ho
 
 ## Testing & Debugging
 
-- **\`dypai_test_endpoint\`** — single endpoint, LOCAL YAML (unpushed edits). Pass \`as_user\` UUID for jwt endpoints. Trace modes: \`smart\` (default), \`full\`, \`minimal\`. Iterate edit → test → push.
+Four ways to validate a backend change, in increasing fidelity:
+
+1. **\`dypai_test_endpoint(mode:'local')\`** — runs YOUR YAML on disk against the engine BEFORE \`dypai_push\`. Fastest feedback loop while iterating on a single endpoint. Pass \`as_user\` UUID for jwt endpoints.
+2. **\`dypai_test_endpoint(mode:'draft')\`** — runs the version staged by \`dypai_push\` (i.e. exactly what \`manage_drafts(publish)\` will promote). Use as the final isolated check before publishing.
+3. **End-to-end from the local frontend** (Layer 2.5 draft overlay) — after \`dypai_push\`, the user's local frontend already calls \`https://dev-<project_id>.dypai.dev\` (set by \`manage_frontend(sync)\`), which serves drafts on top of live. So real UI flows hit the draft transparently. No setup, no env-flip, no headers. Read-only impact on prod data — drafts share the SAME database as live.
+4. **\`dypai_test_endpoint(mode:'live')\`** — repro a bug that's already in production.
+
+Other tools:
 - **\`dypai_test\`** — YAML regression suites at \`dypai/tests/<name>.test.yaml\` with assertions (equals, matches, contains, type, exists, gte, lte) + setup_sql / teardown_sql.
 - **\`dypai_validate\`** — static linting (placeholders, tables, columns, node params, credentials). Run before EVERY push.
-- **Prod debugging**: \`get_recent_workflow_activity(only_errors=true)\` surfaces recent failures.
+- **Prod debugging**: \`search_logs\` is the entry point — see the "Debugging user-reported errors" section above. Returns failed executions + warn/error logs from the last 7 days; pass \`environment:'live'\` to exclude draft-overlay test runs and \`include_trace:true\` for the per-node failure trace.
 
 → Deep patterns: \`search_docs("testing endpoints")\` (test setup + assertions), \`search_docs("troubleshooting")\` (common failures + fixes).
 
@@ -577,7 +802,8 @@ query_file: /absolute/path/sql/get-orders.sql
 - \`/api/v0/<endpoint_name>\` — HTTP endpoints
 - \`/api/v0/webhooks/<endpoint_name>\` — webhook endpoints (different path prefix)
 - \`/public/<path>\` — media served from the storage bucket (auto-populated on deploy; see "Frontend deploy")
-- \`https://<project_id>.dypai.app\` — the engine base URL (what the SDK points to)
+- \`https://<project_id>.dypai.dev\` — engine base URL serving LIVE traffic (what the deployed frontend's SDK points to)
+- \`https://dev-<project_id>.dypai.dev\` — engine base URL serving the **draft overlay** (Layer 2.5): drafts staged via \`dypai_push\` are served here, falling back to live for anything not drafted. This is what the SDK in \`.env.local\` points to during local frontend development, so a local UI can validate backend drafts end-to-end BEFORE \`manage_drafts(publish)\`.
 
 ## Endpoint YAML skeleton (top-level fields)
 
@@ -757,7 +983,7 @@ Pre-configured at \`src/lib/dypai.ts\`. Every method returns \`{ data, error }\`
 - **JWT verification** — jwt auth_mode validates the session token automatically. \`\${current_user_id}\` is trusted.
 - **Rate limiting** — per-plan. Returns 429 automatically.
 - **CORS** — allowed origins per project (configured in dashboard).
-- **Request logging** — every execution in \`system.workflow_runs\` with duration, status, tokens (for agents). View via \`get_recent_workflow_activity\`.
+- **Request logging** — every execution is recorded with duration, status, environment (live/draft), and (on failure) a per-node debug trace. Warn/error \`userLog\` lines are persisted alongside. Query both via \`search_logs\` (last 7 days).
 - **Input validation** — if the endpoint has \`input:\` schema, requests with invalid payloads are rejected with 400 + details BEFORE the workflow runs.
 - **SQL injection** — placeholders bind as Postgres params. Safe by construction.
 - **Secrets management** — credentials and env vars never appear in YAML or logs.
@@ -785,6 +1011,8 @@ Pre-configured at \`src/lib/dypai.ts\`. Every method returns \`{ data, error }\`
 - **Credentials not created** → workflow fails with "credential not found". Check \`get_app_credentials\` before referencing one in a node. Create in dashboard (not via MCP yet).
 - **Binary files in \`dypai/code/\`** → only text code files here. Binary assets go to the frontend \`public/\` or to a bucket.
 - **\`dypai_push\` without \`dypai_validate\`** → pushing a broken workflow. Always validate first.
+- **Editing a YAML and forgetting \`dypai_push\`** → the user reloads their local frontend (which points at the draft overlay \`dev-<project_id>.dypai.dev\`) and sees the OLD behavior because your edit only exists on YOUR DISK. Symptom: "I tested it locally and nothing changed." First check: did you push? Push after every meaningful change set, not at the end.
+- **Treating \`dypai_push\` as a deploy** → It's a "save as draft", not a publish. Live traffic is unaffected until \`manage_drafts(publish, confirm:true)\`. Don't ask the user "ready to ship?" before push — push freely, only ask before publish.
 - **Frontend dev server + remote media** → media files are auto-uploaded to the storage bucket on deploy but \`vite dev\` doesn't proxy to it. Run \`manage_frontend(sync)\` first to pull media to disk.
 
 ## Frontend
@@ -797,19 +1025,23 @@ SDK is pre-configured at \`src/lib/dypai.ts\`. Import \`dypai\` from there. Ever
 - **Realtime hooks**: \`useRealtime\`, \`useChannel\`, \`useChannelMessages\` (see Realtime section)
 - **Rule**: NEVER \`fetch()\` directly — always through the SDK
 
-**\`.env\` required** — \`.env\` is gitignored so \`manage_frontend(sync)\` does NOT fetch it. If \`env_file_missing: true\` in the sync response, create it:
+**\`.env.local\` is auto-managed by \`manage_frontend(sync)\`** — when missing, sync writes it for you pointing at the **draft overlay** (\`https://dev-<project_id>.dypai.dev\`) so your local frontend transparently consumes backend drafts. The variable name follows your framework: \`VITE_DYPAI_URL\` for Vite, \`NEXT_PUBLIC_DYPAI_URL\` for Next.js. **Do not overwrite a user-authored \`.env.local\`** — sync respects an existing file. Only create it manually if \`env_file_missing: true\` in the sync response AND you have a reason to deviate.
+
 \`\`\`bash
-# Vite
-VITE_DYPAI_URL=https://<project_id>.dypai.app
-VITE_PROJECT_ID=<project_id>
-# Next.js (NEXT_PUBLIC_ prefix is required)
-NEXT_PUBLIC_DYPAI_URL=https://<project_id>.dypai.app
+# What sync writes (Vite)
+VITE_DYPAI_URL=https://dev-<project_id>.dypai.dev
+
+# What sync writes (Next.js)
+NEXT_PUBLIC_DYPAI_URL=https://dev-<project_id>.dypai.dev
 \`\`\`
-Without \`.env\`, all SDK calls fail. It's always the missing env var, not the code.
+
+For **production** the deployed frontend bundle automatically receives the live URL (\`https://<project_id>.dypai.dev\`, no \`dev-\` prefix) injected as a build-time env var by \`manage_frontend(deploy)\` — the user never has to flip URLs by hand. Without an \`.env.local\` the local SDK has no engine to call → every API call fails. It's always the env var, not the code.
 
 ## Frontend deploy
 
-\`manage_frontend(operation: deploy, sourceDirectory, project_id)\` → returns immediately with build_status=queued. Poll \`operation: build_status\` every ~5s until "success" or "failure". On failure: \`operation: list_deployments\` → \`operation: logs\` with deployment_id. Supports Vite, React, Next.js, Astro, SvelteKit, Nuxt, Remix, Angular, CRA (auto-detected).
+\`manage_frontend(operation: deploy, sourceDirectory, project_id, confirm:true)\` → ships the frontend bundle. **Replaces the live site IMMEDIATELY** — no draft stage, no automatic rollback. \`confirm:true\` is REQUIRED; without it the tool returns a \`confirmation_required\` hint (and warns if backend drafts are still pending — you should publish those FIRST so the frontend doesn't call non-existent endpoints).
+
+Returns immediately with build_status=queued. Poll \`operation: build_status\` every ~5s until "success" or "failure". On failure: \`operation: list_deployments\` → \`operation: logs\` with deployment_id. Supports Vite, React, Next.js, Astro, SvelteKit, Nuxt, Remix, Angular, CRA (auto-detected).
 
 The deploy is delta by default: only files changed since last deploy are sent. Large media (>25MB) surfaces in \`assets_requiring_action\` with ready-to-exec \`manage_storage(upload_file)\` calls.
 
@@ -822,6 +1054,7 @@ The deploy is delta by default: only files changed since last deploy are sent. L
 - \`manage_users\` / \`manage_roles\` — app-level RBAC (users via better-auth).
 - \`manage_schedules\` / \`manage_webhooks\` — pause/resume/history. To change the DEFINITION, edit the endpoint YAML and push.
 - \`manage_storage\` — buckets + objects. \`upload_file\` reads local path, signs URL, PUTs direct to the storage bucket, registers. Max 100MB/file. → \`search_docs("file storage")\`.
+- \`manage_drafts\` — universal draft-and-publish workflow. \`dypai_push\` always saves changes as drafts; use \`list\` to show the user what's pending, \`publish\` (confirm:true) to apply them atomically to live, \`discard\` to throw them away. Test pending drafts with \`dypai_test_endpoint(mode:'draft')\` before publishing.
 
 ## Deep docs — search_docs topic map
 
@@ -941,6 +1174,14 @@ async function handleRequest(msg) {
             }
           }
 
+          // search_logs can return huge payloads when include_trace=true.
+          // Offload to a temp file when the serialized response > 60 KB so
+          // the agent's context stays clean — it gets a summary + file path
+          // and only Reads the file when it actually needs the detail.
+          if (name === "search_logs") {
+            result = maybeOffloadSearchLogs(result)
+          }
+
           // Note: test_workflow is no longer agent-facing (wrapped by
           // dypai_test_endpoint). dypai_trace is temporarily hidden until
           // the engine captures debug traces for real production executions.

package/src/tools/deploy.js

@@ -489,13 +489,19 @@ export async function deployFromSource({ sourceDirectory, project_id, force = fa
     const assetsAction = buildAssetsRequiringAction(skipped, mediaManifest, project_id)
     const hasUnresolvedAssets = assetsAction && assetsAction.count > 0
 
+    const quota = result.build_quota || null
+    const quotaWarning = buildQuotaWarning(quota)
+
     const baseMessage =
       `Deploy accepted — ${allFiles.length} files (${formatBytes(total)}). ` +
       `Build running (${label}, ~20-60s). Poll manage_frontend({operation:"build_status"}) every ~5s.`
 
     let message = baseMessage
+    if (quotaWarning) {
+      message = `${quotaWarning}\n\n${message}`
+    }
     if (hasUnresolvedAssets) {
-      message = `${assetsAction.message}\n\n${baseMessage}`
+      message = `${assetsAction.message}\n\n${message}`
     }
 
     return {
@@ -513,6 +519,8 @@ export async function deployFromSource({ sourceDirectory, project_id, force = fa
       ...(hasUnresolvedAssets ? { assets_requiring_action: assetsAction } : {}),
       ...(assetsAction?.all_synced ? { assets_synced: assetsAction.already_in_bucket } : {}),
 
+      ...(quota ? { build_quota: quota } : {}),
+
       next_step: hasUnresolvedAssets
         ? {
             action: "resolve_pending_assets_then_poll_build",
@@ -536,6 +544,46 @@ export async function deployFromSource({ sourceDirectory, project_id, force = fa
       message,
     }
   } catch (e) {
+    if (e.statusCode === 429 && e.detail && e.detail.error === "build_quota_exceeded") {
+      return {
+        success: false,
+        error: e.detail.message || "Monthly build minutes limit reached.",
+        error_code: "build_quota_exceeded",
+        build_quota: {
+          minutes_used: e.detail.minutes_used,
+          minutes_limit: e.detail.minutes_limit,
+          resets_at: e.detail.resets_at,
+        },
+        upgrade_url: e.detail.upgrade_url,
+        advice: "Do not retry this deploy. Inform the user that the monthly build minute quota is exhausted and suggest upgrading the project plan.",
+      }
+    }
+    if (e.statusCode === 429 && e.detail && e.detail.error === "concurrent_builds_limit") {
+      return {
+        success: false,
+        error: e.detail.message || "Concurrent build limit reached.",
+        error_code: "concurrent_builds_limit",
+        concurrent_active: e.detail.concurrent_active,
+        concurrent_limit: e.detail.concurrent_limit,
+        advice: "Wait for the active build to finish (poll manage_frontend({operation:'build_status'})) before re-deploying.",
+      }
+    }
     return { error: `Deploy failed: ${e.message}` }
   }
 }
+
+/**
+ * Human-readable warning when the project is near its monthly build quota.
+ * Returns null when plan is unlimited or usage is below 80%.
+ */
+function buildQuotaWarning(quota) {
+  if (!quota) return null
+  const { minutes_used, minutes_limit, minutes_remaining } = quota
+  if (minutes_limit == null) return null
+  const pct = minutes_limit > 0 ? (minutes_used / minutes_limit) : 0
+  if (pct < 0.8) return null
+  if (pct >= 1) {
+    return `⚠️ Monthly build minutes exhausted (${minutes_used}/${minutes_limit} min). This deploy used your last minutes — upgrade your plan to deploy again.`
+  }
+  return `⚠️ Build quota at ${Math.round(pct * 100)}% (${minutes_used}/${minutes_limit} min, ${minutes_remaining} remaining). Consider upgrading soon.`
+}