@google/adk 2.4.0 → 2.5.0

package/dist/esm/sessions/database_session_service.js

@@ -28,7 +28,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { randomUUID } from "../utils/env_aware_utils.js";
+import { newId } from "../utils/id_provider.js";
 import { logger } from "../utils/logger.js";
 import {
   BaseSessionService,
@@ -71,9 +71,82 @@ async function importMikroOrm() {
 }
 __name(importMikroOrm, "importMikroOrm");
 import { isStaleSessionError, StaleSessionError as StaleSessionError2 } from "./stale_session_error.js";
+const STORAGE_UPDATE_MARKER_SYMBOL = /* @__PURE__ */ Symbol.for(
+  "google.adk.session.storageUpdateMarker"
+);
+function setStorageRevisionMarker(session, revision) {
+  Object.defineProperty(session, STORAGE_UPDATE_MARKER_SYMBOL, {
+    value: revision,
+    writable: true,
+    configurable: true,
+    enumerable: false
+  });
+}
+__name(setStorageRevisionMarker, "setStorageRevisionMarker");
+function getStorageRevisionMarker(session) {
+  return session[STORAGE_UPDATE_MARKER_SYMBOL];
+}
+__name(getStorageRevisionMarker, "getStorageRevisionMarker");
+const MAX_IN_QUERY_IDS = 500;
+async function sessionMatchesStorageRevision(txEm, session, eventsComplete, totalEventCount) {
+  const sessionWhere = {
+    appName: session.appName,
+    userId: session.userId,
+    sessionId: session.id
+  };
+  const latestStorageEvent = await txEm.findOne(StorageEvent, sessionWhere, {
+    orderBy: { timestamp: "DESC", id: "DESC" }
+  });
+  if (session.events.length === 0) {
+    if (latestStorageEvent !== null) {
+      return false;
+    }
+    if (totalEventCount !== void 0 && totalEventCount !== 0) {
+      return false;
+    }
+    return true;
+  }
+  if ((latestStorageEvent == null ? void 0 : latestStorageEvent.id) !== session.events[session.events.length - 1].id) {
+    return false;
+  }
+  if (totalEventCount !== void 0) {
+    const totalStored = await txEm.count(StorageEvent, sessionWhere);
+    if (totalStored !== totalEventCount) {
+      return false;
+    }
+  }
+  const knownIds = session.events.map((e) => e.id);
+  if (knownIds.length <= MAX_IN_QUERY_IDS) {
+    const unknownEventWhere = {
+      ...sessionWhere,
+      id: { $nin: knownIds }
+    };
+    if (!eventsComplete) {
+      unknownEventWhere.timestamp = {
+        $gte: new Date(session.events[0].timestamp)
+      };
+    }
+    return await txEm.count(StorageEvent, unknownEventWhere) === 0;
+  }
+  const filter = { ...sessionWhere };
+  if (!eventsComplete) {
+    filter.timestamp = { $gte: new Date(session.events[0].timestamp) };
+  }
+  const storedEvents = await txEm.find(StorageEvent, filter, {
+    fields: ["id"]
+  });
+  const knownSet = new Set(knownIds);
+  for (const stored of storedEvents) {
+    if (!knownSet.has(stored.id)) {
+      return false;
+    }
+  }
+  return true;
+}
+__name(sessionMatchesStorageRevision, "sessionMatchesStorageRevision");
 function formatDateTime(dateOrEpochMs) {
   const date = typeof dateOrEpochMs === "number" ? new Date(dateOrEpochMs) : dateOrEpochMs;
-  return date.toISOString().replace("T", " ").slice(0, 19);
+  return date.toISOString().replace("T", " ").replace("Z", "");
 }
 __name(formatDateTime, "formatDateTime");
 function isDatabaseConnectionString(uri) {
@@ -90,14 +163,25 @@ const _DatabaseSessionService = class _DatabaseSessionService extends BaseSessio
     this.initialized = false;
     if (typeof connectionStringOrOptions === "string") {
       this.connectionString = connectionStringOrOptions;
-      this.staleSession = (_a = options == null ? void 0 : options.staleSession) != null ? _a : "reject";
+      if (options) {
+        const { staleSession, ...mikroOptions } = options;
+        this.options = mikroOptions;
+        this.staleSession = staleSession != null ? staleSession : "reject";
+      } else {
+        this.staleSession = "reject";
+      }
     } else {
-      if (!connectionStringOrOptions.driver) {
+      const { staleSession: firstStaleSession, ...firstMikroOptions } = connectionStringOrOptions;
+      const { staleSession: secondStaleSession, ...secondMikroOptions } = options != null ? options : {};
+      const mergedMikroOptions = {
+        ...firstMikroOptions,
+        ...secondMikroOptions
+      };
+      if (!mergedMikroOptions.driver) {
         throw new Error("Driver is required when passing options object.");
       }
-      const { staleSession, ...mikroOptions } = connectionStringOrOptions;
-      this.options = mikroOptions;
-      this.staleSession = staleSession != null ? staleSession : "reject";
+      this.options = mergedMikroOptions;
+      this.staleSession = (_a = secondStaleSession != null ? secondStaleSession : firstStaleSession) != null ? _a : "reject";
     }
   }
   async init() {
@@ -105,7 +189,11 @@ const _DatabaseSessionService = class _DatabaseSessionService extends BaseSessio
       return;
     }
     await loadMikroOrm();
-    const options = this.connectionString ? await getConnectionOptionsFromUri(this.connectionString) : { ...this.options, entities: ENTITIES };
+    const options = this.connectionString ? {
+      ...await getConnectionOptionsFromUri(this.connectionString),
+      ...this.options,
+      entities: ENTITIES
+    } : { ...this.options, entities: ENTITIES };
     this.options = options;
     this.orm = await MikroORM.init(options);
     await ensureDatabaseCreated(this.orm);
@@ -120,7 +208,7 @@ const _DatabaseSessionService = class _DatabaseSessionService extends BaseSessio
   }) {
     await this.init();
     const em = this.orm.em.fork();
-    const id = sessionId || randomUUID();
+    const id = sessionId || newId();
     const now = /* @__PURE__ */ new Date();
     const existing = await em.findOne(StorageSession, {
       id,
@@ -183,14 +271,22 @@ const _DatabaseSessionService = class _DatabaseSessionService extends BaseSessio
       userStateModel.state,
       sessionState
     );
-    return createSession({
+    const session = createSession({
       id,
       appName,
       userId,
       state: mergedState,
       events: [],
-      lastUpdateTime: storageSession.createTime.getTime()
+      lastUpdateTime: storageSession.updateTime.getTime()
+    });
+    setStorageRevisionMarker(session, {
+      marker: storageSession.updateTime.toISOString(),
+      recordedLastUpdateTime: session.lastUpdateTime,
+      unverifiedWrite: true,
+      eventsComplete: true,
+      totalEventCount: 0
     });
+    return session;
   }
   async getSession({
     appName,
@@ -231,7 +327,7 @@ const _DatabaseSessionService = class _DatabaseSessionService extends BaseSessio
       (userStateModel == null ? void 0 : userStateModel.state) || {},
       storageSession.state
     );
-    return createSession({
+    const session = createSession({
       id: sessionId,
       appName,
       userId,
@@ -239,6 +335,16 @@ const _DatabaseSessionService = class _DatabaseSessionService extends BaseSessio
       events: storageEvents.map((se) => se.eventData),
       lastUpdateTime: storageSession.updateTime.getTime()
     });
+    const eventsComplete = (config == null ? void 0 : config.numRecentEvents) === void 0 && (config == null ? void 0 : config.afterTimestamp) === void 0;
+    const totalEventCount = eventsComplete ? session.events.length : await em.count(StorageEvent, { appName, userId, sessionId });
+    setStorageRevisionMarker(session, {
+      marker: storageSession.updateTime.toISOString(),
+      recordedLastUpdateTime: session.lastUpdateTime,
+      unverifiedWrite: false,
+      eventsComplete,
+      totalEventCount
+    });
+    return session;
   }
   async listSessions({
     appName,
@@ -251,7 +357,7 @@ const _DatabaseSessionService = class _DatabaseSessionService extends BaseSessio
     await this.init();
     const em = this.orm.em.fork();
     const where = { appName };
-    if (userId) {
+    if (userId !== void 0) {
       where.userId = userId;
     }
     const orderBy = order === "asc" ? { updateTime: "ASC", id: "ASC" } : order === "desc" ? { updateTime: "DESC", id: "ASC" } : void 0;
@@ -300,7 +406,7 @@ const _DatabaseSessionService = class _DatabaseSessionService extends BaseSessio
     const appStateModel = await em.findOne(StorageAppState, { appName });
     const appState = (appStateModel == null ? void 0 : appStateModel.state) || {};
     const userStateMap = {};
-    if (userId) {
+    if (userId !== void 0) {
       const u = await em.findOne(StorageUserState, { appName, userId });
       if (u) userStateMap[userId] = u.state;
     } else {
@@ -312,7 +418,7 @@ const _DatabaseSessionService = class _DatabaseSessionService extends BaseSessio
     const sessions = storageSessions.map((ss) => {
       const uState = userStateMap[ss.userId] || {};
       const merged = mergeStates(appState, uState, ss.state);
-      return createSession({
+      const session = createSession({
         id: ss.id,
         appName: ss.appName,
         userId: ss.userId,
@@ -320,6 +426,13 @@ const _DatabaseSessionService = class _DatabaseSessionService extends BaseSessio
         events: [],
         lastUpdateTime: ss.updateTime.getTime()
       });
+      setStorageRevisionMarker(session, {
+        marker: ss.updateTime.toISOString(),
+        recordedLastUpdateTime: session.lastUpdateTime,
+        unverifiedWrite: false,
+        eventsComplete: false
+      });
+      return session;
     });
     return { sessions, ...paginationMeta };
   }
@@ -337,11 +450,13 @@ const _DatabaseSessionService = class _DatabaseSessionService extends BaseSessio
     session,
     event
   }) {
+    var _a, _b;
     await this.init();
     const em = this.orm.em.fork();
     if (event.partial) {
       return event;
     }
+    const stateDelta = (_b = (_a = event.actions) == null ? void 0 : _a.stateDelta) != null ? _b : {};
     const trimmedEvent = trimTempDeltaState(event);
     let sessionWasStale = false;
     await em.transactional(async (txEm) => {
@@ -357,11 +472,37 @@ const _DatabaseSessionService = class _DatabaseSessionService extends BaseSessio
       if (!storageSession) {
         throw new Error(`Session ${session.id} not found for appendEvent`);
       }
-      if (storageSession.updateTime.getTime() > session.lastUpdateTime) {
+      const storageUpdateTime = storageSession.updateTime.getTime();
+      const storageUpdateMarker = storageSession.updateTime.toISOString();
+      const rev = getStorageRevisionMarker(session);
+      const callerMutatedLastUpdateTime = rev !== void 0 && rev.recordedLastUpdateTime !== session.lastUpdateTime;
+      let isStale = false;
+      if (rev !== void 0 && !callerMutatedLastUpdateTime) {
+        if (rev.marker === storageUpdateMarker) {
+          session.lastUpdateTime = storageUpdateTime;
+        } else if (rev.unverifiedWrite && storageUpdateTime % 1e3 === 0 && Math.abs(storageUpdateTime - rev.recordedLastUpdateTime) < 1e3 && await sessionMatchesStorageRevision(
+          txEm,
+          session,
+          rev.eventsComplete,
+          rev.totalEventCount
+        )) {
+          session.lastUpdateTime = storageUpdateTime;
+        } else {
+          isStale = true;
+        }
+      } else if (rev !== void 0) {
+        isStale = storageUpdateTime > session.lastUpdateTime;
+      } else if (storageUpdateTime > session.lastUpdateTime) {
+        if (await sessionMatchesStorageRevision(txEm, session, false)) {
+          session.lastUpdateTime = storageUpdateTime;
+        } else {
+          isStale = true;
+        }
+      }
+      if (isStale) {
         if (this.staleSession === "reject") {
-          throw new StaleSessionError(
-            `The last_update_time provided in the session object ${formatDateTime(session.lastUpdateTime)} is earlier than the update_time in the storage_session ${formatDateTime(storageSession.updateTime)}. Please check if it is a stale session.`
-          );
+          const message = storageUpdateTime > session.lastUpdateTime ? `The last_update_time provided in the session object ${formatDateTime(session.lastUpdateTime)} is earlier than the update_time in the storage_session ${formatDateTime(storageSession.updateTime)}. Please check if it is a stale session.` : `The session object with last_update_time ${formatDateTime(session.lastUpdateTime)} does not match the storage_session revision with update_time ${formatDateTime(storageSession.updateTime)}. Please check if it is a stale session.`;
+          throw new StaleSessionError(message);
         }
         sessionWasStale = true;
       }
@@ -440,9 +581,32 @@ const _DatabaseSessionService = class _DatabaseSessionService extends BaseSessio
         userStateModel.state,
         storageSession.state
       );
+      for (const source of [session.state, stateDelta]) {
+        for (const [key, value] of Object.entries(source)) {
+          if (key.startsWith(State.TEMP_PREFIX)) {
+            newMergedState[key] = value;
+          }
+        }
+      }
       session.state = newMergedState;
+      const isNewEvent = !existingStorageEvent;
       upsertSessionEvent(session, event);
       session.lastUpdateTime = storageSession.updateTime.getTime();
+      let nextTotalEventCount;
+      if (!callerMutatedLastUpdateTime && !isStale) {
+        if ((rev == null ? void 0 : rev.totalEventCount) !== void 0) {
+          nextTotalEventCount = rev.totalEventCount + (isNewEvent ? 1 : 0);
+        } else if ((rev == null ? void 0 : rev.eventsComplete) === true) {
+          nextTotalEventCount = session.events.length;
+        }
+      }
+      setStorageRevisionMarker(session, {
+        marker: storageSession.updateTime.toISOString(),
+        recordedLastUpdateTime: session.lastUpdateTime,
+        unverifiedWrite: true,
+        eventsComplete: !callerMutatedLastUpdateTime && (rev == null ? void 0 : rev.eventsComplete) === true && !isStale,
+        totalEventCount: nextTotalEventCount
+      });
     });
     if (sessionWasStale) {
       try {
@@ -457,6 +621,14 @@ const _DatabaseSessionService = class _DatabaseSessionService extends BaseSessio
         );
         session.events = storageEvents.map((se) => se.eventData);
         upsertSessionEvent(session, event);
+        const lastRev = getStorageRevisionMarker(session);
+        if (lastRev) {
+          setStorageRevisionMarker(session, {
+            ...lastRev,
+            eventsComplete: true,
+            totalEventCount: session.events.length
+          });
+        }
       } catch (e) {
         const message = e instanceof Error ? e.message : String(e);
         logger.warn(

package/dist/esm/sessions/db/operations.js

@@ -300,8 +300,77 @@ async function getConnectionOptionsFromUri(uri) {
 }
 __name(getConnectionOptionsFromUri, "getConnectionOptionsFromUri");
 async function ensureDatabaseCreated(orm) {
+  var _a;
   await orm.schema.ensureDatabase();
-  await orm.schema.update({ safe: true });
+  const entityMetadata = [...orm.getMetadata().getAll().values()].filter(
+    (meta) => !meta.embeddable && !meta.virtual && !meta.view
+  );
+  if (entityMetadata.length === 0) {
+    return;
+  }
+  const platform = orm.driver.getPlatform();
+  const schemaHelper = platform.getSchemaHelper();
+  if (typeof (schemaHelper == null ? void 0 : schemaHelper.getAllTables) !== "function") {
+    await orm.schema.create();
+    return;
+  }
+  const connection = orm.driver.getConnection();
+  const defaultSchema = platform.getDefaultSchemaName();
+  const configSchema = orm.config.get("schema");
+  const dbName = orm.config.get("dbName");
+  const isCurrentSchema = /* @__PURE__ */ __name((schemaName) => !schemaName || schemaName === defaultSchema || defaultSchema === void 0 && schemaName === dbName, "isCurrentSchema");
+  const tableKey = /* @__PURE__ */ __name((tableName, schemaName) => {
+    const schemaPart = !schemaName || isCurrentSchema(schemaName) ? "" : schemaName;
+    return `${schemaPart}.${tableName}`.toLowerCase();
+  }, "tableKey");
+  const listedTables = await schemaHelper.getAllTables(connection);
+  const listedTableKeys = new Set(
+    listedTables.map((table) => tableKey(table.table_name, table.schema_name))
+  );
+  const seenTableKeys = /* @__PURE__ */ new Set();
+  const existingTableNames = [];
+  let missingCount = 0;
+  for (const meta of entityMetadata) {
+    const schemaName = (_a = meta.schema) != null ? _a : configSchema;
+    const key = tableKey(meta.tableName, schemaName);
+    if (seenTableKeys.has(key)) {
+      continue;
+    }
+    seenTableKeys.add(key);
+    let exists = listedTableKeys.has(key);
+    if (!exists && defaultSchema === void 0 && !isCurrentSchema(schemaName) && typeof schemaHelper.tableExists === "function") {
+      exists = await schemaHelper.tableExists(
+        connection,
+        meta.tableName,
+        schemaName
+      );
+    }
+    if (exists) {
+      existingTableNames.push(
+        schemaName && schemaName !== defaultSchema ? `${schemaName}.${meta.tableName}` : meta.tableName
+      );
+    } else {
+      missingCount++;
+    }
+  }
+  if (missingCount === 0) {
+    return;
+  }
+  if (existingTableNames.length === 0) {
+    await orm.schema.create();
+    return;
+  }
+  const schemaGenConfig = orm.config.get("schemaGenerator");
+  const previousSkipTables = schemaGenConfig.skipTables;
+  schemaGenConfig.skipTables = [
+    ...previousSkipTables != null ? previousSkipTables : [],
+    ...existingTableNames
+  ];
+  try {
+    await orm.schema.create();
+  } finally {
+    schemaGenConfig.skipTables = previousSkipTables;
+  }
 }
 __name(ensureDatabaseCreated, "ensureDatabaseCreated");
 async function validateDatabaseSchemaVersion(orm) {

package/dist/esm/sessions/db/schema.js

@@ -65,6 +65,7 @@ const storageAppStateSchema = new EntitySchema({
     state: { type: "json" },
     updateTime: {
       type: "datetime",
+      length: EVENT_TIMESTAMP_PRECISION,
       fieldName: "update_time",
       onCreate: /* @__PURE__ */ __name(() => /* @__PURE__ */ new Date(), "onCreate"),
       onUpdate: /* @__PURE__ */ __name(() => /* @__PURE__ */ new Date(), "onUpdate")
@@ -88,6 +89,7 @@ const storageUserStateSchema = new EntitySchema({
     state: { type: "json" },
     updateTime: {
       type: "datetime",
+      length: EVENT_TIMESTAMP_PRECISION,
       fieldName: "update_time",
       onCreate: /* @__PURE__ */ __name(() => /* @__PURE__ */ new Date(), "onCreate"),
       onUpdate: /* @__PURE__ */ __name(() => /* @__PURE__ */ new Date(), "onUpdate")
@@ -113,11 +115,13 @@ const storageSessionSchema = new EntitySchema({
     state: { type: "json" },
     createTime: {
       type: "datetime",
+      length: EVENT_TIMESTAMP_PRECISION,
       fieldName: "create_time",
       onCreate: /* @__PURE__ */ __name(() => /* @__PURE__ */ new Date(), "onCreate")
     },
     updateTime: {
       type: "datetime",
+      length: EVENT_TIMESTAMP_PRECISION,
       fieldName: "update_time",
       onCreate: /* @__PURE__ */ __name(() => /* @__PURE__ */ new Date(), "onCreate")
     }

package/dist/esm/sessions/in_memory_session_service.js

@@ -8,7 +8,7 @@ var __name = (target, value) => __defProp(target, "name", { value, configurable:
  * SPDX-License-Identifier: Apache-2.0
  */
 import { cloneDeep } from "lodash-es";
-import { randomUUID } from "../utils/env_aware_utils.js";
+import { newId } from "../utils/id_provider.js";
 import { logger } from "../utils/logger.js";
 import {
   BaseSessionService,
@@ -49,7 +49,7 @@ const _InMemorySessionService = class _InMemorySessionService extends BaseSessio
     const session = createSession({
       // Surrounding whitespace is dropped so that a later lookup by the bare
       // id finds the session, and a blank id gets a generated one.
-      id: (sessionId == null ? void 0 : sessionId.trim()) || randomUUID(),
+      id: (sessionId == null ? void 0 : sessionId.trim()) || newId(),
       appName,
       userId,
       state: filteredState,

package/dist/esm/sessions/vertex_ai_session_service.js

@@ -19,6 +19,7 @@ var __decorateClass = (decorators, target, key, kind) => {
 import { Client } from "@google-cloud/vertexai";
 import { isCompactedEvent } from "../events/compacted_event.js";
 import { experimental } from "../utils/experimental.js";
+import { formatError } from "../utils/error_utils.js";
 import { logger } from "../utils/logger.js";
 import {
   EXPRESS_MODE_UNSUPPORTED_MESSAGE,
@@ -314,9 +315,16 @@ let VertexAiSessionService = class extends BaseSessionService {
     if (!session) {
       return;
     }
-    await this.sessions.delete({
-      name: `reasoningEngines/${reasoningEngineId}/sessions/${sessionId}`
-    });
+    try {
+      await this.sessions.delete({
+        name: `reasoningEngines/${reasoningEngineId}/sessions/${sessionId}`
+      });
+    } catch (error) {
+      logger.error(
+        `Error deleting session ${sessionId}: ${formatError(error)}`
+      );
+      throw error;
+    }
   }
   async appendEvent({
     session,

package/dist/esm/skills/loader.js

@@ -67,7 +67,7 @@ async function loadDir(directoryPath) {
         }
         await walk(fullPath);
       } else if (entry.isFile()) {
-        const relativePath = path.relative(directoryPath, fullPath);
+        const relativePath = path.relative(directoryPath, fullPath).split(path.sep).join("/");
         if (IGNORED_EXTENSIONS.has(path.extname(entry.name))) {
           continue;
         }
@@ -95,7 +95,7 @@ const FRONTMATTER_PATTERN = /^---[ \t]*\r?\n(?:([\s\S]*?)\r?\n)??---[ \t]*(?:\r?
 function parseFrontmatterYaml(content) {
   var _a;
   const text = content.startsWith(FRONTMATTER_BOM) ? content.slice(FRONTMATTER_BOM.length) : content;
-  if (!text.startsWith("---")) {
+  if (!/^---[ \t]*(?:\r?\n|$)/.test(text)) {
     throw new InputValidationError(
       "SKILL.md must start with YAML frontmatter (---)"
     );
@@ -108,20 +108,27 @@ function parseFrontmatterYaml(content) {
   }
   const frontmatterStr = (_a = match[1]) != null ? _a : "";
   const body = text.slice(match[0].length).trim();
-  try {
-    const parsed = yaml.load(frontmatterStr);
-    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+  const hasYamlContent = frontmatterStr.split(/\r?\n/).some((line) => {
+    const trimmed = line.trim();
+    return trimmed.length > 0 && !trimmed.startsWith("#");
+  });
+  let parsed = null;
+  if (hasYamlContent) {
+    try {
+      parsed = yaml.load(frontmatterStr);
+    } catch (e) {
       throw new InputValidationError(
-        "SKILL.md frontmatter must be a YAML mapping"
+        `Invalid YAML in frontmatter: ${e.message}`,
+        { cause: e }
       );
     }
-    return { raw: parsed, body };
-  } catch (e) {
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
     throw new InputValidationError(
-      `Invalid YAML in frontmatter: ${e.message}`,
-      { cause: e }
+      "Invalid YAML in frontmatter: SKILL.md frontmatter must be a YAML mapping"
     );
   }
+  return { raw: parsed, body };
 }
 __name(parseFrontmatterYaml, "parseFrontmatterYaml");
 function validateFrontmatter(raw) {
@@ -196,22 +203,16 @@ async function validateSkillDir(skillDir) {
   } catch (e) {
     return [e.message];
   }
-  try {
-    const keys = Object.keys(skill.frontmatter);
-    const unknown = keys.filter((k) => !ALLOWED_FRONTMATTER_KEYS.has(k));
-    if (unknown.length > 0) {
-      problems.push(
-        `Unknown frontmatter fields: [${unknown.sort().join(", ")}]`
-      );
-    }
-    const dirName = path.basename(resolvedDir);
-    if (dirName !== skill.frontmatter.name) {
-      problems.push(
-        `Skill name '${skill.frontmatter.name}' does not match directory name '${dirName}'.`
-      );
-    }
-  } catch (e) {
-    problems.push(e.message);
+  const keys = Object.keys(skill.frontmatter);
+  const unknown = keys.filter((k) => !ALLOWED_FRONTMATTER_KEYS.has(k));
+  if (unknown.length > 0) {
+    problems.push(`Unknown frontmatter fields: [${unknown.sort().join(", ")}]`);
+  }
+  const dirName = path.basename(resolvedDir);
+  if (dirName !== skill.frontmatter.name) {
+    problems.push(
+      `Skill name '${skill.frontmatter.name}' does not match directory name '${dirName}'.`
+    );
   }
   return problems;
 }
@@ -314,7 +315,7 @@ function loadSkillFromZipBuffer(zipBuffer) {
       );
     }
   }
-  let skillMdContent = "";
+  let skillMdContent;
   for (const entry of entries) {
     if (entry.isDirectory) continue;
     if (entry.entryName.toLowerCase() === "skill.md") {
@@ -322,7 +323,7 @@ function loadSkillFromZipBuffer(zipBuffer) {
       break;
     }
   }
-  if (!skillMdContent) {
+  if (skillMdContent === void 0) {
     throw new NotFoundError("SKILL.md not found in zipped filesystem.");
   }
   const { raw, body } = parseFrontmatterYaml(skillMdContent);