mindoodb-app-sdk 0.0.70 → 0.0.72

package/dist/{chunk-P7SOHCEQ.js → chunk-UFP7O4OJ.js}

@@ -66,6 +66,296 @@ function assertValidMindooDBCreateIds(input, methodName = "createDocument") {
   }
 }
 
+// src/inspection.ts
+var MINDOODB_INSPECT_DOCUMENT = "mindoo.inspect.document@1";
+var MINDOODB_INSPECT_SPREADSHEET = "mindoo.inspect.spreadsheet@1";
+var MINDOODB_INSPECT_SLIDES = "mindoo.inspect.slides@1";
+var MINDOODB_APP_INSPECTION_FIELD = "inspection";
+var MINDOODB_APP_INSPECTION_SUMMARY_MAX_BYTES = 8 * 1024;
+var MINDOODB_APP_INSPECTION_MAX_BYTES = 256 * 1024;
+var MINDOODB_APP_ISSUES_MAX = 100;
+var MindooDBAppEmbedValidationError = class extends Error {
+  constructor(issues) {
+    const first = issues.find((issue) => issue.severity === "error") ?? issues[0];
+    super(first ? first.message : "The document was not saved.");
+    this.issues = issues;
+    this.name = "MindooDBAppEmbedValidationError";
+  }
+  issues;
+};
+var SUPPORTS_CAPABILITY = /^[a-z][a-z0-9-]{0,31}$/;
+function mindooDBAppComponentSupports(supports, requirement) {
+  const wanted = requirement.trim();
+  return (supports ?? []).some((entry) => entry === wanted || !wanted.includes(":") && entry.startsWith(`${wanted}:`));
+}
+function mindooDBAppInspectContracts(supports) {
+  return (supports ?? []).filter((entry) => entry.startsWith("inspect:")).map((entry) => entry.slice("inspect:".length));
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeMindooDBAppInspectAnchor(raw) {
+  if (!isPlainObject(raw)) {
+    return void 0;
+  }
+  if (raw.kind === "heading" && typeof raw.id === "string" && raw.id && raw.id.length <= 200) {
+    return { kind: "heading", id: raw.id };
+  }
+  if (raw.kind === "cell" && typeof raw.ref === "string" && raw.ref && raw.ref.length <= 200) {
+    return { kind: "cell", ref: raw.ref };
+  }
+  if (raw.kind === "slide" && Number.isInteger(raw.index) && raw.index >= 0) {
+    return { kind: "slide", index: raw.index };
+  }
+  return void 0;
+}
+function normalizeMindooDBAppIssues(raw) {
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  const issues = [];
+  for (const entry of raw) {
+    if (issues.length >= MINDOODB_APP_ISSUES_MAX) {
+      break;
+    }
+    if (!isPlainObject(entry) || typeof entry.message !== "string" || !entry.message.trim()) {
+      continue;
+    }
+    const severity = entry.severity === "warning" || entry.severity === "info" ? entry.severity : entry.severity === "error" ? "error" : null;
+    if (!severity) {
+      continue;
+    }
+    const anchor = normalizeMindooDBAppInspectAnchor(entry.anchor);
+    const code = typeof entry.code === "string" && entry.code.trim() ? entry.code.trim().slice(0, 64) : void 0;
+    issues.push({
+      severity,
+      message: entry.message.trim().slice(0, 500),
+      ...anchor ? { anchor } : {},
+      ...code ? { code } : {}
+    });
+  }
+  return issues;
+}
+function normalizeMindooDBAppInspectRequest(raw) {
+  const input = isPlainObject(raw) ? raw : {};
+  const strings = (value, max) => Array.isArray(value) ? [...new Set(value.filter((entry) => typeof entry === "string" && !!entry && entry.length <= 200))].slice(0, max) : [];
+  const include = strings(input.include, 16);
+  const cells = strings(input.cells, 200);
+  const maxTextLength = Number(input.maxTextLength);
+  return {
+    ...typeof input.contract === "string" && input.contract ? { contract: input.contract.slice(0, 200) } : {},
+    ...include.length ? { include } : {},
+    ...cells.length ? { cells } : {},
+    ...Number.isFinite(maxTextLength) && maxTextLength > 0 ? { maxTextLength: Math.min(Math.floor(maxTextLength), 5e4) } : {}
+  };
+}
+function normalizeMindooDBAppInspection(raw) {
+  let json;
+  try {
+    json = JSON.stringify(raw);
+  } catch {
+    throw new Error("An inspection must be plain JSON.");
+  }
+  if (!json || json.length > MINDOODB_APP_INSPECTION_MAX_BYTES) {
+    throw new Error(`An inspection must not be larger than ${MINDOODB_APP_INSPECTION_MAX_BYTES / 1024} KiB.`);
+  }
+  const value = JSON.parse(json);
+  if (!isPlainObject(value) || typeof value.contract !== "string" || !value.contract) {
+    throw new Error("An inspection must be an object with a contract.");
+  }
+  return value;
+}
+var SUMMARY_TEXT_STEPS = [500, 200, 0];
+var SUMMARY_LIST_STEPS = [50, 20, 5, 0];
+function shorten(value, textMax, listMax, marks) {
+  if (typeof value === "string") {
+    if (value.length <= textMax) return value;
+    marks.truncated = true;
+    return value.slice(0, textMax);
+  }
+  if (Array.isArray(value)) {
+    if (value.length > listMax) marks.truncated = true;
+    return value.slice(0, listMax).map((entry) => shorten(entry, Math.min(textMax || 80, 80), listMax, marks));
+  }
+  if (isPlainObject(value)) {
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, shorten(entry, textMax, listMax, marks)]));
+  }
+  return value;
+}
+function summarizeMindooDBAppInspection(inspection, maxBytes = MINDOODB_APP_INSPECTION_SUMMARY_MAX_BYTES) {
+  const { cells: _cells, ...rest } = inspection;
+  const base = JSON.parse(JSON.stringify(rest));
+  for (const textMax of SUMMARY_TEXT_STEPS) {
+    for (const listMax of SUMMARY_LIST_STEPS) {
+      const marks = { truncated: false };
+      const next = shorten(base, textMax, listMax, marks);
+      if (textMax === 0 && typeof next.text === "string") delete next.text;
+      next.contract = inspection.contract;
+      if (typeof inspection.subject === "string") next.subject = inspection.subject.slice(0, 200);
+      if (marks.truncated || inspection.truncated) next.truncated = true;
+      if (JSON.stringify(next).length <= maxBytes) {
+        return next;
+      }
+    }
+  }
+  return { contract: inspection.contract, truncated: true };
+}
+function mindooDBAppInspectionSummaryValue(inspection) {
+  return MindooDBAppValue.atomic(JSON.stringify(summarizeMindooDBAppInspection(inspection)));
+}
+function readMindooDBAppInspectionSummary(root) {
+  let value = root?.[MINDOODB_APP_INSPECTION_FIELD];
+  if (typeof value === "string") {
+    try {
+      value = JSON.parse(value);
+    } catch {
+      return null;
+    }
+  }
+  return isPlainObject(value) && typeof value.contract === "string" ? value : null;
+}
+function outcomeIssues(rule, outcome) {
+  if (!outcome) return [];
+  if (typeof outcome === "string") {
+    return [{ severity: rule.severity ?? "error", message: outcome, code: rule.code }];
+  }
+  return (Array.isArray(outcome) ? outcome : [outcome]).map((issue) => ({ code: rule.code, ...issue }));
+}
+function defineDocumentRules(definition) {
+  const request = normalizeMindooDBAppInspectRequest(definition);
+  function check(inspection) {
+    if (!inspection || definition.contract && inspection.contract !== definition.contract) {
+      return [];
+    }
+    const issues = definition.rules.flatMap((rule) => {
+      try {
+        return outcomeIssues(rule, rule.check(inspection));
+      } catch (error) {
+        return [
+          {
+            severity: "warning",
+            code: rule.code,
+            message: `Check "${rule.code}" failed: ${error instanceof Error ? error.message : String(error)}`
+          }
+        ];
+      }
+    });
+    return normalizeMindooDBAppIssues(issues);
+  }
+  const rules = {
+    request,
+    check,
+    checkRoot: (root) => check(readMindooDBAppInspectionSummary(root)),
+    beforeSave: ({ inspection }) => ({ issues: check(inspection) }),
+    attach: (embed) => embed.onBeforeSave(rules.beforeSave, { inspect: request })
+  };
+  return rules;
+}
+function plural(count, one, many) {
+  return `${count} ${count === 1 ? one : many}`;
+}
+var mindooDBAppInspectRules = {
+  /** Documents: no placeholder or MERGEFIELD left open. */
+  noOpenPlaceholders(severity = "error", message) {
+    return {
+      code: "open-placeholders",
+      severity,
+      check: (inspection) => {
+        const names = (inspection.placeholders ?? []).map((entry) => entry.name);
+        if (!names.length) return null;
+        return message?.(names) ?? `${plural(names.length, "placeholder is", "placeholders are")} not filled in: ${names.slice(0, 5).join(", ")}${names.length > 5 ? ", \u2026" : ""}`;
+      }
+    };
+  },
+  /** Documents: every comment resolved. */
+  noOpenComments(severity = "warning", message) {
+    return {
+      code: "open-comments",
+      severity,
+      check: (inspection) => inspection.openComments > 0 ? message?.(inspection.openComments) ?? `${plural(inspection.openComments, "comment is", "comments are")} not resolved.` : null
+    };
+  },
+  /** Documents: every tracked change accepted or rejected. */
+  noOpenTrackedChanges(severity = "warning", message) {
+    return {
+      code: "open-tracked-changes",
+      severity,
+      check: (inspection) => inspection.openTrackedChanges > 0 ? message?.(inspection.openTrackedChanges) ?? `${plural(inspection.openTrackedChanges, "tracked change is", "tracked changes are")} not accepted or rejected.` : null
+    };
+  },
+  /** Spreadsheets: no formula evaluates to an error; one issue per cell. */
+  noFormulaErrors(severity = "error") {
+    return {
+      code: "formula-errors",
+      severity,
+      check: (inspection) => (inspection.formulaErrors ?? []).map((entry) => ({
+        severity,
+        message: `${entry.ref}: ${entry.error}`,
+        anchor: { kind: "cell", ref: entry.ref }
+      }))
+    };
+  },
+  /** Presentations: no layout placeholder left empty; one issue per slide. */
+  noEmptySlidePlaceholders(severity = "warning") {
+    return {
+      code: "empty-placeholders",
+      severity,
+      check: (inspection) => {
+        const bySlide = /* @__PURE__ */ new Map();
+        for (const entry of inspection.emptyPlaceholders ?? []) {
+          bySlide.set(entry.slide, [...bySlide.get(entry.slide) ?? [], entry.placeholder]);
+        }
+        return [...bySlide.entries()].map(([slide, names]) => ({
+          severity,
+          message: `Slide ${slide + 1}: empty ${names.join(", ")}`,
+          anchor: { kind: "slide", index: slide }
+        }));
+      }
+    };
+  }
+};
+function isMindooDBAppSupportsEntry(entry, contractPattern) {
+  const [capability, contract, ...rest] = entry.split(":");
+  if (rest.length || !capability || !SUPPORTS_CAPABILITY.test(capability)) {
+    return false;
+  }
+  return contract === void 0 || contractPattern.test(contract);
+}
+async function performMindooDBAppEmbeddingSave(steps) {
+  const validation = await steps.validate();
+  if (!validation.ok) {
+    if (validation.issues.length && steps.showIssues) {
+      try {
+        await steps.showIssues(validation.issues);
+      } catch (error) {
+        console.warn("[mindoodb-app-sdk] Showing issues failed.", error);
+      }
+    }
+    throw new MindooDBAppEmbedValidationError(validation.issues);
+  }
+  let inspection = null;
+  if (steps.provider) {
+    try {
+      inspection = mindooDBAppInspectionSummaryValue(normalizeMindooDBAppInspection(await steps.provider({})));
+    } catch (error) {
+      console.warn("[mindoodb-app-sdk] Could not summarize the document.", error);
+    }
+  }
+  await steps.flush({ inspection, issues: validation.issues });
+  await steps.saved();
+  return validation;
+}
+async function resolveMindooDBAppEmbedValidation(issues, interactive, confirm) {
+  if (issues.some((issue) => issue.severity === "error")) {
+    return { ok: false, issues };
+  }
+  const warnings = issues.filter((issue) => issue.severity === "warning");
+  if (!warnings.length || !interactive) {
+    return { ok: true, issues };
+  }
+  return { ok: await confirm(warnings) === true, issues };
+}
+
 // src/appDefinition.ts
 var MINDOODB_APP_DEFINITION_FORMAT = "mindoodb.haven.app";
 var MINDOODB_APP_DEFINITION_VERSION = 1;
