@dypai-ai/mcp 1.4.3 → 1.4.5

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,
     }
   },
 }

package/src/tools/sync/push.js

@@ -16,7 +16,6 @@ import {
   readLocalStateSnapshot,
   readLocalConfig,
   readLocalRealtime,
-  fetchRemoteRealtime,
   computePlan,
   localToCanonical,
 } from "./planner.js"
@@ -66,6 +65,12 @@ function endpointPayload(row) {
  * least one of the markers we expect from a real mutation. Anything else
  * (empty object, error string masquerading as data, missing id) becomes
  * an error so the push doesn't lie to the agent.
+ *
+ * Layer 2: by default the API stages mutations as drafts and returns
+ * `{applied_to: "draft", draft: {...}, message: "..."}`. That counts as a
+ * successful mutation — the change was saved, just not applied to live yet.
+ * Power-user direct-write projects skip the draft stage and return the
+ * legacy live shape; both are valid successes.
  */
 function assertMutationOK(result, op, name) {
   if (!result || typeof result !== "object") {
@@ -75,15 +80,29 @@ function assertMutationOK(result, op, name) {
     throw new Error(`${op} ${name}: ${typeof result.error === "string" ? result.error : JSON.stringify(result.error)}`)
   }
   // Successful create returns { id, name } or { ok: true }; update/delete return
-  // { message } or { ok: true }. If none of these markers are present the call
-  // probably failed silently.
-  const hasMarker = result.id || result.ok === true || result.message || result.endpoint_id || result.success === true
+  // { message } or { ok: true }. Draft responses return { applied_to: "draft", draft, message }.
+  const hasMarker = result.id
+    || result.ok === true
+    || result.message
+    || result.endpoint_id
+    || result.success === true
+    || result.applied_to === "draft"
   if (!hasMarker) {
     throw new Error(`${op} ${name}: response missing success markers — ${JSON.stringify(result).slice(0, 200)}`)
   }
   return result
 }
 
+/**
+ * Returns true when the API staged the change as a draft (default behavior)
+ * instead of applying it directly to live. Both the draft branch and the
+ * direct-write branch are valid successful outcomes — drafts just need to
+ * be reported back to the user so they know to run manage_drafts(publish).
+ */
+function isDraftResponse(result) {
+  return result && typeof result === "object" && result.applied_to === "draft"
+}
+
 async function applyCreate(canonicalRow, projectId) {
   const res = await proxyToolCall("create_endpoint", {
     ...(projectId ? { project_id: projectId } : {}),
@@ -150,101 +169,66 @@ async function applyGroupDelete(name, projectId, mapsCtx) {
 }
 
 // ─── Realtime policies sync ────────────────────────────────────────────────
+//
+// Layer 2 update: we no longer compute the diff client-side and write
+// directly via execute_sql. The whole bulk-sync goes through the API
+// endpoint POST /{project_id}/realtime/sync (called via the cloud MCP
+// tool `sync_realtime_policies`). The API:
+//   - computes the diff against live (and pending drafts in production)
+//   - branches dev/prod: production queues drafts, development applies
+//   - returns `{ applied_to: "live"|"draft", summary, details, drafts_queued? }`
+// Cache invalidation in the engine is automatic via the SQL trigger
+// `_dypai_notify_policy_change` (pg_notify → engine LISTEN), so neither
+// dev nor draft-publish need anything extra here.
 
 /**
- * Reconcile local realtime.yaml with system.realtime_policies remotely.
- * Returns a summary of what was applied (or would be applied in dry_run).
+ * Reconcile local realtime.yaml with the engine via the API. Returns the
+ * API response unchanged (with `dry_run: true` short-circuit when requested
+ * — the API itself doesn't have dry-run yet, so we just return the local
+ * count without making the call).
  */
 async function syncRealtimePolicies(projectId, rootDir, dryRun = false) {
   const local = await readLocalRealtime(rootDir)
   if (!local) return { skipped: true, reason: "no realtime.yaml found" }
 
-  const remote = await fetchRemoteRealtime(projectId)
-  if (remote === null) {
-    return { skipped: true, reason: "engine has no system.realtime_policies table yet (backward compat)" }
-  }
-
-  const key = (p) => `${p.target_type}::${p.target_name}`
-  const remoteMap = Object.fromEntries(remote.map(p => [key(p), p]))
-  const localMap = Object.fromEntries(local.rows.map(p => [key(p), p]))
-
-  const toUpsert = []
-  const toDelete = []
-  for (const k of Object.keys(localMap)) {
-    const l = localMap[k]
-    const r = remoteMap[k]
-    if (!r || !policiesEqual(l, r)) toUpsert.push(l)
-  }
-  for (const k of Object.keys(remoteMap)) {
-    if (!localMap[k]) toDelete.push(remoteMap[k])
-  }
-
   if (dryRun) {
-    return { upsert: toUpsert.length, delete: toDelete.length, dry_run: true }
+    // API doesn't expose dry-run today. We can still report the local count;
+    // the actual upsert/delete breakdown is computed server-side, so for the
+    // purposes of `dypai_diff` we just say "N local policies on disk".
+    return { local_count: local.rows.length, dry_run: true }
   }
 
-  // execute_sql on the remote is parameterless (only takes a raw `sql` string).
-  // To avoid hand-escaping values, we embed the rows as JSON and let Postgres
-  // parse them via jsonb_to_recordset — JSON.stringify handles quote escaping
-  // correctly, and we only need to double single-quotes for the SQL literal.
-  if (toUpsert.length > 0) {
-    const rowsJson = JSON.stringify(toUpsert.map(p => ({
+  // Forward the FULL local list — server diffs against live + drafts.
+  const result = await proxyToolCall("sync_realtime_policies", {
+    project_id: projectId,
+    policies: local.rows.map(p => ({
       target_type: p.target_type,
       target_name: p.target_name,
-      subscribe_filter: p.subscribe_filter,
-      events: p.events,
-      required_role: p.required_role,
-      auth_required: p.auth_required,
-    }))).replace(/'/g, "''")  // escape for SQL string literal
-
-    await proxyToolCall("execute_sql", {
-      project_id: projectId,
-      sql: `
-        INSERT INTO system.realtime_policies
-          (target_type, target_name, subscribe_filter, events, required_role, auth_required, updated_at)
-        SELECT target_type, target_name, subscribe_filter, events, required_role, auth_required, now()
-        FROM jsonb_to_recordset('${rowsJson}'::jsonb) AS r(
-          target_type text,
-          target_name text,
-          subscribe_filter text,
-          events text[],
-          required_role text,
-          auth_required boolean
-        )
-        ON CONFLICT (target_type, target_name) DO UPDATE SET
-          subscribe_filter = EXCLUDED.subscribe_filter,
-          events = EXCLUDED.events,
-          required_role = EXCLUDED.required_role,
-          auth_required = EXCLUDED.auth_required,
-          updated_at = now()
-      `,
-    })
-  }
+      subscribe_filter: p.subscribe_filter ?? null,
+      events: p.events ?? null,
+      required_role: p.required_role ?? null,
+      auth_required: p.auth_required !== false,
+    })),
+    delete_orphans: true,
+  })
 
-  if (toDelete.length > 0) {
-    // Build a safe tuple list. target_type is always 'table' or 'channel', target_name is user-provided.
-    const pairs = toDelete.map(p =>
-      `('${p.target_type}', '${String(p.target_name).replace(/'/g, "''")}')`
-    ).join(",")
-    await proxyToolCall("execute_sql", {
-      project_id: projectId,
-      sql: `
-        DELETE FROM system.realtime_policies
-        WHERE (target_type, target_name) IN (${pairs})
-      `,
-    })
+  if (result?.error) {
+    throw new Error(`sync_realtime_policies failed: ${result.error}`)
+  }
+  // Backward-compat: surface the legacy `{ upsert, delete }` shape that
+  // older code paths (and the diff tool) expect, in addition to the full
+  // API response.
+  const summary = result?.summary || { upserts: 0, deletes: 0, unchanged: 0 }
+  return {
+    upsert: summary.upserts ?? 0,
+    delete: summary.deletes ?? 0,
+    unchanged: summary.unchanged ?? 0,
+    applied_to: result?.applied_to ?? "live",
+    drafts_queued: result?.drafts_queued || undefined,
+    skipped: result?.skipped || undefined,
+    reason: result?.reason || undefined,
+    details: result?.details || undefined,
   }
-
-  return { upsert: toUpsert.length, delete: toDelete.length }
-}
-
-function policiesEqual(a, b) {
-  return a.target_type === b.target_type
-    && a.target_name === b.target_name
-    && (a.subscribe_filter || null) === (b.subscribe_filter || null)
-    && JSON.stringify(a.events || []) === JSON.stringify(b.events || [])
-    && (a.required_role || null) === (b.required_role || null)
-    && !!a.auth_required === !!b.auth_required
 }
 
 // ─── Tool ──────────────────────────────────────────────────────────────────
@@ -252,9 +236,11 @@ function policiesEqual(a, b) {
 export const dypaiPushTool = {
   name: "dypai_push",
   description:
-    "Apply the local ./dypai/ state to the remote project: creates, updates, and optionally deletes endpoints. " +
-    "ALWAYS run dypai_diff first to preview the plan. This tool mutates remote state. " +
-    "By default, endpoints in remote but missing locally are kept (safe). Pass delete_orphans: true to delete them.",
+    "BACKEND ONLY — applies the local ./dypai/ state (endpoints, realtime policies) to the remote project as DRAFTS. " +
+    "Does NOT touch the live site by itself: changes are staged in `system.config_drafts` and only become live after `manage_drafts(operation:'publish', confirm:true)`. Safe to iterate freely. " +
+    "ALWAYS run dypai_diff first to preview what will be staged. " +
+    "Frontend code is not affected — use `manage_frontend` for that. " +
+    "By default, endpoints in remote but missing locally are kept (safe). Pass delete_orphans: true to stage their deletion as a draft as well.",
   inputSchema: {
     type: "object",
     properties: {
@@ -397,7 +383,16 @@ export const dypaiPushTool = {
     // Group operations are sequential because they're fast (a handful of
     // groups typically) and we need mapsCtx mutations to be race-free.
     const CONCURRENCY = 5
-    const applied = { created: [], updated: [], deleted: [], groups_created: [], groups_deleted: [] }
+    // `applied.*_drafts` tracks the per-op subset that the API staged as
+    // drafts (default behavior). The lists in `created/updated/deleted`
+    // include all successful ops — drafts and direct-write — so existing
+    // callers and tests don't break. Drafts are also broken out for the
+    // summary and `next_step` so the user knows to publish.
+    const applied = {
+      created: [], updated: [], deleted: [],
+      created_drafts: [], updated_drafts: [], deleted_drafts: [],
+      groups_created: [], groups_deleted: [],
+    }
     const errors = []
 
     // Phase 1 — create missing groups BEFORE any endpoint is created,
@@ -414,8 +409,9 @@ export const dypaiPushTool = {
     await runWithConcurrency(plan.create, CONCURRENCY, async (item) => {
       try {
         const canonical = localToCanonical(local.byName[item.name], remote.mapsCtx)
-        await applyCreate(canonical, targetProjectId)
+        const res = await applyCreate(canonical, targetProjectId)
         applied.created.push(item.name)
+        if (isDraftResponse(res)) applied.created_drafts.push(item.name)
       } catch (e) {
         errors.push({ op: "create", endpoint: item.name, error: e.message })
       }
@@ -426,8 +422,9 @@ export const dypaiPushTool = {
         const canonical = localToCanonical(local.byName[item.name], remote.mapsCtx)
         const endpointId = remote.byName[item.name]?.id
         if (!endpointId) throw new Error("endpoint_id missing from remote state")
-        await applyUpdate(canonical, endpointId, targetProjectId)
+        const res = await applyUpdate(canonical, endpointId, targetProjectId)
         applied.updated.push({ name: item.name, changed_fields: item.changedFields })
+        if (isDraftResponse(res)) applied.updated_drafts.push(item.name)
       } catch (e) {
         errors.push({ op: "update", endpoint: item.name, error: e.message })
       }
@@ -437,8 +434,9 @@ export const dypaiPushTool = {
       try {
         const endpointId = remote.byName[item.name]?.id
         if (!endpointId) throw new Error("endpoint_id missing from remote state")
-        await applyDelete(endpointId, targetProjectId)
+        const res = await applyDelete(endpointId, targetProjectId)
         applied.deleted.push(item.name)
+        if (isDraftResponse(res)) applied.deleted_drafts.push(item.name)
       } catch (e) {
         errors.push({ op: "delete", endpoint: item.name, error: e.message })
       }
@@ -474,13 +472,44 @@ export const dypaiPushTool = {
       ...applied.updated.map(u => u.name),
     ]
 
+    // How many ops landed in draft state. When `draftCount > 0` the user
+    // must run `manage_drafts(operation:'publish')` to expose the changes
+    // on live; tests against live won't see them yet. Realtime drafts are
+    // also counted — the API returns `applied_to: "draft"` and a
+    // `drafts_queued` array when realtime policies were staged.
+    const realtimeDraftCount = realtime && realtime.applied_to === "draft"
+      ? (realtime.drafts_queued?.length ?? ((realtime.upsert ?? 0) + (realtime.delete ?? 0)))
+      : 0
+    const draftCount =
+      applied.created_drafts.length +
+      applied.updated_drafts.length +
+      applied.deleted_drafts.length +
+      realtimeDraftCount
+    const endpointTotal =
+      applied.created.length + applied.updated.length + applied.deleted.length
+    const realtimeTotal = realtime ? ((realtime.upsert ?? 0) + (realtime.delete ?? 0)) : 0
+    const isDraftMode = draftCount > 0
+      && draftCount === endpointTotal + realtimeTotal
+
     return {
       success: errors.length === 0,
       applied: true,
+      // By default every endpoint mutation is staged as a draft, so the
+      // same push that "created 3 endpoints" actually queued 3 drafts.
+      // Surfacing this at the top level makes the difference unmissable
+      // for both human callers and the agent.
+      //   - "draft": every mutation in this push was staged as a draft
+      //   - "mixed": some drafts, some direct writes (rare)
+      //   - "live":  direct-write mode, mutation hit live immediately
+      mode: isDraftMode ? "draft" : draftCount > 0 ? "mixed" : "live",
+      pending_drafts: draftCount,
       summary: {
         created: applied.created.length,
+        created_drafts: applied.created_drafts.length,
         updated: applied.updated.length,
+        updated_drafts: applied.updated_drafts.length,
         deleted: applied.deleted.length,
+        deleted_drafts: applied.deleted_drafts.length,
         unchanged: plan.unchanged.length,
         groups_created: applied.groups_created.length,
         groups_deleted: applied.groups_deleted.length,
@@ -489,12 +518,16 @@ export const dypaiPushTool = {
       },
       details: applied,
       errors: errors.length ? errors : undefined,
-      // Only one next_step — and only when it's non-obvious
+      // Only one next_step — and only when it's non-obvious. Drafts win
+      // over the test suggestion because tests against live won't see
+      // the change until the drafts are promoted.
       next_step: errors.length
         ? "Fix the offending YAMLs and push again."
-        : changedNames.length
-          ? `Test changed endpoint(s) with dypai_test_endpoint: ${changedNames.slice(0, 3).join(", ")}${changedNames.length > 3 ? "…" : ""}`
-          : undefined,
+        : draftCount > 0
+          ? `${draftCount} change(s) saved as draft(s) — they're not live yet. Review with manage_drafts(operation:'list'), verify with dypai_test_endpoint(mode:'draft', endpoint:'<name>'), then publish with manage_drafts(operation:'publish', confirm:true) (or discard with manage_drafts(operation:'discard', confirm:true) to throw them away).`
+          : changedNames.length
+            ? `Test changed endpoint(s) with dypai_test_endpoint: ${changedNames.slice(0, 3).join(", ")}${changedNames.length > 3 ? "…" : ""}`
+            : undefined,
       hint: errors.some(e => /credential/i.test(e.error))
         ? "A referenced credential doesn't exist remotely. Create it in the dashboard (same name), then retry."
         : errors.some(e => /validation/i.test(e.error))