@dypai-ai/mcp 1.4.1 → 1.4.2

package/package.json

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

package/src/index.js

@@ -103,7 +103,7 @@ const REMOTE_TOOLS = [
   // ── Project ───────────────────────────────────────────────────────────────
   { name: "list_projects", description: "Lists all projects you have access to across your organizations. Returns project id, name, description, organization, subscription plan, and status. Use this as the first step to discover which projects are available, then pass project_id to other tools.", inputSchema: { type: "object", properties: { organization_id: { type: "string", description: "Optional. Filter projects by organization UUID." } }, required: [] } },
   { name: "get_project", description: "Gets detailed information about a specific project. Returns project name, description, organization, plan, status, engine URL, frontend slug, and timestamps.", inputSchema: { type: "object", properties: { project_id: { type: "string" } }, required: ["project_id"] } },
-  { name: "create_project", description: "Create a new DYPAI project (free plan). Creates a full project with database, engine, and hosting. Provisioning takes ~1 minute.\n\nIMPORTANT: before calling this, check for a matching template with `search_project_templates`. Passing a `template_slug` drops in a ready-made schema + endpoints + UI that cover 70% of common app types (clinic, gym, waitlist, SaaS, e-commerce, landing, etc.). Only create a blank project if nothing matches — starting blank costs the user hours of boilerplate.", inputSchema: { type: "object", properties: { name: { type: "string", description: "Project name (e.g. 'My Veterinary App')" }, organization_id: { type: "string", description: "Optional. Uses default org if omitted." }, description: { type: "string" }, template_slug: { type: "string", description: "RECOMMENDED. Project template slug to start from (e.g. 'clinic', 'gym', 'waitlist', 'blank'). Always call search_project_templates first to find the best match for what the user asked. Only omit this / use 'blank' when nothing fits." } }, required: ["name"] } },
+  { name: "create_project", description: "Create a new DYPAI project (free plan). Creates a full project with database, engine, GitHub repo, and frontend hosting. BLOCKS by default until provisioning finishes (~60s typical, 120s max) — when it returns, the project_id is ready to use with execute_sql, endpoint tools, etc. Pass wait_until_ready:false for batch flows.\n\nName collision: if another project in the same org already uses the name (case-insensitive), returns {error:'name_taken', existing_project_id, suggestions:[...]}. Pick a different name or use the existing project.\n\nIMPORTANT: before calling, check for a matching template with `search_project_templates`. Passing a `template_slug` drops in a ready-made schema + endpoints + UI that cover 70% of common app types. Only create a blank project if nothing matches.", inputSchema: { type: "object", properties: { name: { type: "string", description: "Project name (e.g. 'My Veterinary App')" }, organization_id: { type: "string", description: "Optional. Uses default org if omitted." }, description: { type: "string" }, template_slug: { type: "string", description: "RECOMMENDED. Project template slug to start from (e.g. 'clinic', 'gym', 'waitlist', 'blank'). Always call search_project_templates first to find the best match." }, wait_until_ready: { type: "boolean", description: "If true (default), blocks until provisioning completes and the project is ready for all operations. If false, returns immediately with status='provisioning' — caller must poll get_project before using.", default: true } }, required: ["name"] } },
   { name: "get_app_credentials", description: "Lists available credentials in the current application. Returns API keys, anon key, service role key, and engine URL needed for SDK configuration.", inputSchema: { type: "object", properties: { project_id: { type: "string" } }, required: [] } },
 
   // ── Database ──────────────────────────────────────────────────────────────
@@ -531,7 +531,7 @@ Any endpoint can be flagged \`tool: true\` to be callable by \`agent\` nodes. Ho
     │   └── create-order.test.yaml
     └── .dypai/               ← local cache, gitignored — DO NOT touch
         ├── deploy-manifest.json    ← SHA hashes from last deploy (delta engine)
-        └── media-manifest.json     ← media files uploaded to R2
+        └── media-manifest.json     ← media files uploaded to the storage bucket
 \`\`\`
 
 ### Where to put what
@@ -576,7 +576,7 @@ 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 R2 (auto-populated on deploy; see "Frontend deploy")
+- \`/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)
 
 ## Endpoint YAML skeleton (top-level fields)
@@ -785,7 +785,7 @@ 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.
-- **Frontend dev server + R2 media** → media files are auto-uploaded to R2 on deploy but \`vite dev\` doesn't proxy to R2. Run \`manage_frontend(sync)\` first to pull media to disk.
+- **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
 
@@ -821,7 +821,7 @@ The deploy is delta by default: only files changed since last deploy are sent. L
 - \`manage_domain\` — custom domains. \`add\` returns the CNAME to configure. \`verify\` forces DNS/SSL recheck. → \`search_docs("manage domain")\`.
 - \`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 R2, registers. Max 100MB/file. → \`search_docs("file storage")\`.
+- \`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")\`.
 
 ## Deep docs — search_docs topic map
 
@@ -897,7 +897,7 @@ async function handleRequest(msg) {
           let finalArgs = withProjectContext(toolDef, args || {})
 
           // manage_storage.upload_file is orchestrated LOCALLY (filesystem →
-          // sign → direct PUT to R2 → verify). It's listed under manage_storage
+          // sign → direct PUT to the bucket → verify). It's listed under manage_storage
           // so the agent sees one unified tool, but the binary never travels
           // through the MCP transport — that would saturate the remote pod on
           // large files. See tools/storage.js for the 3-step flow.

package/src/tools/storage.js

@@ -10,7 +10,7 @@
  * the frontend SDK:
  *
  *   1. Ask the remote MCP → API for a signed PUT URL (op: sign_upload).
- *   2. PUT the file binary DIRECTLY to R2 from the local machine (no infra hop).
+ *   2. PUT the file binary DIRECTLY to the storage bucket from the local machine (no infra hop).
  *   3. Ask the remote MCP → API to register the object (op: verify_upload).
  *
  * Net effect: the agent just calls `manage_storage(operation:"upload_file",
@@ -34,7 +34,7 @@ import { updateMediaManifest } from "./deploy.js"
 const MAX_UPLOAD_BYTES = 100 * 1024 * 1024
 
 // Extensions we know how to MIME-type without shelling out. Everything else
-// falls back to application/octet-stream, which R2 accepts fine — the browser
+// falls back to application/octet-stream, which the bucket accepts fine — the browser
 // just won't preview it inline.
 const MIME_BY_EXT = {
   // Images
@@ -169,7 +169,7 @@ export async function uploadFile({
     return { success: false, error: "sign_upload returned an invalid payload (no upload_url or file_path)." }
   }
 
-  // ── Step 2: direct PUT to R2 ────────────────────────────────────────────
+  // ── Step 2: direct PUT to the bucket ────────────────────────────────────
   let buf
   try {
     buf = readFileSync(local_path)
@@ -190,11 +190,11 @@ export async function uploadFile({
       const detail = await safeReadBody(res)
       return {
         success: false,
-        error: `R2 PUT failed with status ${res.status}. ${detail ? `Detail: ${detail.slice(0, 300)}` : ""}`.trim(),
+        error: `Storage upload failed with status ${res.status}. ${detail ? `Detail: ${detail.slice(0, 300)}` : ""}`.trim(),
       }
     }
   } catch (e) {
-    return { success: false, error: `Direct upload to R2 failed: ${e.message}` }
+    return { success: false, error: `Direct upload to storage failed: ${e.message}` }
   }
 
   // ── Step 3: verify_upload ───────────────────────────────────────────────
@@ -213,7 +213,7 @@ export async function uploadFile({
   } catch (e) {
     return {
       success: false,
-      error: `verify_upload failed (the file WAS uploaded to R2 but not registered): ${e.message}. You can retry the upload — verify_upload is idempotent on (bucket, name).`,
+      error: `verify_upload failed (the file WAS uploaded to storage but not registered): ${e.message}. You can retry the upload — verify_upload is idempotent on (bucket, name).`,
     }
   }
 

package/src/tools/sync/codec.js

@@ -12,7 +12,12 @@
  * "doc" is the YAML-ready declarative object.
  */
 
-import { pullNodeParams, pushNodeParams } from "./transforms.js"
+import {
+  pullNodeParams,
+  pushNodeParams,
+  SQL_INLINE_MAX_CHARS,
+  PROMPT_INLINE_MAX_CHARS,
+} from "./transforms.js"
 
 // ─── Triggers (execution_config.triggers ↔ doc.trigger) ─────────────────────
 
@@ -23,14 +28,23 @@ function triggersToYaml(triggers = {}) {
   const telegramEnabled = triggers.telegram?.enabled
   for (const [kind, cfg] of Object.entries(triggers)) {
     if (!cfg) continue
+    // Strip `enabled` from every block — it's an engine-internal flag. The
+    // presence of the key in the YAML already means "enabled". Everything else
+    // (auth_mode, path, cron, timezone, payload, stripe_webhook,
+    // hmac_secret_env, methods, …) MUST round-trip unchanged — without this,
+    // webhook signature verification and schedule payloads silently disappear
+    // on pull → push.
     if (kind === "http_api" && cfg.enabled !== false) {
-      out.http_api = { auth_mode: cfg.auth_mode || "jwt" }
+      const { enabled, ...rest } = cfg
+      out.http_api = { auth_mode: rest.auth_mode || "jwt", ...rest }
     } else if (kind === "webhook" && cfg.enabled && !telegramEnabled) {
-      out.webhook = { path: cfg.path || "" }
+      const { enabled, ...rest } = cfg
+      // Ensure `path` is always present (default empty) but keep every other
+      // field the engine stored (methods, stripe_webhook, hmac_secret_env, etc.).
+      out.webhook = { path: rest.path || "", ...rest }
     } else if (kind === "schedule" && cfg.enabled) {
-      const s = { cron: cfg.cron }
-      if (cfg.timezone) s.timezone = cfg.timezone
-      out.schedule = s
+      const { enabled, ...rest } = cfg
+      out.schedule = { ...rest }
     } else if (kind === "manual" && cfg.enabled) {
       out.manual = true
     } else if (kind === "telegram" && cfg.enabled) {
@@ -54,15 +68,19 @@ function triggersToDb(trigger = {}) {
   const httpApi = trigger.http_api === true ? {} : trigger.http_api
   const hasNonHttpTrigger = trigger.webhook || trigger.schedule || trigger.manual || trigger.telegram
   if (httpApi) {
-    const authMode = httpApi.auth_mode || httpApi.mode || "jwt"
-    out.http_api = { enabled: true, auth_mode: authMode }
+    // Preserve all extra http_api fields (methods, rate_limit, etc.) while
+    // normalizing auth_mode / mode into auth_mode.
+    const { mode, auth_mode, ...rest } = httpApi
+    out.http_api = { enabled: true, auth_mode: auth_mode || mode || "jwt", ...rest }
   } else if (hasNonHttpTrigger) {
     // Non-HTTP trigger: disable http_api
     out.http_api = { enabled: false, auth_mode: "jwt" }
   }
   if (trigger.webhook) {
     const wh = trigger.webhook === true ? {} : trigger.webhook
-    out.webhook = { path: wh.path || "", enabled: true }
+    // Preserve all webhook fields (methods, stripe_webhook, hmac_secret_env,
+    // auth_mode, etc.) — previously only `path` survived push.
+    out.webhook = { path: wh.path || "", ...wh, enabled: true }
   }
   if (trigger.schedule) {
     out.schedule = { ...trigger.schedule, enabled: true }
@@ -84,13 +102,18 @@ function triggersToDb(trigger = {}) {
 // ─── Edges (source/target ↔ from/to) ────────────────────────────────────────
 
 function edgesToYaml(edges = []) {
-  return edges.map(e => {
+  // Pull-side: be symmetric with edgesToDb which throws on missing source/target.
+  // Instead of silently producing `{ from: undefined, to: undefined }`, we skip
+  // malformed edges entirely. This shouldn't happen with a healthy engine but
+  // protects the YAML from half-broken entries that would confuse diff/push.
+  return (edges || []).map(e => {
+    if (!e || typeof e !== "object" || !e.source || !e.target) return null
     const out = { from: e.source, to: e.target }
     if (e.condition) out.condition = e.condition
     if (e.source_handle) out.source_handle = e.source_handle
     if (e.target_handle) out.target_handle = e.target_handle
     return out
-  })
+  }).filter(Boolean)
 }
 
 function edgesToDb(edges = []) {
@@ -127,12 +150,24 @@ export function serializeEndpoint(row, mapsCtx) {
   const extractedFiles = []
   const emitFile = (path, content) => extractedFiles.push({ path, content })
 
-  // Pre-count nodes that produce extracted files — used to decide flat vs dotted filenames
+  // Pre-count nodes that produce extracted files — used to decide flat vs
+  // dotted filenames. Only count nodes whose content will actually be
+  // extracted (i.e. exceeds the inline threshold). Short content stays
+  // inline in the YAML and doesn't contribute to the count, so files don't
+  // get spurious `.node-id` suffixes when there's only one actual file.
+  // Thresholds are imported from transforms.js to keep the two sides in sync.
   const rawNodes = wf.nodes || []
-  const sqlNodeCount = rawNodes.filter(n => n.node_type === "dypai_database" && n.parameters?.query).length
-  const promptNodeCount = rawNodes.filter(n => n.node_type === "agent" && n.parameters?.system_prompt).length
+  const sqlNodeCount = rawNodes.filter(n =>
+    n.node_type === "dypai_database" &&
+    n.parameters?.query && n.parameters.query.length > SQL_INLINE_MAX_CHARS
+  ).length
+  const promptNodeCount = rawNodes.filter(n =>
+    n.node_type === "agent" &&
+    n.parameters?.system_prompt && n.parameters.system_prompt.length > PROMPT_INLINE_MAX_CHARS
+  ).length
   const codeNodeCount = rawNodes.filter(n =>
-    (n.node_type === "javascript_code" || n.node_type === "python_code") && n.parameters?.code
+    (n.node_type === "javascript_code" || n.node_type === "python_code") &&
+    n.parameters?.code && n.parameters.code.length > SQL_INLINE_MAX_CHARS
   ).length
 
   const nodes = rawNodes.map(node => {

package/src/tools/sync/diff.js

@@ -65,7 +65,8 @@ export const dypaiDiffTool = {
       stateSnapshot,
     })
 
-    const totalChanges = plan.create.length + plan.update.length + plan.delete.length
+    const groupChanges = (plan.groups?.create?.length || 0) + (plan.groups?.delete?.length || 0)
+    const totalChanges = plan.create.length + plan.update.length + plan.delete.length + groupChanges
     const hasConflicts = (plan.warnings || []).some(w => w.type === "remote_changed_since_pull")
 
     return {
@@ -76,6 +77,9 @@ export const dypaiDiffTool = {
         delete: plan.delete.length,
         unchanged: plan.unchanged.length,
         orphans_ignored: plan.orphansIgnored?.length || 0,
+        groups_create: plan.groups?.create?.length || 0,
+        groups_delete: plan.groups?.delete?.length || 0,
+        groups_unchanged: plan.groups?.unchanged?.length || 0,
         warnings: plan.warnings?.length || 0,
       },
       // Only include plan details when there are actual changes or warnings

package/src/tools/sync/planner.js

@@ -389,6 +389,24 @@ export function computePlan(local, remote, mapsCtx, { deleteOrphans = false, sta
   const plan = { create: [], update: [], delete: [], unchanged: [] }
   const warnings = []
 
+  // ── Groups plan ──────────────────────────────────────────────────────
+  // Groups are 100% folder-driven: each first-level subfolder in endpoints/
+  // IS a group. The remote is made to match the local folder structure
+  // unconditionally — new folders create groups, disappeared folders delete
+  // them. No flag, no opt-in. If a user later re-creates the folder, the
+  // group is re-created automatically. Zero friction.
+  const localGroups = new Set()
+  for (const entry of Object.values(local.byName)) {
+    const g = entry?.doc?.group
+    if (g) localGroups.add(g)
+  }
+  const remoteGroupNames = new Set(Object.keys(mapsCtx.groupNameToId || {}))
+  plan.groups = {
+    create: [...localGroups].filter(g => !remoteGroupNames.has(g)).sort(),
+    delete: [...remoteGroupNames].filter(g => !localGroups.has(g)).sort(),
+    unchanged: [...localGroups].filter(g => remoteGroupNames.has(g)).sort(),
+  }
+
   for (const name of Object.keys(local.byName)) {
     const entry = local.byName[name]
     const localCanonical = localToComparable(entry, mapsCtx)

package/src/tools/sync/push.js

@@ -109,6 +109,46 @@ async function applyDelete(endpointId, projectId) {
   return assertMutationOK(res, "delete", endpointId)
 }
 
+// ─── Group apply helpers ───────────────────────────────────────────────────
+//
+// Groups are fully folder-driven: create missing, delete orphans. The push
+// flow calls these BEFORE endpoint creates (so new endpoints can reference
+// freshly-created groups) and AFTER endpoint deletes (so groups are only
+// orphan once their endpoints are gone).
+
+async function applyGroupCreate(name, projectId, mapsCtx) {
+  const res = await proxyToolCall("manage_endpoint_groups", {
+    ...(projectId ? { project_id: projectId } : {}),
+    operation: "create",
+    name,
+  })
+  // Response shape: { group_id | id, name, ... }. Accept both.
+  const id = res?.group_id || res?.id
+  if (!id) {
+    throw new Error(`manage_endpoint_groups(create) did not return a group id for '${name}': ${JSON.stringify(res).slice(0, 200)}`)
+  }
+  // Update the in-memory map so subsequent endpoint resolutions use the new id.
+  mapsCtx.groupNameToId[name] = id
+  mapsCtx.groupIdToName[id] = name
+  return id
+}
+
+async function applyGroupDelete(name, projectId, mapsCtx) {
+  const id = mapsCtx.groupNameToId[name]
+  if (!id) {
+    throw new Error(`cannot delete group '${name}': no id in remote map (already gone?)`)
+  }
+  const res = await proxyToolCall("manage_endpoint_groups", {
+    ...(projectId ? { project_id: projectId } : {}),
+    operation: "delete",
+    group_id: id,
+  })
+  assertMutationOK(res, "delete group", name)
+  delete mapsCtx.groupNameToId[name]
+  delete mapsCtx.groupIdToName[id]
+  return id
+}
+
 // ─── Realtime policies sync ────────────────────────────────────────────────
 
 /**
@@ -320,7 +360,8 @@ export const dypaiPushTool = {
       deleteOrphans: delete_orphans,
       stateSnapshot,
     })
-    const totalChanges = plan.create.length + plan.update.length + plan.delete.length
+    const groupChanges = (plan.groups?.create?.length || 0) + (plan.groups?.delete?.length || 0)
+    const totalChanges = plan.create.length + plan.update.length + plan.delete.length + groupChanges
 
     // Block push on conflicts unless forced
     const conflicts = (plan.warnings || []).filter(w => w.type === "remote_changed_since_pull")
@@ -344,13 +385,32 @@ export const dypaiPushTool = {
       }
     }
 
-    // Apply in order: creates → updates → deletes.
-    // Within each phase we run with bounded concurrency (5) so pushing 50
-    // endpoints doesn't take 50 * 200ms = 10s — drops to ~2s on typical RTT.
+    // Apply in order:
+    //   1. Create missing groups (so endpoint creates can reference them)
+    //   2. Create endpoints
+    //   3. Update endpoints
+    //   4. Delete endpoints
+    //   5. Delete orphan groups (only once their endpoints are gone)
+    //
+    // Within each endpoint phase we run with bounded concurrency (5) so
+    // pushing 50 endpoints doesn't take 50 * 200ms = 10s — drops to ~2s.
+    // 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: [] }
+    const applied = { created: [], updated: [], deleted: [], groups_created: [], groups_deleted: [] }
     const errors = []
 
+    // Phase 1 — create missing groups BEFORE any endpoint is created,
+    // so endpoint creates can resolve their group_id correctly.
+    for (const groupName of plan.groups?.create || []) {
+      try {
+        await applyGroupCreate(groupName, targetProjectId, remote.mapsCtx)
+        applied.groups_created.push(groupName)
+      } catch (e) {
+        errors.push({ op: "create_group", group: groupName, error: e.message })
+      }
+    }
+
     await runWithConcurrency(plan.create, CONCURRENCY, async (item) => {
       try {
         const canonical = localToCanonical(local.byName[item.name], remote.mapsCtx)
@@ -384,6 +444,21 @@ export const dypaiPushTool = {
       }
     })
 
+    // Phase 5 — delete orphan groups AFTER endpoint deletes, so a group
+    // is only orphan once all its endpoints are gone. This runs only when
+    // delete_orphans=true OR when the group has no endpoints on either
+    // side (safe case). We always try: the remote API will refuse to
+    // delete a group that still has endpoints, which is the correct
+    // safety net.
+    for (const groupName of plan.groups?.delete || []) {
+      try {
+        await applyGroupDelete(groupName, targetProjectId, remote.mapsCtx)
+        applied.groups_deleted.push(groupName)
+      } catch (e) {
+        errors.push({ op: "delete_group", group: groupName, error: e.message })
+      }
+    }
+
     // Also reconcile realtime policies if realtime.yaml exists
     let realtime = null
     try {
@@ -407,6 +482,8 @@ export const dypaiPushTool = {
         updated: applied.updated.length,
         deleted: applied.deleted.length,
         unchanged: plan.unchanged.length,
+        groups_created: applied.groups_created.length,
+        groups_deleted: applied.groups_deleted.length,
         errors: errors.length,
         realtime: realtime || { skipped: true, reason: "no realtime.yaml" },
       },
@@ -434,5 +511,8 @@ function summaryFromPlan(plan) {
     delete: plan.delete.length,
     unchanged: plan.unchanged.length,
     orphans_ignored: plan.orphansIgnored?.length || 0,
+    groups_create: plan.groups?.create?.length || 0,
+    groups_delete: plan.groups?.delete?.length || 0,
+    groups_unchanged: plan.groups?.unchanged?.length || 0,
   }
 }

package/src/tools/sync/transforms.js

@@ -25,8 +25,9 @@
 
 // Only extract truly large content. Below these thresholds, SQL and prompts
 // stay inline in the YAML so the endpoint is one self-contained file.
-const SQL_INLINE_MAX_CHARS = 500
-const PROMPT_INLINE_MAX_CHARS = 800
+// Exported so codec.js can use the same cutoffs when deciding file naming.
+export const SQL_INLINE_MAX_CHARS = 500
+export const PROMPT_INLINE_MAX_CHARS = 800
 
 const shouldInlineSql = (q) => !q || q.length <= SQL_INLINE_MAX_CHARS
 
@@ -36,16 +37,23 @@ export const NODE_FIELD_TRANSFORMS = [
   {
     name: "credential",
     pull(params, ctx) {
-      if (params.credential_id && ctx.credIdToName[params.credential_id]) {
-        return { credential: ctx.credIdToName[params.credential_id] }
-      }
-      return {}
+      if (!params.credential_id) return {}
+      const name = ctx.credIdToName[params.credential_id]
+      if (name) return { credential: name }
+      // Credential UUID doesn't resolve to a known name (deleted cred, or map
+      // not loaded). Preserve the UUID as-is so the reference isn't silently
+      // lost on the next push — the agent or user can see there's a stale
+      // reference to fix.
+      return { credential: params.credential_id }
     },
     push(params, ctx) {
-      if (params.credential && ctx.credNameToId[params.credential]) {
-        return { credential_id: ctx.credNameToId[params.credential] }
-      }
-      return {}
+      if (!params.credential) return {}
+      const id = ctx.credNameToId[params.credential]
+      if (id) return { credential_id: id }
+      // Name didn't resolve — could be a UUID the user wrote directly, or a
+      // stale reference. Pass through; the engine validates on execute and
+      // returns a clean error.
+      return { credential_id: params.credential }
     },
     pullConsumes: ["credential_id"],
     pushConsumes: ["credential"],