@@ -86,8 +376,17 @@ var MINDOODB_APP_DEFINITION_REGISTRATION_PERMISSIONS = ["proposeapps"];
 var MINDOODB_APP_LISTING_SUMMARY_MAX = 300;
 var MINDOODB_APP_LISTING_DESCRIPTION_MAX = 4e3;
 var MINDOODB_APP_LISTING_MAX_SCREENSHOTS = 8;
+var MINDOODB_APP_AGENT_SUMMARY_MAX = 400;
+var MINDOODB_APP_AGENT_CAPABILITIES_MAX = 8;
+var MINDOODB_APP_AGENT_CAPABILITY_TITLE_MAX = 80;
+var MINDOODB_APP_AGENT_CAPABILITY_TOOLS_MAX = 64;
+var MINDOODB_APP_AGENT_LIST_MAX = 8;
+var MINDOODB_APP_AGENT_EXAMPLE_MAX = 200;
+var MINDOODB_APP_AGENT_LIMIT_MAX = 300;
+var MINDOODB_APP_AGENT_GUIDE_MAX_BYTES = 8 * 1024;
+var MINDOODB_APP_AGENT_TOOL_NAME_PATTERN = /^[a-z][a-z0-9_]{0,47}$/;
 var LOGICAL_DATABASE_ID_PATTERN = /^[a-z0-9][a-z0-9._-]*$/i;
