@dypai-ai/mcp 1.4.3 → 1.4.6

package/src/tools/frontend.js

@@ -14,11 +14,13 @@
 import { api } from "../api.js"
 import { deployFromSource } from "./deploy.js"
 import { syncFromRemote } from "./sync.js"
+import { proxyToolCall } from "./proxy.js"
 
 export const manageFrontendTool = {
   name: "manage_frontend",
   description:
-    "Manage the project's frontend: download the source code to disk AND the deploy lifecycle.\n\n" +
+    "FRONTEND ONLY — manages the project's static frontend (HTML/CSS/JS bundle). For BACKEND endpoints/workflows use dypai_push + manage_drafts; never use this tool for backend work.\n\n" +
+    "Two phases: download source to local disk (`sync`), then ship changes back (`deploy`).\n\n" +
     "Use `sync` FIRST whenever you start working on a project whose frontend code isn't already on this machine — " +
     "without it you have no React/Vite source to read or edit. Call `deploy` to ship your changes.\n\n" +
     "Operations:\n" +
@@ -28,19 +30,25 @@ export const manageFrontendTool = {
     "Writes only; does NOT delete local files that were removed upstream — you may have stale files after sync (call them out to the user). " +
     "By default refuses to overwrite a directory that already has a package.json — pass overwrite:true to allow it (local-only files like .env, node_modules, .vscode are always preserved). " +
     "AFTER SYNC: .env is gitignored so it's NOT included in the download. If the target directory has no .env, the response sets `env_file_missing: true` and adds a `next_steps` line with the exact VITE_DYPAI_URL / NEXT_PUBLIC_DYPAI_URL value to write. Follow it — without .env the SDK can't reach the engine.\n" +
-    "  - deploy: Upload source files from a local directory and queue a build. Returns immediately with build_status=\"queued\" — poll with `build_status` until \"success\" or \"failure\".\n" +
+    "  - deploy: Upload source files from a local directory and queue a build. **DESTRUCTIVE: replaces the LIVE site immediately, no draft stage, no rollback button.** " +
+    "Requires `confirm: true` — without it the tool returns a confirmation_required hint instead of deploying. " +
+    "If backend drafts are pending, the hint includes a warning to publish backend FIRST (otherwise the new frontend may call endpoints that don't exist yet). " +
+    "Returns immediately with build_status=\"queued\" — poll with `build_status` until \"success\" or \"failure\". " +
+    "The response includes `build_quota` with remaining monthly build minutes. If minutes_remaining is low, tell the user. If 0, DO NOT retry — suggest upgrading the plan.\n" +
     "  - status: Current live deploy info (URL, last deploy time, size).\n" +
     "  - build_status: Progress of the current/latest build (queued/building/success/failure + stage + %).\n" +
+    "  - usage: Full frontend usage snapshot including build_quota (minutes used/limit/remaining, deploy counts, resets_at). Call BEFORE deploy if unsure how much quota is left.\n" +
     "  - list_deployments: Recent deploy history (status, commit, duration, URL).\n" +
     "  - logs: Build logs for a specific deployment (needs deployment_id from list_deployments).\n\n" +
-    "Related: `dypai_pull` brings BACKEND state (YAML endpoints, SQL, prompts). The two are independent — run both when starting fresh on a full-stack project.",
+    "Related: `dypai_pull` brings BACKEND state (YAML endpoints, SQL, prompts). The two are independent — run both when starting fresh on a full-stack project.\n\n" +
+    "Order rule when both backend AND frontend changed: 1) dypai_push (saves backend as draft) → 2) manage_drafts(publish, confirm:true) → 3) manage_frontend(deploy, confirm:true). Inverting steps 2 and 3 may serve a frontend that calls non-existent endpoints.",
 
   inputSchema: {
     type: "object",
     properties: {
       operation: {
         type: "string",
-        enum: ["deploy", "sync", "status", "build_status", "list_deployments", "logs"],
+        enum: ["deploy", "sync", "status", "build_status", "usage", "list_deployments", "logs"],
         description: "Which action to run.",
       },
       project_id: {
@@ -65,6 +73,11 @@ export const manageFrontendTool = {
         description: "deploy only. Bypass the delta manifest and re-send ALL files (full deploy). Use when the previous deploy's remote build FAILED — the manifest says 'synced' but the remote never built, so a normal delta incorrectly reports no_changes. Default: false.",
         default: false,
       },
+      confirm: {
+        type: "boolean",
+        description: "Required `true` for `deploy`. Without it the tool returns a confirmation_required hint (with a ready-to-call next_call) instead of replacing the live site. The agent MUST get explicit user approval before passing confirm:true.",
+        default: false,
+      },
       deployment_id: {
         type: "string",
         description: "logs only. Deployment UUID obtained from list_deployments.",
@@ -77,7 +90,7 @@ export const manageFrontendTool = {
     required: ["operation"],
   },
 
-  async execute({ operation, project_id, sourceDirectory, targetDirectory, overwrite, force, deployment_id, limit } = {}) {
+  async execute({ operation, project_id, sourceDirectory, targetDirectory, overwrite, force, confirm, deployment_id, limit } = {}) {
     if (!operation) {
       return { success: false, error: "operation is required (deploy | sync | status | build_status | list_deployments | logs)." }
     }
@@ -91,6 +104,43 @@ export const manageFrontendTool = {
           if (!sourceDirectory) {
             return { success: false, error: "operation 'deploy' requires 'sourceDirectory' (absolute path to your frontend project root)." }
           }
+          // Defense-in-depth gate: deploy replaces the live site immediately
+          // with no rollback. Without explicit confirm we return a structured
+          // hint (with ready-to-execute next_call). We also surface any
+          // pending backend drafts as warnings — the agent should ALWAYS
+          // publish backend drafts before deploying frontend, otherwise the
+          // new frontend may call endpoints that don't exist yet on live.
+          if (confirm !== true) {
+            const warnings = []
+            try {
+              const draftsResult = await proxyToolCall("manage_drafts", { project_id, operation: "list" })
+              const draftsTotal = draftsResult?.total || 0
+              if (draftsTotal > 0) {
+                warnings.push(
+                  `${draftsTotal} backend draft(s) pending. Publish them BEFORE deploying the frontend with manage_drafts(operation:'publish', confirm:true) — otherwise the new frontend may call endpoints that don't exist on live yet.`,
+                )
+              }
+            } catch {
+              // Soft-fail — drafts check is advisory, not gating.
+            }
+            return {
+              confirmation_required: true,
+              summary: `About to replace the LIVE frontend at this project's public URL with the contents of '${sourceDirectory}'. This is IMMEDIATE and there is NO automatic rollback.`,
+              warnings: warnings.length > 0 ? warnings : undefined,
+              next_call: {
+                tool: "manage_frontend",
+                operation: "deploy",
+                project_id,
+                sourceDirectory,
+                ...(force ? { force: true } : {}),
+                confirm: true,
+              },
+              hint:
+                "Summarize the change to the user (what visual/functional changes are about to go live, " +
+                "and any pending backend drafts) and wait for explicit user approval. Then re-call this " +
+                "tool with confirm:true.",
+            }
+          }
           return await deployFromSource({ sourceDirectory, project_id, force: !!force })
 
         case "sync":
@@ -105,6 +155,9 @@ export const manageFrontendTool = {
         case "build_status":
           return await api.get(`/api/engine/${project_id}/frontend/build-status`)
 
+        case "usage":
+          return await api.get(`/api/engine/${project_id}/frontend/usage`)
+
         case "list_deployments":
           return await api.get(`/api/engine/${project_id}/frontend/deployments?limit=${limit || 10}`)
 
@@ -115,7 +168,7 @@ export const manageFrontendTool = {
           return await api.get(`/api/engine/${project_id}/frontend/deployments/${deployment_id}/logs`)
 
         default:
-          return { success: false, error: `Unknown operation '${operation}'. Use deploy | sync | status | build_status | list_deployments | logs.` }
+          return { success: false, error: `Unknown operation '${operation}'. Use deploy | sync | status | build_status | usage | list_deployments | logs.` }
       }
     } catch (e) {
       return { success: false, error: e.message, operation }

package/src/tools/scaffold.js

@@ -47,9 +47,13 @@ Or use "blank" for an empty starter project.`,
       return { error: `Directory already has a package.json. Pick an empty directory or a new name.` }
     }
 
-    // Production engine URL: https://<project-id>.dypai.app (NOT .dypai.dev — that's the dev tier).
+    // Engine base URL — `<project_id>.dypai.dev` serves LIVE traffic; the
+    // local-development URL `dev-<project_id>.dypai.dev` (Layer 2.5 draft
+    // overlay) is written into `.env.local` separately by `sync` once the
+    // user has the frontend on disk. Scaffold writes the production URL
+    // because at scaffold-time we expect the user to deploy soon.
     // Override with DYPAI_ENGINE_BASE for self-hosted / staging setups.
-    const engineBase = process.env.DYPAI_ENGINE_BASE || "dypai.app"
+    const engineBase = process.env.DYPAI_ENGINE_BASE || "dypai.dev"
     const engineUrl = `https://${project_id}.${engineBase}`
 
     // Try to download template from API

package/src/tools/search-logs-offload.js

@@ -0,0 +1,151 @@
+/**
+ * maybeOffloadSearchLogs — keep `search_logs` responses from blowing up the
+ * agent's context window.
+ *
+ * `search_logs` (especially with `include_trace=true`) can return hundreds of
+ * KB of JSON. Inlining that into the tool-result `text` field forces the model
+ * to load the whole payload into context, which is wasteful for the typical
+ * "show me what failed and let me drill into one of them" workflow.
+ *
+ * Strategy:
+ *   - If the serialized response exceeds OFFLOAD_THRESHOLD_BYTES, write the
+ *     full JSON to a temp file and return a compact summary that includes:
+ *       · the absolute file path (so the agent can `Read` it on demand)
+ *       · counts by level/type/environment
+ *       · the first 5 items, trace-stripped
+ *   - Otherwise, return the response unchanged.
+ *
+ * The offload threshold is intentionally loose (~60 KB). A normal search
+ * without `include_trace` is well under that and stays inline.
+ */
+
+import fs from "fs"
+import os from "os"
+import path from "path"
+
+// ~60 KB. Claude/GPT swallow this comfortably, but full traces (200-500 KB)
+// are forced to disk so the agent can consume them selectively.
+const OFFLOAD_THRESHOLD_BYTES = 60 * 1024
+
+// Keep the on-disk dir manageable: prune files older than this on every
+// offload. Cheap because it only runs when we actually offload.
+const FILE_TTL_MS = 24 * 60 * 60 * 1000 // 24h
+
+const OFFLOAD_DIR = path.join(os.tmpdir(), "dypai-mcp-search-logs")
+
+function ensureDir() {
+  try {
+    fs.mkdirSync(OFFLOAD_DIR, { recursive: true })
+  } catch {
+    /* race-safe; mkdirSync with recursive doesn't throw on existing dirs */
+  }
+}
+
+function pruneOldFiles() {
+  try {
+    const cutoff = Date.now() - FILE_TTL_MS
+    for (const name of fs.readdirSync(OFFLOAD_DIR)) {
+      const full = path.join(OFFLOAD_DIR, name)
+      try {
+        const stat = fs.statSync(full)
+        if (stat.mtimeMs < cutoff) fs.unlinkSync(full)
+      } catch { /* ignore individual file errors */ }
+    }
+  } catch { /* ignore — best-effort housekeeping */ }
+}
+
+function lightItem(item) {
+  // Drop the heavy `trace` field from each item for the inline summary.
+  // Everything else stays so the agent can decide which one to drill into.
+  if (!item || typeof item !== "object") return item
+  const { trace, ...rest } = item
+  return trace ? { ...rest, trace_omitted: true } : rest
+}
+
+function bucket(items, key) {
+  const out = {}
+  for (const it of items) {
+    const v = it && it[key] != null ? String(it[key]) : "null"
+    out[v] = (out[v] || 0) + 1
+  }
+  return out
+}
+
+/**
+ * Returns either the original `result` (small enough to inline) OR a compact
+ * summary object that points at a temp file holding the full JSON.
+ *
+ * Never throws — on any FS error it falls back to returning the original
+ * payload so the agent at least gets the data, even if it's big.
+ */
+export function maybeOffloadSearchLogs(result) {
+  if (!result || typeof result !== "object" || !Array.isArray(result.items)) {
+    return result
+  }
+
+  let serialized
+  try {
+    serialized = JSON.stringify(result, null, 2)
+  } catch {
+    return result
+  }
+
+  if (Buffer.byteLength(serialized, "utf8") <= OFFLOAD_THRESHOLD_BYTES) {
+    return result
+  }
+
+  try {
+    ensureDir()
+    pruneOldFiles()
+
+    const ts = new Date().toISOString().replace(/[:.]/g, "-")
+    const rand = Math.random().toString(36).slice(2, 8)
+    const filePath = path.join(OFFLOAD_DIR, `search-logs-${ts}-${rand}.json`)
+    fs.writeFileSync(filePath, serialized, "utf8")
+
+    const sizeBytes = Buffer.byteLength(serialized, "utf8")
+    const sizeKb = Math.round(sizeBytes / 1024)
+    const items = result.items
+    const firstFive = items.slice(0, 5).map(lightItem)
+
+    return {
+      offloaded_to_file: true,
+      file_path: filePath,
+      size_bytes: sizeBytes,
+      guidance: (
+        `Response was too large to inline (${sizeKb} KB > 60 KB threshold). ` +
+        `Full JSON written to disk — open it with the Read tool when you want ` +
+        `to inspect a specific item or its trace:\n  Read("${filePath}")\n\n` +
+        `The summary below covers the whole result. Only read the file if you ` +
+        `need fields beyond the first 5 items or any 'trace' contents.`
+      ),
+      summary: {
+        total_returned: items.length,
+        by_level: bucket(items, "level"),
+        by_type: bucket(items, "type"),
+        by_environment: bucket(items, "environment"),
+        first_5: firstFive,
+      },
+      filters: {
+        project_id: result.project_id,
+        since: result.since,
+        level: result.level,
+        environment: result.environment,
+        endpoint: result.endpoint,
+        query: result.query,
+        include_trace: result.include_trace,
+      },
+      // Mirror the upstream guidance so the agent doesn't lose it.
+      upstream_guidance: result.guidance,
+    }
+  } catch (err) {
+    // Disk full / permissions / whatever — just return the original. The
+    // agent's context will take a hit but the data still gets through.
+    return {
+      ...result,
+      offload_warning: `Could not write large payload to disk: ${err.message}`,
+    }
+  }
+}
+
+export const _internals = { OFFLOAD_THRESHOLD_BYTES, OFFLOAD_DIR }

package/src/tools/sync/diff.js

@@ -1,9 +1,27 @@
 /**
  * dypai_diff — preview what dypai_push would change. Read-only, safe.
+ *
+ * The picture has THREE layers, not two:
+ *   - LOCAL  : what's on disk in dypai/
+ *   - DRAFT  : what's already been staged via prior pushes (system.config_drafts)
+ *   - LIVE   : what the engine actually serves at <project_id>.dypai.dev
+ *
+ * The diff body reports the LOCAL → LIVE plan (existing behavior) — that's
+ * what `dypai_push` will queue. We additionally surface the DRAFT layer so
+ * the agent can spot:
+ *   1. Endpoints with a pending draft AND a local change → pushing again
+ *      will REPLACE the existing draft with the new local version.
+ *   2. Endpoints with only a pending draft → run manage_drafts to publish/discard.
+ *   3. Endpoints with only a local change → push will create a new draft.
+ *
+ * A full 3-way semantic diff (local vs draft vs live, field-by-field) would
+ * require reserializing each draft payload and comparing — deferred. The
+ * overlap signal here covers the common workflow without the extra cost.
  */
 
 import { resolve as resolvePath } from "path"
 import { fetchRemoteState, readLocalState, readLocalStateSnapshot, readLocalConfig, computePlan } from "./planner.js"
+import { proxyToolCall } from "../proxy.js"
 
 export const dypaiDiffTool = {
   name: "dypai_diff",
@@ -37,10 +55,17 @@ export const dypaiDiffTool = {
     const config = await readLocalConfig(rootDir)
     const targetProjectId = project_id || config?.project_id || null
 
-    const [local, remote, stateSnapshot] = await Promise.all([
+    const [local, remote, stateSnapshot, draftsResult] = await Promise.all([
       readLocalState(rootDir),
       fetchRemoteState(targetProjectId),
       readLocalStateSnapshot(rootDir),
+      // Pending drafts. Cheap on dev (always 0); on prod surfaces what's
+      // already staged so the agent can reason about overlap with the local
+      // change set. Old engines without the drafts API silently fall back.
+      proxyToolCall("manage_drafts", targetProjectId
+        ? { project_id: targetProjectId, operation: "list" }
+        : { operation: "list" }
+      ).catch(() => ({ total: 0, drafts: [], _unavailable: true })),
     ])
 
     if (local.errors.length) {
@@ -69,6 +94,62 @@ export const dypaiDiffTool = {
     const totalChanges = plan.create.length + plan.update.length + plan.delete.length + groupChanges
     const hasConflicts = (plan.warnings || []).some(w => w.type === "remote_changed_since_pull")
 
+    // ─── Drafts overlay ───────────────────────────────────────────────────
+    // Build a `pending_drafts` view that tells the agent what's already
+    // staged AND highlights the overlap with this diff's local-change set.
+    // The overlap is the agent-relevant signal: same endpoint touched on
+    // BOTH sides means pushing now will overwrite the existing draft.
+    const draftItems = Array.isArray(draftsResult?.drafts) ? draftsResult.drafts : []
+    const draftCount = draftsResult?.total || 0
+
+    const localChangeNames = new Set([
+      ...plan.create.map(p => p.name),
+      ...plan.update.map(p => p.name),
+      ...plan.delete.map(p => p.name),
+    ])
+
+    const overlap = draftItems
+      .filter(d => d.resource_type === "endpoint" && localChangeNames.has(d.resource_name))
+      .map(d => ({
+        endpoint: d.resource_name,
+        existing_draft_op: d.op,
+        local_change_op: plan.create.find(p => p.name === d.resource_name) ? "create"
+          : plan.update.find(p => p.name === d.resource_name) ? "update"
+          : "delete",
+      }))
+
+    const pendingDrafts = draftCount > 0 ? {
+      total: draftCount,
+      counts_by_type: draftsResult?.counts_by_type || {},
+      items: draftItems
+        .map(d => ({
+          resource_type: d.resource_type,
+          resource_name: d.resource_name,
+          op: d.op,
+        }))
+        .sort((a, b) => (a.resource_name || "").localeCompare(b.resource_name || "")),
+      // Endpoints that are BOTH staged AND modified locally — pushing again
+      // replaces the existing draft. Empty array = no overlap (clean signal).
+      overlap_with_local: overlap,
+    } : null
+
+    // ─── Hint priority ────────────────────────────────────────────────────
+    // 1. Conflicts and missing creds always win (block push).
+    // 2. Overlap is next: explicitly tell the agent that re-push overwrites.
+    // 3. Pending drafts (no overlap): suggest publishing or discarding before
+    //    stacking more on top.
+    const hint = hasConflicts
+      ? "Remote changed since your last pull — dypai_pull first, or dypai_push will be blocked."
+      : (plan.warnings || []).some(w => w.type === "missing_credential")
+        ? "Some YAMLs reference credentials missing remotely. Create them in the dashboard before pushing."
+        : overlap.length > 0
+          ? `${overlap.length} endpoint(s) have BOTH a pending draft AND a local change — dypai_push will REPLACE the existing draft with the new version. Review pending_drafts.overlap_with_local before pushing.`
+          : draftCount > 0 && totalChanges > 0
+            ? `${draftCount} draft(s) already pending; this diff would queue ${totalChanges} more. Consider manage_drafts(operation:'publish'|'discard', confirm:true) first to keep the staged set focused.`
+            : draftCount > 0
+              ? `${draftCount} pending draft(s) — no local changes to push. Run manage_drafts(operation:'list') to review, then 'publish' (confirm:true) or 'discard' (confirm:true).`
+              : undefined
+
     return {
       success: true,
       summary: {
@@ -81,15 +162,15 @@ export const dypaiDiffTool = {
         groups_delete: plan.groups?.delete?.length || 0,
         groups_unchanged: plan.groups?.unchanged?.length || 0,
         warnings: plan.warnings?.length || 0,
+        pending_drafts: draftCount,
+        drafts_overlap_with_local: overlap.length,
       },
       // Only include plan details when there are actual changes or warnings
       plan: (totalChanges > 0 || plan.warnings?.length) ? plan : undefined,
-      // Conflicts and missing creds deserve surfacing; no-op diffs don't
-      hint: hasConflicts
-        ? "Remote changed since your last pull — dypai_pull first, or dypai_push will be blocked."
-        : (plan.warnings || []).some(w => w.type === "missing_credential")
-          ? "Some YAMLs reference credentials missing remotely. Create them in the dashboard before pushing."
-          : undefined,
+      // Always present so the agent knows the key exists. `null` = nothing
+      // staged (cleaner signal than omitted-or-zero ambiguity).
+      pending_drafts: pendingDrafts,
+      hint,
     }
   },
 }

package/src/tools/sync/pull.js

@@ -558,7 +558,7 @@ export const dypaiPullTool = {
       await writeFile(gitignorePath, "# Auto-generated by dypai_pull\n.dypai/\n.DS_Store\n", "utf8")
     }
 
-    const [endpoints, credentials, groups, schemaSql, nodeCatalogResult, realtimePolicies] = await Promise.all([
+    const [endpoints, credentials, groups, schemaSql, nodeCatalogResult, realtimePolicies, draftsResult] = await Promise.all([
       execSql(project_id, `
         SELECT id, name, method, description, workflow_code, input, output,
                allowed_roles, is_tool, tool_description, group_id, is_active, updated_at
@@ -584,6 +584,17 @@ export const dypaiPullTool = {
         FROM system.realtime_policies
         ORDER BY target_type, target_name
       `).catch(() => []),
+      // Pending config drafts. Cheap on dev (always returns total=0); on prod
+      // surfaces what `dypai_push` queued so the agent doesn't need a separate
+      // `manage_drafts(list)` round-trip after pull. Old engines without the
+      // drafts API silently fall back to "no drafts" — pull stays usable.
+      proxyToolCall("manage_drafts", project_id
+        ? { project_id, operation: "list" }
+        : { operation: "list" }
+      ).catch(e => {
+        console.error(`[dypai_pull] manage_drafts(list) failed: ${e.message}`)
+        return { total: 0, drafts: [], counts_by_type: {}, _unavailable: true }
+      }),
     ])
 
     // schema.sql: always regenerated (read-only reference)
@@ -756,12 +767,54 @@ export const dypaiPullTool = {
       .filter(e => e.is_active === false)
       .map(e => e.name)
 
+    // `environment` is an internal flag we still surface in `overview.project`
+    // for diagnostics / dashboard parity, but the agent-facing copy uses the
+    // universal "drafts → publish" vocabulary regardless of the value.
+    // Default is "production" (= draft-publish workflow); legacy projects
+    // may still report "development" (= zero-friction direct writes).
+    const environment = (projectInfo?.environment || "production").toLowerCase()
+    const usesDraftWorkflow = environment !== "development"
+
+    // Compact view of `manage_drafts(list)` so the agent doesn't need a
+    // second round-trip to know what's staged. We surface BOTH the raw count
+    // and a per-resource view (most useful: "what endpoints have pending
+    // edits?") so the agent can decide whether to publish, discard, or
+    // continue iterating without re-querying.
+    const draftsTotal = draftsResult?.total || 0
+    const draftItems = Array.isArray(draftsResult?.drafts) ? draftsResult.drafts : []
+    const pendingDrafts = draftsTotal > 0 ? {
+      total: draftsTotal,
+      counts_by_type: draftsResult?.counts_by_type || {},
+      // Each item: { resource_type, resource_name, op } — strip noisy payload.
+      // Sorted by name for stable output across pulls (helps diff-on-disk if
+      // we ever persist this).
+      items: draftItems
+        .map(d => ({
+          resource_type: d.resource_type,
+          resource_name: d.resource_name,
+          op: d.op,
+        }))
+        .sort((a, b) => (a.resource_name || "").localeCompare(b.resource_name || "")),
+      hint: `Test the staged version with dypai_test_endpoint(mode:'draft', endpoint:'<name>'), then ` +
+        `manage_drafts(operation:'publish', confirm:true) to apply (or 'discard' to throw away).`,
+    } : null
+
     const overview = {
       project: projectInfo ? {
         id: projectInfo.id,
         name: projectInfo.name,
         plan: projectInfo.plan,
-      } : { id: resolvedProjectId || "(from token)" },
+        environment,
+      } : { id: resolvedProjectId || "(from token)", environment },
+      environment,
+      // User-facing hint speaks the universal "drafts → publish" language.
+      // We branch only on whether there are pending drafts and on the
+      // (uncommon) legacy direct-write mode.
+      environment_hint: usesDraftWorkflow
+        ? (draftsTotal > 0
+            ? `${draftsTotal} pending draft(s) — review with manage_drafts(operation:'list') before publishing. Confirm with the user before push, DDL, delete, deploy, or manage_drafts(publish/discard).`
+            : "Draft-and-publish workflow active. dypai_push stages changes as drafts; confirm with the user before publishing, DDL, delete, or deploy.")
+        : "Direct-write mode (legacy): mutations apply immediately, no draft stage. Iterate freely but confirm destructive ops with the user.",
       endpoints: {
         total: (endpoints || []).length,
         active: (endpoints || []).filter(e => e.is_active !== false).length,
@@ -773,9 +826,18 @@ export const dypaiPullTool = {
       },
       credentials: (credentials || []).map(c => ({ name: c.name, type: c.type })),
       realtime_policies: (realtimePolicies || []).length,
-      next_steps: (endpoints || []).length === 0
-        ? ["Empty project. Create tables via execute_sql, then write dypai/endpoints/<name>.yaml and dypai_push."]
-        : ["Read dypai/schema.sql before writing queries.", "Edit YAML in dypai/endpoints/, then dypai_diff → dypai_push."],
+      // Always present so the agent can rely on the key existing. `null`
+      // means "nothing pending" (cleaner than 0/empty-array which the agent
+      // might treat as "I should check this").
+      pending_drafts: pendingDrafts,
+      next_steps: pendingDrafts
+        ? [
+            `${draftsTotal} pending draft(s). Review with manage_drafts(operation:'list'), verify with dypai_test_endpoint(mode:'draft'), then publish or discard.`,
+            "After resolving drafts, edit YAML in dypai/endpoints/ and dypai_diff → dypai_push to stage more.",
+          ]
+        : (endpoints || []).length === 0
+          ? ["Empty project. Create tables via execute_sql, then write dypai/endpoints/<name>.yaml and dypai_push."]
+          : ["Read dypai/schema.sql before writing queries.", "Edit YAML in dypai/endpoints/, then dypai_diff → dypai_push."],
     }
 
     return {
@@ -784,6 +846,9 @@ export const dypaiPullTool = {
       files_written: filesWritten.length,
       output_dir: outDir,
       out_dir_resolved_via: outDirSource,
+      // Surface count at top level too — agents that ignore `overview` (e.g.
+      // pure scripted callers) still need to know the project has staged work.
+      pending_drafts: draftsTotal,
       overview,
       errors: errors.length ? errors : undefined,
       warning: suspiciousWarning || undefined,
@@ -791,9 +856,11 @@ export const dypaiPullTool = {
         ? "Some endpoints failed to serialize. Check errors[] — usually malformed workflow_code."
         : suspiciousWarning
           ? "Files were written but the path looks wrong. See `warning` above and re-run with an absolute out_dir."
-          : endpoints.length === 0
-            ? "Empty project. Create tables with execute_sql, then write endpoints/<name>.yaml and dypai_push."
-            : undefined,
+          : draftsTotal > 0
+            ? `${draftsTotal} pending draft(s) on this project — see overview.pending_drafts and decide publish vs discard before pushing more.`
+            : endpoints.length === 0
+              ? "Empty project. Create tables with execute_sql, then write endpoints/<name>.yaml and dypai_push."
+              : undefined,
     }
   },
 }