@dypai-ai/mcp 1.2.3 → 1.3.0

package/src/tools/sync/validate.js

@@ -13,9 +13,16 @@
  * mean push will refuse (unless skip_validation is passed).
  */
 
-import { readFile } from "fs/promises"
+import { readFile, writeFile, stat } from "fs/promises"
 import { join, resolve as resolvePath } from "path"
 import { fetchRemoteState, readLocalState, readLocalConfig, readLocalRealtime } from "./planner.js"
+import { proxyToolCall } from "../proxy.js"
+import { dumpPublicSchema } from "./schema-dump.js"
+
+/** schema.sql is considered "fresh" if it was written less than this ago.
+ * Within the freshness window, we trust it without re-checking the remote.
+ * Outside the window, sql_table_not_found triggers a remote verification. */
+const SCHEMA_FRESHNESS_MS = 5 * 60 * 1000  // 5 minutes
 
 /**
  * Validate dypai/realtime.yaml against known schemas/tables. Rules:
@@ -133,13 +140,15 @@ async function loadNodeCatalog(rootDir) {
     const parsed = JSON.parse(raw)
     const schemas = {}
     const knownTypes = new Set()
+    const isNonEmptyObj = (o) => o && typeof o === "object" && !Array.isArray(o) && Object.keys(o).length > 0
     for (const [nodeType, data] of Object.entries(parsed.nodes || {})) {
+      if (!data || typeof data !== "object") continue
       knownTypes.add(nodeType)
       schemas[nodeType] = {
         label: data.label,
         description: data.description,
-        inputs: data.inputs && Object.keys(data.inputs).length ? data.inputs : null,
-        outputs: data.outputs && Object.keys(data.outputs).length ? data.outputs : null,
+        inputs: isNonEmptyObj(data.inputs) ? data.inputs : null,
+        outputs: isNonEmptyObj(data.outputs) ? data.outputs : null,
       }
     }
     return { schemas, knownTypes, missing: false }
@@ -321,19 +330,27 @@ function validateEndpoint(entry, ctx) {
     // Heuristic: look like SQL (contains SELECT/INSERT/UPDATE/DELETE/WITH)
     if (/\b(SELECT|INSERT|UPDATE|DELETE|WITH)\b/i.test(value)) {
       for (const t of extractSqlTables(value)) referencedTables.add(t)
+
+      // NOTE: an earlier version of this validator warned about manual
+      // `'${current_user_id}'::uuid` casts as "redundant", under the assumption
+      // that the engine auto-cast UUID-shaped values. That auto-cast was
+      // removed because it broke postgres.js binding in production. Manual
+      // ::uuid casts are now legitimate again, so no warning is emitted here.
     }
   }
 
   // --- SQL table existence (if schema.sql available) ---
+  // Defer the actual error emission to runValidation: it batch-checks all
+  // missing tables against the remote in ONE query before deciding what's
+  // a real error vs a stale-local-schema. We just collect the misses here
+  // along with enough context for runValidation to emit per-endpoint errors.
   if (ctx.schemaTables) {
     for (const table of referencedTables) {
       if (!ctx.schemaTables.has(table)) {
-        diagnostics.push({
-          severity: "error",
-          rule: "sql_table_not_found",
-          endpoint: name, file,
-          message: `SQL references public.${table}, but that table does not exist in schema.sql.`,
-          fix_hint: `Check typos, or create the table first with execute_sql. Known tables: ${[...ctx.schemaTables].slice(0, 8).join(", ")}${ctx.schemaTables.size > 8 ? "…" : ""}`,
+        ctx.suspectedMissingTables.push({
+          table,
+          endpoint: name,
+          file,
         })
       }
     }
@@ -341,14 +358,144 @@ function validateEndpoint(entry, ctx) {
 
   // --- Per-node catalog-based validation (unknown type, missing/unknown params) ---
   for (const node of doc.workflow?.nodes || []) {
+    if (!node || typeof node !== "object") continue
+    // Tolerate both `type` and `node_type` (the codec accepts either).
+    const nodeType = node.type ?? node.node_type
+    // Legacy `start_trigger` node — the codec lifts it transparently, but
+    // surface a warning so the agent learns the canonical form (top-level trigger:).
+    if (nodeType === "start_trigger") {
+      diagnostics.push({
+        severity: "warn",
+        rule: "obsolete_start_trigger_node",
+        endpoint: name, file, loc: `workflow.nodes[${node.id}]`,
+        message: `'start_trigger' is no longer a node. The codec lifted it to the top-level trigger: block automatically — but please remove this node from the YAML.`,
+        fix_hint: "Move trigger config to top-level `trigger: { http_api: { auth_mode: jwt } }` (or webhook/schedule/telegram) and delete this node + any edges that referenced it.",
+      })
+      continue
+    }
+    if (!nodeType) {
+      diagnostics.push({
+        severity: "error",
+        rule: "missing_node_type",
+        endpoint: name, file, loc: `workflow.nodes[${node.id || "?"}]`,
+        message: `Node '${node.id || "(no id)"}' is missing 'type'.`,
+        fix_hint: "Add `type: <node_type>` to this node. Use `dypai_pull` to refresh `node-catalog.json` for the list of valid types.",
+      })
+      continue
+    }
+
+    // dypai_database — coherence checks for the new canonical operations.
+    if (nodeType === "dypai_database") {
+      const op = node.operation
+      const LEGACY_OPS = new Set(["select", "insert", "update", "delete", "upsert", "aggregate", "copy_to", "custom_query"])
+      if (op && LEGACY_OPS.has(op)) {
+        const suggested = (op === "custom_query") ? "query" : (op === "select") ? "query" : "mutation"
+        const example = suggested === "query"
+          ? `operation: query, query: "..."`
+          : `operation: mutation, table: "...", ${op}: { ... }${op === "delete" ? "" : ", where: { ... }"}`
+        diagnostics.push({
+          severity: "warn",
+          rule: "legacy_database_operation",
+          endpoint: name, file, loc: `workflow.nodes[${node.id}].operation`,
+          message: `Operation '${op}' is legacy. The canonical form is '${suggested}'.`,
+          fix_hint: `Replace with: ${example}. Both still execute today; use the canonical form for new endpoints.`,
+        })
+      }
+
+      // ── operation: mutation coherence ─────────────────────────────────────
+      // mutation requires `table:` and exactly one of insert/update/delete.
+      // Fields like `query`, `query_file`, `params` belong to `operation: query`
+      // and are silently ignored here — surface as ERROR so the agent reroutes.
+      if (op === "mutation") {
+        if (!node.table) {
+          diagnostics.push({
+            severity: "error",
+            rule: "mutation_missing_table",
+            endpoint: name, file, loc: `workflow.nodes[${node.id}]`,
+            message: `Node '${node.id}' uses 'operation: mutation' but is missing the required 'table:' field.`,
+            fix_hint: `Add 'table: <name>'. mutation also needs exactly one of: insert / update / delete.`,
+          })
+        }
+        const wantsInsert = node.insert !== undefined && node.insert !== null
+        const wantsUpdate = node.update !== undefined && node.update !== null
+        const wantsDelete = node.delete === true
+        const opCount = [wantsInsert, wantsUpdate, wantsDelete].filter(Boolean).length
+        if (opCount === 0) {
+          diagnostics.push({
+            severity: "error",
+            rule: "mutation_missing_action",
+            endpoint: name, file, loc: `workflow.nodes[${node.id}]`,
+            message: `Node '${node.id}' uses 'operation: mutation' but declares none of: insert / update / delete.`,
+            fix_hint: `Add ONE of: 'insert: { ... }', 'update: { ... } + where: { ... }', or 'delete: true + where: { ... }'.`,
+          })
+        } else if (opCount > 1) {
+          diagnostics.push({
+            severity: "error",
+            rule: "mutation_multiple_actions",
+            endpoint: name, file, loc: `workflow.nodes[${node.id}]`,
+            message: `Node '${node.id}' uses 'operation: mutation' with multiple actions set. Use one per node.`,
+            fix_hint: `Pick exactly one: insert OR update OR delete (split into separate nodes if you need more).`,
+          })
+        }
+        if ((wantsUpdate || wantsDelete) && !node.where) {
+          diagnostics.push({
+            severity: "error",
+            rule: "mutation_missing_where",
+            endpoint: name, file, loc: `workflow.nodes[${node.id}]`,
+            message: `Node '${node.id}' (mutation ${wantsUpdate ? "update" : "delete"}) is missing 'where:' — refusing to operate on every row.`,
+            fix_hint: `Add 'where: { id: \${input.id}, user_id: \${current_user_id} }' (or whatever filter applies).`,
+          })
+        }
+        // Foreign fields that belong to `operation: query`
+        const QUERY_ONLY = ["query", "query_file", "params"]
+        for (const k of QUERY_ONLY) {
+          if (node[k] !== undefined) {
+            diagnostics.push({
+              severity: "error",
+              rule: "mutation_with_query_field",
+              endpoint: name, file, loc: `workflow.nodes[${node.id}].${k}`,
+              message: `Node '${node.id}' uses 'operation: mutation' but declares '${k}' (only valid for 'operation: query').`,
+              fix_hint: `If this is raw SQL, change to 'operation: query'. If it's declarative CRUD, remove '${k}' and use insert/update/delete + where.`,
+            })
+          }
+        }
+      }
+
+      // ── operation: query coherence ────────────────────────────────────────
+      // query needs SQL: either inline `query:` or external `query_file:`.
+      // Fields like `table`, `insert`, `update`, `delete`, `where`, `on_conflict`,
+      // `returning` belong to `operation: mutation` and are ignored here.
+      if (op === "query") {
+        if (!node.query && !node.query_file) {
+          diagnostics.push({
+            severity: "error",
+            rule: "query_missing_sql",
+            endpoint: name, file, loc: `workflow.nodes[${node.id}]`,
+            message: `Node '${node.id}' uses 'operation: query' but is missing both 'query:' and 'query_file:'.`,
+            fix_hint: `Add 'query: "SELECT ..."' for inline SQL, or 'query_file: sql/<name>.sql' for an external file.`,
+          })
+        }
+        const MUTATION_ONLY = ["table", "insert", "update", "delete", "where", "on_conflict", "returning"]
+        const foreign = MUTATION_ONLY.filter(k => node[k] !== undefined && node[k] !== false)
+        if (foreign.length > 0) {
+          diagnostics.push({
+            severity: "error",
+            rule: "query_with_mutation_field",
+            endpoint: name, file, loc: `workflow.nodes[${node.id}]`,
+            message: `Node '${node.id}' uses 'operation: query' but declares mutation-only fields: ${foreign.join(", ")}.`,
+            fix_hint: `If this is declarative CRUD, change to 'operation: mutation'. If it's raw SQL, remove ${foreign.join(", ")} from the node.`,
+          })
+        }
+      }
+    }
     // node_type exists in catalog?
-    if (ctx.knownTypes.size && !ctx.knownTypes.has(node.type)) {
-      const suggestions = [...ctx.knownTypes].filter(t => levenshteinSmall(t, node.type) <= 2).slice(0, 3)
+    if (ctx.knownTypes.size && !ctx.knownTypes.has(nodeType)) {
+      const suggestions = [...ctx.knownTypes].filter(t => levenshteinSmall(t, nodeType) <= 2).slice(0, 3)
       diagnostics.push({
         severity: "error",
         rule: "unknown_node_type",
         endpoint: name, file, loc: `workflow.nodes[${node.id}].type`,
-        message: `Node type '${node.type}' is not registered.`,
+        message: `Node type '${nodeType}' is not registered.`,
         fix_hint: suggestions.length
           ? `Did you mean: ${suggestions.join(", ")}?`
           : `Run dypai_pull to refresh node-catalog.json. Or call search_nodes to discover.`,
@@ -357,19 +504,46 @@ function validateEndpoint(entry, ctx) {
     }
 
     // Schema-based parameter validation (only when we have a schema for this node_type)
-    const schema = ctx.catalog[node.type]
+    const schema = ctx.catalog[nodeType]
     if (schema?.inputs?.properties) {
       const { properties, required = [] } = schema.inputs
       // Ignore node metadata keys (id, type, variable, return, credential, *_file) — they're not "params"
       const META_KEYS = new Set(["id", "type", "variable", "return", "credential", "query_file", "code_file", "system_prompt_file"])
       const paramKeys = Object.keys(node).filter(k => !META_KEYS.has(k))
 
-      // Required params present? Severity: warn (not error) because current
-      // engine node_catalog schemas list all conditional params as "required"
-      // (e.g. dypai_database flags `data` AND `query` both required regardless
-      // of `operation`). Once schemas model conditional required properly
-      // (oneOf / dependentRequired), we can bump this back to error.
-      for (const req of required) {
+      // Required-param check.
+      //
+      // We respect the schema as-is: top-level `required` are universally
+      // required; `allOf[].if/then` blocks express conditional requirements
+      // driven by sibling fields (e.g. `query` is required only when
+      // `operation: query`). The engine's parametersToJsonSchema emits these
+      // automatically from displayOptions.show — so the catalog is the single
+      // source of truth and we don't hardcode node names anywhere.
+      const allRequired = []
+
+      // Universal requirements
+      for (const req of required) allRequired.push({ name: req, condition: null })
+
+      // Conditional requirements from allOf[]
+      const allOf = Array.isArray(schema.inputs?.allOf) ? schema.inputs.allOf : []
+      for (const rule of allOf) {
+        const ifProps = rule?.if?.properties || {}
+        const thenRequired = rule?.then?.required || []
+        const selectorField = Object.keys(ifProps)[0]
+        const selectorValues = ifProps[selectorField]?.enum || []
+        if (!selectorField || selectorValues.length === 0) continue
+        // Activates only if the node's value for selectorField matches one of selectorValues.
+        const nodeValue = node[selectorField]
+        if (!selectorValues.includes(nodeValue)) continue
+        for (const req of thenRequired) {
+          allRequired.push({
+            name: req,
+            condition: `${selectorField}=${nodeValue}`,
+          })
+        }
+      }
+
+      for (const { name: req, condition } of allRequired) {
         if (!paramKeys.includes(req)) {
           const hasFileEquivalent = META_KEYS.has(`${req}_file`) && node[`${req}_file`]
           if (!hasFileEquivalent) {
@@ -377,8 +551,12 @@ function validateEndpoint(entry, ctx) {
               severity: "warn",
               rule: "missing_required_param",
               endpoint: name, file, loc: `workflow.nodes[${node.id}]`,
-              message: `Node '${node.id}' (type '${node.type}') may be missing parameter '${req}'.`,
-              fix_hint: `Schema lists required: [${required.join(", ")}]. Verify this param is actually needed for your operation.`,
+              message: condition
+                ? `Node '${node.id}' (type '${nodeType}') is missing parameter '${req}' required when ${condition}.`
+                : `Node '${node.id}' (type '${nodeType}') is missing required parameter '${req}'.`,
+              fix_hint: condition
+                ? `Add '${req}: ...' to this node, or change the value of '${condition.split("=")[0]}'.`
+                : `Add '${req}: ...' to this node.`,
             })
           }
         }
@@ -393,7 +571,7 @@ function validateEndpoint(entry, ctx) {
             severity: "warn",
             rule: "unknown_param",
             endpoint: name, file, loc: `workflow.nodes[${node.id}].${key}`,
-            message: `Node '${node.id}' (type '${node.type}') has unknown parameter '${key}'.`,
+            message: `Node '${node.id}' (type '${nodeType}') has unknown parameter '${key}'.`,
             fix_hint: suggestions.length
               ? `Did you mean: ${suggestions.join(", ")}?`
               : `Valid params: ${knownKeys.slice(0, 8).join(", ")}${knownKeys.length > 8 ? "…" : ""}`,
@@ -438,6 +616,7 @@ function validateEndpoint(entry, ctx) {
 
   // --- Credential references ---
   for (const node of doc.workflow?.nodes || []) {
+    if (!node || typeof node !== "object") continue
     const cred = node.credential
     if (cred && !ctx.remoteCredentials.has(cred)) {
       diagnostics.push({
@@ -452,7 +631,8 @@ function validateEndpoint(entry, ctx) {
     }
 
     // Agent tool references
-    if (node.type === "agent" && Array.isArray(node.tools)) {
+    const nodeType = node.type ?? node.node_type
+    if (nodeType === "agent" && Array.isArray(node.tools)) {
       for (const toolName of node.tools) {
         if (!ctx.toolEndpoints.has(toolName)) {
           diagnostics.push({
@@ -472,6 +652,65 @@ function validateEndpoint(entry, ctx) {
   return diagnostics
 }
 
+// ─── Schema staleness detection ─────────────────────────────────────────────
+
+/**
+ * Returns mtime of dypai/schema.sql as Date, or null if missing.
+ */
+async function getSchemaFileAge(rootDir) {
+  try {
+    const s = await stat(join(rootDir, "schema.sql"))
+    return s.mtime
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Returns true if schema.sql was written less than SCHEMA_FRESHNESS_MS ago.
+ * Within the freshness window we skip remote staleness checks.
+ */
+async function isSchemaFresh(rootDir) {
+  const mtime = await getSchemaFileAge(rootDir)
+  if (!mtime) return false
+  return (Date.now() - mtime.getTime()) < SCHEMA_FRESHNESS_MS
+}
+
+/**
+ * Batch-check which of the given tables exist in the remote DB. Returns the
+ * subset that DO exist. Single SQL round-trip via execute_sql.
+ *
+ * Tolerant on failure: if the check itself fails (auth, network), returns null
+ * and the caller treats every missing table as a real "table not found" error.
+ */
+async function verifyTablesInRemote(missingTables, projectId) {
+  if (!missingTables.length) return new Set()
+  if (!projectId) return null
+  try {
+    const list = missingTables.map(t => `'${String(t).replace(/'/g, "''")}'`).join(",")
+    const sql = `SELECT table_name FROM information_schema.tables WHERE table_schema = 'public' AND table_name IN (${list})`
+    const result = await proxyToolCall("execute_sql", { project_id: projectId, sql })
+    const rows = Array.isArray(result?.rows) ? result.rows : []
+    return new Set(rows.map(r => r.table_name).filter(Boolean))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Refresh dypai/schema.sql from the remote. Best-effort — if it fails the
+ * caller continues with the existing local schema (just logs the warning).
+ */
+async function refreshSchemaSql(rootDir, projectId) {
+  try {
+    const fresh = await dumpPublicSchema(projectId)
+    await writeFile(join(rootDir, "schema.sql"), fresh, "utf8")
+    return true
+  } catch {
+    return false
+  }
+}
+
 // ─── Tool ───────────────────────────────────────────────────────────────────
 
 export async function runValidation(rootDir, projectId) {
@@ -502,6 +741,9 @@ export async function runValidation(rootDir, projectId) {
     catalog: nodeCatalog.schemas,
     knownTypes: nodeCatalog.knownTypes,
     fileByName: Object.fromEntries(Object.values(local.byName).map(e => [e.doc.name, `endpoints/${e.doc.name}.yaml`])),
+    // Collected during per-endpoint pass; resolved against the remote AFTER
+    // all endpoints are checked (one batch query instead of N).
+    suspectedMissingTables: [],
   }
 
   const diagnostics = []
@@ -509,6 +751,66 @@ export async function runValidation(rootDir, projectId) {
     diagnostics.push(...validateEndpoint(entry, ctx))
   }
 
+  // ── Resolve suspected missing tables against the remote ──────────────────
+  // The local schema.sql may be stale (someone pushed DDL outside our flow).
+  // Verify each missing table against information_schema BEFORE crying error.
+  // Skip the remote check entirely if schema.sql is fresh (recently refreshed).
+  let schemaWasRefreshed = false
+  if (ctx.suspectedMissingTables.length > 0) {
+    const uniqueTables = [...new Set(ctx.suspectedMissingTables.map(s => s.table))]
+    const fresh = await isSchemaFresh(rootDir)
+    let realMissing = new Set(uniqueTables)
+
+    if (!fresh && targetProjectId) {
+      // Schema is old → ask the remote which of these tables actually exist.
+      const existsInRemote = await verifyTablesInRemote(uniqueTables, targetProjectId)
+      if (existsInRemote !== null) {
+        // Remove tables that exist remotely from the "real missing" set.
+        const nowKnown = [...uniqueTables].filter(t => existsInRemote.has(t))
+        realMissing = new Set(uniqueTables.filter(t => !existsInRemote.has(t)))
+
+        if (nowKnown.length > 0) {
+          // Local schema was stale — refresh it so subsequent runs are accurate.
+          schemaWasRefreshed = await refreshSchemaSql(rootDir, targetProjectId)
+          // Add the now-known tables to ctx.schemaTables so any callers that
+          // re-use this validation result see a consistent picture.
+          if (ctx.schemaTables) for (const t of nowKnown) ctx.schemaTables.add(t)
+          diagnostics.push({
+            severity: "warn",
+            rule: "schema_was_stale",
+            message: `Local dypai/schema.sql was out of date — auto-refreshed from remote (added: ${nowKnown.join(", ")}).`,
+            fix_hint: "No action needed. The local file is now in sync.",
+          })
+        }
+      }
+    }
+
+    // Emit one error per (endpoint, missing_table) for the tables that really don't exist.
+    const knownTablesList = ctx.schemaTables
+      ? [...ctx.schemaTables].slice(0, 8).join(", ") + (ctx.schemaTables.size > 8 ? "…" : "")
+      : "(none yet)"
+    for (const { table, endpoint, file } of ctx.suspectedMissingTables) {
+      if (realMissing.has(table)) {
+        diagnostics.push({
+          severity: "error",
+          rule: "sql_table_not_found",
+          endpoint, file,
+          message: `SQL references public.${table}, but that table does not exist in the database.`,
+          fix_hint:
+            `Create it first via execute_sql. Example:\n` +
+            `  execute_sql({ sql: "CREATE TABLE public.${table} (\\n` +
+            `    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\\n` +
+            `    user_id TEXT NOT NULL,\\n` +
+            `    created_at TIMESTAMPTZ DEFAULT NOW()\\n` +
+            `  );" })\n` +
+            `IMPORTANT: user_id must be TEXT (not UUID) — better-auth's auth.user.id is a 32-char nanoid stored as TEXT. ` +
+            `(Add other columns matching what your endpoint INSERTs.) ` +
+            `schema.sql will auto-refresh after the DDL. Existing tables: ${knownTablesList}`,
+        })
+      }
+    }
+  }
+
   // Realtime YAML rules
   diagnostics.push(...await validateRealtime(rootDir, ctx))
 
@@ -556,12 +858,23 @@ export const dypaiValidateTool = {
   },
   async execute({ project_id, root_dir = "./dypai" } = {}) {
     const rootDir = resolvePath(process.cwd(), root_dir)
-    const result = await runValidation(rootDir, project_id)
-    return {
-      ...result,
-      hint: result.success
-        ? undefined
-        : `${result.summary.errors} error(s) would cause runtime failures. Fix them, or push with skip_validation: true to override (not recommended).`,
+    try {
+      const result = await runValidation(rootDir, project_id)
+      return {
+        ...result,
+        hint: result.success
+          ? undefined
+          : `${result.summary.errors} error(s) would cause runtime failures. Fix them, or push with skip_validation: true to override (not recommended).`,
+      }
+    } catch (e) {
+      // Surface the real stack so failures during validation don't look like
+      // a generic "undefined.length" mystery to the agent.
+      return {
+        success: false,
+        error: `Validation crashed: ${e.message}`,
+        stack: (e.stack || "").split("\n").slice(0, 5).join("\n"),
+        hint: "This is a bug in the local MCP. Report the stack above; in the meantime you can pass skip_validation: true to dypai_push to bypass.",
+      }
     }
   },
 }

package/src/tools/sync.js

@@ -0,0 +1,133 @@
+/**
+ * syncFromRemote — Mirror of `deployFromSource`.
+ *
+ * Fetches the project's source from the API (which reads it from GitHub
+ * server-side and returns a JSON `{ files: [{ path, content }] }` payload —
+ * same shape the deploy uses, just reversed direction) and writes each file
+ * to disk under `targetDirectory`.
+ *
+ * Safety: refuses to write into a directory that already contains a
+ * `package.json` unless `overwrite: true`. When overwriting, only files
+ * present in the remote ZIP are touched — local-only files (.env,
+ * node_modules, .vscode, etc.) are preserved.
+ */
+
+import { writeFileSync, mkdirSync, existsSync } from "fs"
+import { join, dirname } from "path"
+import { api } from "../api.js"
+
+export async function syncFromRemote({ project_id, targetDirectory, overwrite = false }) {
+  if (!project_id) {
+    return { success: false, error: "project_id is required." }
+  }
+  if (!targetDirectory) {
+    return { success: false, error: "targetDirectory is required (absolute path where the source will be written)." }
+  }
+
+  // Refuse to clobber an existing project unless asked.
+  // Heuristic: presence of package.json (or any file at the root) means "in use".
+  if (existsSync(join(targetDirectory, "package.json")) && !overwrite) {
+    return {
+      success: false,
+      error: `targetDirectory '${targetDirectory}' already contains a package.json. ` +
+        `Pass overwrite: true to replace files (local-only files like .env are preserved). ` +
+        `Or pick an empty directory.`,
+    }
+  }
+
+  // Pull the JSON payload — same shape the deploy uses, just reversed.
+  let payload
+  try {
+    payload = await api.get(`/api/engine/${project_id}/frontend/source`)
+  } catch (e) {
+    return { success: false, error: `Failed to fetch source from API: ${e.message}` }
+  }
+
+  if (!payload || !Array.isArray(payload.files) || payload.files.length === 0) {
+    return {
+      success: false,
+      error: "API returned no files. The project may be empty or the GitHub repo unreachable.",
+      raw: payload,
+    }
+  }
+
+  // Make sure the target directory exists. mkdir is recursive, idempotent.
+  try {
+    mkdirSync(targetDirectory, { recursive: true })
+  } catch (e) {
+    return { success: false, error: `Could not create targetDirectory '${targetDirectory}': ${e.message}` }
+  }
+
+  let written = 0
+  const failures = []
+
+  for (const file of payload.files) {
+    if (!file?.path || typeof file.content !== "string") {
+      failures.push({ path: file?.path ?? "<unknown>", reason: "Malformed file entry from API" })
+      continue
+    }
+
+    // Defense in depth: refuse anything that tries to escape targetDirectory.
+    // The API strips the GitHub wrapper but we re-validate so a future bug
+    // there can't lead to writes outside the intended folder.
+    if (file.path.startsWith("/") || file.path.includes("..")) {
+      failures.push({ path: file.path, reason: "Suspicious path (absolute or contains '..'); skipped." })
+      continue
+    }
+
+    const fullPath = join(targetDirectory, file.path)
+    try {
+      mkdirSync(dirname(fullPath), { recursive: true })
+      // `content` is base64 from the API (uniform encoding, binary-safe —
+      // same convention as the deploy). Decode to a Buffer so binaries
+      // (images, fonts, etc.) round-trip cleanly.
+      writeFileSync(fullPath, Buffer.from(file.content, "base64"))
+      written++
+    } catch (e) {
+      failures.push({ path: file.path, reason: e.message })
+    }
+  }
+
+  // Structured next_steps so the agent can act without re-prompting the LLM.
+  // `npm install` is always suggested (idempotent and cheap). When we overwrote
+  // an existing project the user's local files removed upstream are NOT
+  // deleted by sync — flag that so the agent can surface it.
+  const next_steps = ["Run `npm install` in the target directory if dependencies changed."]
+  if (overwrite) {
+    next_steps.push(
+      "Sync does not delete local files that were removed upstream. Review the target directory for stale files and remove them manually if needed."
+    )
+  }
+
+  // .env is gitignored → the source API does NOT return it → the frontend won't
+  // know the engine URL. If it's missing after sync, tell the agent to create it.
+  // Engine URL convention: https://<project_id>.dypai.app (override with DYPAI_ENGINE_BASE).
+  const envMissing = !existsSync(join(targetDirectory, ".env"))
+  if (envMissing) {
+    const engineBase = process.env.DYPAI_ENGINE_BASE || "dypai.app"
+    const engineUrl = `https://${project_id}.${engineBase}`
+    next_steps.push(
+      `Create .env in ${targetDirectory} with \`VITE_DYPAI_URL=${engineUrl}\` (and \`VITE_PROJECT_ID=${project_id}\`). ` +
+      `Use NEXT_PUBLIC_DYPAI_URL instead of VITE_DYPAI_URL for Next.js projects. ` +
+      `The frontend SDK reads this to reach the engine — without .env, API calls will fail with network errors.`
+    )
+  }
+
+  return {
+    success: written > 0,
+    targetDirectory,
+    files_written: written,
+    files_failed: failures.length,
+    failures: failures.length > 0 ? failures : undefined,
+    total_bytes: payload.total_bytes ?? null,
+    ref: payload.ref ?? "main",
+    repo: payload.repo ?? null,
+    overwrite,
+    env_file_missing: envMissing,
+    next_steps,
+    message:
+      `Synced ${written} file(s) to ${targetDirectory}` +
+      (failures.length > 0 ? ` (${failures.length} failed — see failures[])` : "") +
+      ". See next_steps[].",
+  }
+}

package/src/tools/trace-summarize.js

@@ -113,6 +113,14 @@ export function summarizeTrace(trace, mode = "smart") {
         type: n.error?.type,
         stack: truncateString(n.error?.stack, 800),
       }
+      // Preserve the engine's pre-computed fix_hint and category so the
+      // agent gets actionable guidance without us re-deriving it.
+      if (n.fix_hint || n.error?.fix_hint) {
+        base.fix_hint = truncateString(n.fix_hint || n.error?.fix_hint)
+      }
+      if (n.error_category || n.error?.category) {
+        base.error_category = n.error_category || n.error?.category
+      }
       // failure_snapshot: reduce to a key outline — not full values
       if (n.failure_snapshot) {
         const snap = n.failure_snapshot