-function isPlainObject(value) {
+function isPlainObject2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function readOptionalString(raw, key, errors) {
@@ -118,7 +417,7 @@ function readStringRecord(raw, key, errors) {
   if (value === void 0 || value === null) {
     return void 0;
   }
-  if (!isPlainObject(value)) {
+  if (!isPlainObject2(value)) {
     errors.push(`App definition ${key} must be an object of string values.`);
     return void 0;
   }
@@ -184,7 +483,7 @@ function readDatabases(value, errors) {
   const result = [];
   const seen = /* @__PURE__ */ new Set();
   value.forEach((entry, index) => {
-    if (!isPlainObject(entry)) {
+    if (!isPlainObject2(entry)) {
       errors.push(`App definition database #${index} must be an object.`);
       return;
     }
@@ -237,7 +536,7 @@ function readLocalizedText(value, label, maxLength, errors) {
     }
     return trimmed || void 0;
   }
-  if (!isPlainObject(value)) {
+  if (!isPlainObject2(value)) {
     errors.push(`${label} must be a string or an object of per-locale strings.`);
     return void 0;
   }
@@ -284,7 +583,7 @@ function readAccepts(value, errors) {
   const ids = /* @__PURE__ */ new Set();
   value.forEach((entry, index) => {
     const label = `App definition accepts[${index}]`;
-    if (!isPlainObject(entry)) {
+    if (!isPlainObject2(entry)) {
       errors.push(`${label} must be an object.`);
       return;
     }
@@ -345,7 +644,7 @@ var COMPONENT_FIELD_PATTERN = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
 var COMPONENT_INTENTS = ["create", "edit", "view"];
 var COMPONENT_CREATE_MAX_BYTES = 16 * 1024;
 function readComponentFieldMatch(value, label, errors) {
-  if (!isPlainObject(value)) {
+  if (!isPlainObject2(value)) {
     errors.push(`${label} must be an object of field values.`);
     return void 0;
   }
@@ -368,6 +667,28 @@ var MINDOODB_APP_COMPONENT_CONTRACT_PATTERN = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]
 var COMPONENT_CONTRACTS_MAX = 8;
 var COMPONENT_REFERENCES_MAX = 8;
 var COMPONENT_REFERENCE_SHOW_MAX = 8;
+var COMPONENT_SUPPORTS_MAX = 16;
+function readComponentSupports(value, label, errors) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (!Array.isArray(value) || value.length > COMPONENT_SUPPORTS_MAX) {
+    errors.push(`${label} must be an array of at most ${COMPONENT_SUPPORTS_MAX} entries.`);
+    return void 0;
+  }
+  const result = [];
+  for (const entry of value) {
+    const text = typeof entry === "string" ? entry.trim() : "";
+    if (!isMindooDBAppSupportsEntry(text, MINDOODB_APP_COMPONENT_CONTRACT_PATTERN)) {
+      errors.push(`${label} entries must look like "validate" or "inspect:mindoo.inspect.document@1", received ${JSON.stringify(entry)}.`);
+      return void 0;
+    }
+    if (!result.includes(text)) {
+      result.push(text);
+    }
+  }
+  return result.length ? result : void 0;
+}
 function readComponentContracts(value, label, errors) {
   if (value === void 0) {
     return void 0;
@@ -378,14 +699,14 @@ function readComponentContracts(value, label, errors) {
   }
   const result = [];
   for (const [index, entry] of value.entries()) {
-    const contract = isPlainObject(entry) && typeof entry.contract === "string" ? entry.contract.trim() : "";
+    const contract = isPlainObject2(entry) && typeof entry.contract === "string" ? entry.contract.trim() : "";
     if (!MINDOODB_APP_COMPONENT_CONTRACT_PATTERN.test(contract)) {
       errors.push(`${label}[${index}].contract must look like "mindoo.contacts.company@1".`);
       return void 0;
     }
     let fields;
-    if (isPlainObject(entry) && entry.fields !== void 0) {
-      if (!isPlainObject(entry.fields)) {
+    if (isPlainObject2(entry) && entry.fields !== void 0) {
+      if (!isPlainObject2(entry.fields)) {
         errors.push(`${label}[${index}].fields must map contract fields to document fields.`);
         return void 0;
       }
@@ -414,7 +735,7 @@ function readComponentReferences(value, label, rootMatch, errors) {
   const fieldsSeen = /* @__PURE__ */ new Set();
   for (const [index, entry] of value.entries()) {
     const at = `${label}[${index}]`;
-    if (!isPlainObject(entry)) {
+    if (!isPlainObject2(entry)) {
       errors.push(`${at} must be an object.`);
       return void 0;
     }
@@ -463,7 +784,7 @@ function readComponents(value, errors) {
   value.forEach((entry, index) => {
     const label = `App definition components[${index}]`;
     const errorCount = errors.length;
-    if (!isPlainObject(entry)) {
+    if (!isPlainObject2(entry)) {
       errors.push(`${label} must be an object.`);
       return;
     }
@@ -510,7 +831,7 @@ function readComponents(value, errors) {
     }
     let create;
     if (entry.create !== void 0) {
-      if (!isPlainObject(entry.create)) {
+      if (!isPlainObject2(entry.create)) {
         errors.push(`${label}.create must be an object of initial field values.`);
         return;
       }
@@ -539,7 +860,7 @@ function readComponents(value, errors) {
     }
     let children;
     if (entry.children !== void 0) {
-      if (!isPlainObject(entry.children)) {
+      if (!isPlainObject2(entry.children)) {
         errors.push(`${label}.children must be an object.`);
         return;
       }
@@ -568,6 +889,7 @@ function readComponents(value, errors) {
     }
     const provides = readComponentContracts(entry.provides, `${label}.provides`, errors);
     const references = readComponentReferences(entry.references, `${label}.references`, match, errors);
+    const supports = readComponentSupports(entry.supports, `${label}.supports`, errors);
     if (errors.length !== errorCount) {
       return;
     }
@@ -582,7 +904,8 @@ function readComponents(value, errors) {
       ...children ? { children } : {},
       ...category ? { category } : {},
       ...provides ? { provides } : {},
-      ...references ? { references } : {}
+      ...references ? { references } : {},
+      ...supports ? { supports } : {}
     });
   });
   return result.length ? result : void 0;
@@ -622,7 +945,7 @@ function readListing(value, errors) {
   if (value === void 0 || value === null) {
     return void 0;
   }
-  if (!isPlainObject(value)) {
+  if (!isPlainObject2(value)) {
     errors.push("App definition listing must be an object.");
     return void 0;
   }
@@ -662,7 +985,7 @@ function readListing(value, errors) {
       value.screenshots.forEach((entry, index) => {
         const label = `App definition listing.screenshots[${index}]`;
         const raw = typeof entry === "string" ? { file: entry } : entry;
-        if (!isPlainObject(raw)) {
+        if (!isPlainObject2(raw)) {
           errors.push(`${label} must be a path or an object with a file.`);
           return;
         }
@@ -677,7 +1000,7 @@ function readListing(value, errors) {
     }
   }
   if (value.publisher !== void 0 && value.publisher !== null) {
-    const publisher = isPlainObject(value.publisher) ? value.publisher : {};
+    const publisher = isPlainObject2(value.publisher) ? value.publisher : {};
     const name = typeof publisher.name === "string" ? publisher.name.trim() : "";
     if (!name) {
       errors.push("App definition listing.publisher must be an object with a non-empty name.");
@@ -692,6 +1015,163 @@ function readListing(value, errors) {
   }
   return Object.keys(listing).length ? listing : void 0;
 }
+var AGENT_CAPABILITY_ID_PATTERN = /^[a-z0-9][a-z0-9_-]{0,47}$/;
+var AGENT_LOCALE_PATTERN = /^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/;
+var AGENT_GUIDE_PATH_PATTERN = /^[A-Za-z0-9_][A-Za-z0-9_.\/-]{0,199}\.md$/;
+function readAgentLocaleText(value, label, maxLength, errors) {
+  if (!isPlainObject2(value)) {
+    errors.push(`${label} must be an object of per-locale strings with an "en" entry.`);
+    return void 0;
+  }
+  const result = {};
+  for (const [locale, text] of Object.entries(value)) {
+    if (!AGENT_LOCALE_PATTERN.test(locale)) {
+      errors.push(`${label} has an invalid locale ${JSON.stringify(locale)}.`);
+      return void 0;
+    }
+    const trimmed = typeof text === "string" ? text.trim() : "";
+    if (!trimmed) {
+      errors.push(`${label}.${locale} must be a non-empty string.`);
+      return void 0;
+    }
+    if (trimmed.length > maxLength) {
+      errors.push(`${label}.${locale} must not be longer than ${maxLength} characters.`);
+      return void 0;
+    }
+    result[locale] = trimmed;
+  }
+  if (!result.en) {
+    errors.push(`${label} must include an "en" entry as the fallback for other locales.`);
+    return void 0;
+  }
+  return result;
+}
+function readAgentLocaleList(value, label, maxLength, errors) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (!isPlainObject2(value)) {
+    errors.push(`${label} must be an object of per-locale string arrays with an "en" entry.`);
+    return void 0;
+  }
+  const result = {};
+  for (const [locale, entries] of Object.entries(value)) {
+    if (!AGENT_LOCALE_PATTERN.test(locale)) {
+      errors.push(`${label} has an invalid locale ${JSON.stringify(locale)}.`);
+      return void 0;
+    }
+    if (!Array.isArray(entries) || !entries.length || entries.length > MINDOODB_APP_AGENT_LIST_MAX) {
+      errors.push(`${label}.${locale} must be an array of 1-${MINDOODB_APP_AGENT_LIST_MAX} strings.`);
+      return void 0;
+    }
+    const list = [];
+    for (const entry of entries) {
+      const trimmed = typeof entry === "string" ? entry.trim() : "";
+      if (!trimmed || trimmed.length > maxLength) {
+        errors.push(`${label}.${locale} must only hold non-empty strings of at most ${maxLength} characters.`);
+        return void 0;
+      }
+      list.push(trimmed);
+    }
+    result[locale] = list;
+  }
+  if (!result.en) {
+    errors.push(`${label} must include an "en" entry as the fallback for other locales.`);
+    return void 0;
+  }
+  return result;
+}
+function readAgentCapabilities(value, errors) {
+  const label = "App definition agent.capabilities";
+  if (!Array.isArray(value) || !value.length || value.length > MINDOODB_APP_AGENT_CAPABILITIES_MAX) {
+    errors.push(`${label} must be an array of 1-${MINDOODB_APP_AGENT_CAPABILITIES_MAX} capabilities.`);
+    return void 0;
+  }
+  const result = [];
+  const ids = /* @__PURE__ */ new Set();
+  for (const [index, entry] of value.entries()) {
+    const at = `${label}[${index}]`;
+    if (!isPlainObject2(entry)) {
+      errors.push(`${at} must be an object.`);
+      return void 0;
+    }
+    const id = typeof entry.id === "string" ? entry.id.trim() : "";
+    if (!AGENT_CAPABILITY_ID_PATTERN.test(id)) {
+      errors.push(`${at}.id must be 1-48 lowercase letters, digits, "-" or "_", received ${JSON.stringify(entry.id)}.`);
+      return void 0;
+    }
+    if (ids.has(id)) {
+      errors.push(`${at}.id "${id}" is used twice.`);
+      return void 0;
+    }
+    ids.add(id);
+    const title = readAgentLocaleText(entry.title, `${at}.title`, MINDOODB_APP_AGENT_CAPABILITY_TITLE_MAX, errors);
+    if (!title) {
+      return void 0;
+    }
+    if (!Array.isArray(entry.tools) || !entry.tools.length || entry.tools.length > MINDOODB_APP_AGENT_CAPABILITY_TOOLS_MAX) {
+      errors.push(`${at}.tools must be an array of 1-${MINDOODB_APP_AGENT_CAPABILITY_TOOLS_MAX} tool names.`);
+      return void 0;
+    }
+    const tools = [];
+    for (const tool of entry.tools) {
+      const name = typeof tool === "string" ? tool.trim() : "";
+      if (!MINDOODB_APP_AGENT_TOOL_NAME_PATTERN.test(name) || /^haven(?:_|$)/.test(name)) {
+        errors.push(
+          `${at}.tools contains ${JSON.stringify(tool)}; name the app's own tools as registered, without prefix and never "haven_*".`
+        );
+        return void 0;
+      }
+      if (!tools.includes(name)) {
+        tools.push(name);
+      }
+    }
+    result.push({ id, title, tools });
+  }
+  return result;
+}
+function readAgentProfile(value, errors) {
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  if (!isPlainObject2(value)) {
+    errors.push("App definition agent must be an object.");
+    return void 0;
+  }
+  const errorCount = errors.length;
+  const summary = readAgentLocaleText(value.summary, "App definition agent.summary", MINDOODB_APP_AGENT_SUMMARY_MAX, errors);
+  const capabilities = readAgentCapabilities(value.capabilities, errors);
+  const examples = readAgentLocaleList(value.examples, "App definition agent.examples", MINDOODB_APP_AGENT_EXAMPLE_MAX, errors);
+  const limits = readAgentLocaleList(value.limits, "App definition agent.limits", MINDOODB_APP_AGENT_LIMIT_MAX, errors);
+  let guide;
+  if (value.guide !== void 0) {
+    guide = readAgentLocaleText(value.guide, "App definition agent.guide", 200, errors);
+    for (const [locale, path] of Object.entries(guide ?? {})) {
+      if (!AGENT_GUIDE_PATH_PATTERN.test(path) || path.split("/").some((part) => part === "." || part === "..")) {
+        errors.push(
+          `App definition agent.guide.${locale} must be a relative path to a .md file next to the manifest, e.g. "agent/agent.${locale}.md".`
+        );
+        guide = void 0;
+        break;
+      }
+    }
+  }
+  if (errors.length !== errorCount || !summary || !capabilities) {
+    return void 0;
+  }
+  return {
+    summary,
+    capabilities,
+    ...examples ? { examples } : {},
+    ...limits ? { limits } : {},
+    ...guide ? { guide } : {}
+  };
+}
+function validateMindooDBAppAgentProfile(value) {
+  const errors = [];
+  const agent = readAgentProfile(value, errors);
+  return { agent: errors.length ? void 0 : agent, errors };
+}
 function resolveMindooDBAppLocalizedText(text, locale) {
   if (text === void 0) {
     return "";
@@ -717,7 +1197,7 @@ function resolveMindooDBAppListingAssetUrl(path, originUrl) {
 }
 function validateMindooDBAppDefinition(raw) {
   const errors = [];
-  if (!isPlainObject(raw)) {
+  if (!isPlainObject2(raw)) {
     return { definition: null, errors: ["App definition must be a JSON object."] };
   }
   if (raw.format !== MINDOODB_APP_DEFINITION_FORMAT) {
@@ -772,6 +1252,7 @@ function validateMindooDBAppDefinition(raw) {
   const listing = readListing(raw.listing, errors);
   const accepts = readAccepts(raw.accepts, errors);
   const components = readComponents(raw.components, errors);
+  const agent = readAgentProfile(raw.agent, errors);
   const agentToolPrefix = readOptionalString(raw, "agentToolPrefix", errors);
   if (agentToolPrefix !== void 0 && (!/^[a-z][a-z0-9_]{0,15}$/.test(agentToolPrefix) || agentToolPrefix.endsWith("_") || /^haven(?:_|$)/.test(agentToolPrefix))) {
     errors.push(
@@ -813,7 +1294,8 @@ function validateMindooDBAppDefinition(raw) {
       databases,
       accepts,
       components,
-      listing
+      listing,
+      agent
     },
     errors: []
   };
@@ -1229,29 +1711,29 @@ function bindDragSource(element, options, start, follow) {
 }
 
 // src/client/agentInput.ts
-function isPlainObject2(value) {
+function isPlainObject3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isPlaceholder(value) {
   if (value === null || value === void 0) return true;
   if (typeof value === "string") return value.trim() === "";
   if (Array.isArray(value)) return value.length === 0;
-  if (isPlainObject2(value)) return Object.keys(value).length === 0;
+  if (isPlainObject3(value)) return Object.keys(value).length === 0;
   return false;
 }
 function normalizeValue(value, schema) {
-  if (!isPlainObject2(schema)) return value;
+  if (!isPlainObject3(schema)) return value;
   if (Array.isArray(value)) {
     const items = schema.items;
-    return isPlainObject2(items) ? value.map((item) => normalizeValue(item, items)) : value;
+    return isPlainObject3(items) ? value.map((item) => normalizeValue(item, items)) : value;
   }
-  if (isPlainObject2(value) && isPlainObject2(schema.properties)) {
+  if (isPlainObject3(value) && isPlainObject3(schema.properties)) {
     return normalizeObject(value, schema);
   }
   return value;
 }
 function normalizeObject(input, schema) {
-  const properties = isPlainObject2(schema.properties) ? schema.properties : {};
+  const properties = isPlainObject3(schema.properties) ? schema.properties : {};
   const required = new Set(Array.isArray(schema.required) ? schema.required.filter((key) => typeof key === "string") : []);
   const result = {};
   for (const [key, raw] of Object.entries(input)) {
@@ -1266,7 +1748,7 @@ function normalizeObject(input, schema) {
   return result;
 }
 function normalizeAgentToolInput(input, schema) {
-  return isPlainObject2(input) ? normalizeObject(input, schema) : input;
+  return isPlainObject3(input) ? normalizeObject(input, schema) : input;
 }
 
 // src/client/agentTools.ts
@@ -1483,6 +1965,15 @@ import { parseMindooDBFormulaBooleanExpression } from "mindoodb-view-language";
 function isEmbedEventMessage(message) {
   return message.kind === "embed-event";
 }
+function isEmbedRequestMessage(message) {
+  return message.kind === "embed-request";
+}
+function isMethodNotFound(error) {
+  return error instanceof Error && error.name === "method-not-found";
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
 function isEmbeddingRequestMessage(message) {
   return message.kind === "embedding-request";
 }
@@ -1549,13 +2040,14 @@ function createComponentFrame(container, url, allow) {
   return frame;
 }
 var MindooDBAppEmbedImpl = class {
-  constructor(rpc, embedId, componentKey, databaseId, docId, frame, container) {
+  constructor(rpc, embedId, componentKey, databaseId, docId, frame, container, supports = []) {
     this.rpc = rpc;
     this.embedId = embedId;
     this.componentKey = componentKey;
     this.databaseId = databaseId;
     this.docId = docId;
     this.frame = frame;
+    this.supports = supports;
     this.closed = new Promise((resolve) => {
       this.resolveClosed = resolve;
     });
@@ -1572,6 +2064,7 @@ var MindooDBAppEmbedImpl = class {
   databaseId;
   docId;
   frame;
+  supports;
   closed;
   resolveClosed;
   closedEvent = null;
@@ -1581,6 +2074,8 @@ var MindooDBAppEmbedImpl = class {
   tracker = null;
   toolsState = null;
   toolsListeners = /* @__PURE__ */ new Set();
+  beforeSaveHandler = null;
+  savedListeners = /* @__PURE__ */ new Set();
   get placement() {
     return this.frame ? "frame" : "overlay";
   }
@@ -1663,6 +2158,88 @@ var MindooDBAppEmbedImpl = class {
       const stopClosed = this.onClosed(() => finish(null));
     });
   }
+  async inspect(request) {
+    const result = await this.rpc.call("embeds.inspect", {
+      embedId: this.embedId,
+      request: normalizeMindooDBAppInspectRequest(request)
+    });
+    return normalizeMindooDBAppInspection(result);
+  }
+  onBeforeSave(handler, options) {
+    this.beforeSaveHandler = handler;
+    this.announceBeforeSave(true, options?.inspect);
+    return () => {
+      if (this.beforeSaveHandler === handler) {
+        this.beforeSaveHandler = null;
+        this.announceBeforeSave(false);
+      }
+    };
+  }
+  /** Haven only asks hosts that said they check, and fetches the inspection they want. */
+  announceBeforeSave(enabled, inspect) {
+    if (this.closedEvent) {
+      return;
+    }
+    void this.rpc.call("embeds.setBeforeSave", {
+      embedId: this.embedId,
+      enabled,
+      ...enabled ? { inspect: normalizeMindooDBAppInspectRequest(inspect) } : {}
+    }).catch((error) => {
+      if (!isMethodNotFound(error)) {
+        console.warn("[mindoodb-app-sdk] Could not register the save check.", error);
+      }
+    });
+  }
+  /** Haven asks before the component saves: run the handler, never longer than Haven waits. */
+  async answerBeforeSave(params) {
+    const handler = this.beforeSaveHandler;
+    if (!handler || this.closedEvent) {
+      return { issues: [] };
+    }
+    const result = await handler({
+      embedId: this.embedId,
+      inspection: params?.inspection ?? null,
+      root: params?.root ?? null
+    });
+    return { issues: normalizeMindooDBAppIssues(result?.issues) };
+  }
+  onAfterSave(listener) {
+    this.savedListeners.add(listener);
+    return () => {
+      this.savedListeners.delete(listener);
+    };
+  }
+  /** The component reported that it saved. */
+  notifySaved() {
+    if (this.closedEvent) {
+      return;
+    }
+    const event = { embedId: this.embedId };
+    this.savedListeners.forEach((listener) => {
+      try {
+        listener(event);
+      } catch (error) {
+        console.error("MindooDB embed saved listener failed.", error);
+      }
+    });
+  }
+  async showIssues(issues) {
+    await this.rpc.call("embeds.showIssues", { embedId: this.embedId, issues: normalizeMindooDBAppIssues(issues) });
+  }
+  async reveal(anchor) {
+    const normalized = normalizeMindooDBAppInspectAnchor(anchor);
+    if (!normalized) {
+      throw new Error("Invalid anchor.");
+    }
+    await this.rpc.call("embeds.reveal", { embedId: this.embedId, anchor: normalized });
+  }
+  async callTool(name, input) {
+    return await this.rpc.call("embeds.callTool", {
+      embedId: this.embedId,
+      name: String(name),
+      input: input === void 0 ? {} : JSON.parse(JSON.stringify(input))
+    });
+  }
   async setRect(rect) {
     if (this.closedEvent) {
       return;
@@ -1717,6 +2294,8 @@ var MindooDBAppEmbedImpl = class {
     });
     this.listeners.clear();
     this.dirtyListeners.clear();
+    this.savedListeners.clear();
+    this.beforeSaveHandler = null;
     this.toolsState = null;
     this.toolsListeners.forEach((listener) => {
       try {
@@ -1736,6 +2315,10 @@ var MindooDBAppEmbedsClient = class {
         void this.answerRequest(message);
         return;
       }
+      if (isEmbedRequestMessage(message)) {
+        void this.answerEmbedRequest(message);
+        return;
+      }
       if (!isEmbedEventMessage(message)) {
         return;
       }
@@ -1759,6 +2342,10 @@ var MindooDBAppEmbedsClient = class {
         }
         return;
       }
+      if (message.event?.type === "saved") {
+        this.open.get(message.event.embedId)?.notifySaved();
+        return;
+      }
       if (message.event?.type !== "closed") {
         return;
       }
@@ -1796,7 +2383,8 @@ var MindooDBAppEmbedsClient = class {
           input.databaseId,
           input.docId,
           frame,
-          container
+          container,
+          Array.isArray(response.supports) ? response.supports.filter((entry) => typeof entry === "string") : []
         );
         const earlyDirty = this.earlyDirty.get(embed.embedId);
         if (earlyDirty !== void 0) {
@@ -1872,7 +2460,45 @@ var MindooDBAppEmbedsClient = class {
             this.saveHandler = null;
           }
         };
-      }
+      },
+      provideInspection: (provider) => {
+        this.inspectionProvider = provider;
+        return () => {
+          if (this.inspectionProvider === provider) {
+            this.inspectionProvider = null;
+          }
+        };
+      },
+      onShowIssues: (handler) => {
+        this.showIssuesHandler = handler;
+        return () => {
+          if (this.showIssuesHandler === handler) {
+            this.showIssuesHandler = null;
+          }
+        };
+      },
+      onReveal: (handler) => {
+        this.revealHandler = handler;
+        return () => {
+          if (this.revealHandler === handler) {
+            this.revealHandler = null;
+          }
+        };
+      },
+      validate: async (options) => await this.validate(options),
+      save: async (flush, options) => await performMindooDBAppEmbeddingSave({
+        validate: () => this.validate(options),
+        provider: this.inspectionProvider,
+        showIssues: this.showIssuesHandler,
+        flush,
+        // Only news for the host: a lost message must not fail a save that happened.
+        saved: () => this.rpc.call("embedding.saved", {}).then(
+          () => {
+          },
+          () => {
+          }
+        )
+      })
     };
   }
   rpc;
@@ -1887,18 +2513,53 @@ var MindooDBAppEmbedsClient = class {
   stopListening;
   /** This app as a component: what to do when its host asks it to save. */
   saveHandler = null;
-  /** Runs the save handler and tells Haven how it went; Haven answers the host. */
+  inspectionProvider = null;
+  showIssuesHandler = null;
+  revealHandler = null;
+  /** `embedding.validate`; ok when Haven cannot check (not embedded, older Haven). */
+  async validate(options) {
+    try {
+      const result = await this.rpc.call("embedding.validate", {
+        interactive: options?.interactive !== false
+      });
+      return {
+        ok: result?.ok !== false,
+        issues: normalizeMindooDBAppIssues(result?.issues),
+        ...result?.timedOut ? { timedOut: true } : {}
+      };
+    } catch (error) {
+      if (isMethodNotFound(error) || error instanceof Error && error.name === "unsupported") {
+        return { ok: true, issues: [] };
+      }
+      throw error;
+    }
+  }
+  /** Runs the matching handler and tells Haven how it went; Haven answers the host. */
   async answerRequest(message) {
     let response;
-    if (message.request !== "save" || !this.saveHandler) {
-      response = { ok: false, error: "unsupported" };
-    } else {
-      try {
+    try {
+      const params = message.params ?? {};
+      if (message.request === "save" && this.saveHandler) {
         await this.saveHandler();
         response = { ok: true };
-      } catch (error) {
-        response = { ok: false, error: error instanceof Error ? error.message : String(error) };
+      } else if (message.request === "inspect" && this.inspectionProvider) {
+        const inspection = await this.inspectionProvider(normalizeMindooDBAppInspectRequest(params.request));
+        response = { ok: true, result: normalizeMindooDBAppInspection(inspection) };
+      } else if (message.request === "showIssues" && this.showIssuesHandler) {
+        await this.showIssuesHandler(normalizeMindooDBAppIssues(params.issues));
+        response = { ok: true };
+      } else if (message.request === "reveal" && this.revealHandler) {
+        const anchor = normalizeMindooDBAppInspectAnchor(params.anchor);
+        if (!anchor) {
+          throw new Error("Invalid anchor.");
+        }
+        await this.revealHandler(anchor);
+        response = { ok: true };
+      } else {
+        response = { ok: false, error: "unsupported" };
       }
+    } catch (error) {
+      response = { ok: false, error: errorMessage(error) };
     }
     try {
       await this.rpc.call("embedding.respond", { requestId: message.requestId, ...response });
@@ -1906,6 +2567,24 @@ var MindooDBAppEmbedsClient = class {
       console.warn("[mindoodb-app-sdk] Could not answer the host's request.", error);
     }
   }
+  /** This app as a host: Haven asks before one of its components saves. */
+  async answerEmbedRequest(message) {
+    let response;
+    const embed = this.open.get(message.embedId);
+    try {
+      response = message.request === "beforeSave" ? { ok: true, result: embed ? await embed.answerBeforeSave(message.params) : { issues: [] } } : { ok: false, error: "unsupported" };
+    } catch (error) {
+      response = {
+        ok: true,
+        result: { issues: [{ severity: "warning", message: `The check failed: ${errorMessage(error)}`, code: "check-failed" }] }
+      };
+    }
+    try {
+      await this.rpc.call("embeds.respond", { requestId: message.requestId, ...response });
+    } catch (error) {
+      console.warn("[mindoodb-app-sdk] Could not answer Haven's request.", error);
+    }
+  }
   dispose() {
     this.stopListening();
   }
@@ -3739,6 +4418,27 @@ export {
   isValidMindooDBDocumentId,
   mindooDBDocumentId,
   assertValidMindooDBCreateIds,
+  MINDOODB_INSPECT_DOCUMENT,
+  MINDOODB_INSPECT_SPREADSHEET,
+  MINDOODB_INSPECT_SLIDES,
+  MINDOODB_APP_INSPECTION_FIELD,
+  MINDOODB_APP_INSPECTION_SUMMARY_MAX_BYTES,
+  MINDOODB_APP_INSPECTION_MAX_BYTES,
+  MINDOODB_APP_ISSUES_MAX,
+  MindooDBAppEmbedValidationError,
+  mindooDBAppComponentSupports,
+  mindooDBAppInspectContracts,
+  normalizeMindooDBAppInspectAnchor,
+  normalizeMindooDBAppIssues,
+  normalizeMindooDBAppInspectRequest,
+  normalizeMindooDBAppInspection,
+  summarizeMindooDBAppInspection,
+  mindooDBAppInspectionSummaryValue,
+  readMindooDBAppInspectionSummary,
+  defineDocumentRules,
+  mindooDBAppInspectRules,
+  performMindooDBAppEmbeddingSave,
+  resolveMindooDBAppEmbedValidation,
   MINDOODB_APP_DEFINITION_FORMAT,
   MINDOODB_APP_DEFINITION_VERSION,
   MINDOODB_APP_DEFINITION_FILE_NAME,
@@ -3747,6 +4447,15 @@ export {
   MINDOODB_APP_LISTING_SUMMARY_MAX,
   MINDOODB_APP_LISTING_DESCRIPTION_MAX,
   MINDOODB_APP_LISTING_MAX_SCREENSHOTS,
+  MINDOODB_APP_AGENT_SUMMARY_MAX,
+  MINDOODB_APP_AGENT_CAPABILITIES_MAX,
+  MINDOODB_APP_AGENT_CAPABILITY_TITLE_MAX,
+  MINDOODB_APP_AGENT_CAPABILITY_TOOLS_MAX,
+  MINDOODB_APP_AGENT_LIST_MAX,
+  MINDOODB_APP_AGENT_EXAMPLE_MAX,
+  MINDOODB_APP_AGENT_LIMIT_MAX,
+  MINDOODB_APP_AGENT_GUIDE_MAX_BYTES,
+  MINDOODB_APP_AGENT_TOOL_NAME_PATTERN,
   MINDOODB_APP_ACCEPTS_MAX,
   validateMindooDBAppAccepts,
   mindooDBAppAcceptMatchesType,
@@ -3754,6 +4463,7 @@ export {
   MINDOODB_APP_COMPONENT_CONTRACT_PATTERN,
   validateMindooDBAppComponents,
   mindooDBAppComponentFieldsMatch,
+  validateMindooDBAppAgentProfile,
   resolveMindooDBAppLocalizedText,
   resolveMindooDBAppListingAssetUrl,
   validateMindooDBAppDefinition,