mindoodb-app-sdk 0.0.53 → 0.0.55

package/README.md

@@ -22,26 +22,17 @@ A **MindooDB App** is any web application that uses this SDK to communicate with
 
 ## Architecture
 
-```
-┌─────────────────────────────────────────────────────────┐
-│  Haven (browser tab)                                    │
-│                                                         │
-│  ┌──────────────┐   ┌─────────────┐   ┌─────────────┐  │
-│  │  Haven UI    │──▶│ Bridge Host │──▶│  MindooDB    │  │
-│  │  (theme,     │   │  (RPC +     │   │  (encrypted  │  │
-│  │   viewport)  │   │   streams)  │   │   databases) │  │
-│  └──────────────┘   └──────┬──────┘   └─────────────┘  │
-│                            │                            │
-│              postMessage + MessagePort                  │
-│                            │                            │
-│  ┌─────────────────────────┼─────────────────────────┐  │
-│  │  Your App (sandboxed iframe / window)             │  │
-│  │                         │                         │  │
-│  │              ┌──────────▼──────────┐              │  │
-│  │              │  mindoodb-app-sdk   │              │  │
-│  │              └─────────────────────┘              │  │
-│  └───────────────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────────────┘
+```mermaid
+flowchart TB
+  subgraph haven["Haven (browser tab)"]
+    direction TB
+    ui["Haven UI<br/>(theme, viewport)"] --> bridge["Bridge Host<br/>(RPC + streams)"]
+    bridge --> db["MindooDB<br/>(encrypted databases)"]
+    subgraph app["Your App (sandboxed iframe / window)"]
+      sdk["mindoodb-app-sdk"]
+    end
+    bridge -- "postMessage + MessagePort" --> sdk
+  end
 ```
 
 The bridge carries RPC calls (documents, views, database info), binary attachment streams, and push events (theme changes, viewport resizes) over a single `MessagePort`.
@@ -258,6 +249,77 @@ Show a notice when the app does not have host focus, or when a long task finishe
 
 Haven uses the app's registration label as the headline and ignores any title from the app. Pass the same `id` to update that notice in place. Omit `id` to add another notice. An id only matches notices from this launch. Omit `durationMs` and the notice stays until the user dismisses it or clicks it. A duration is clamped to about 1–8 seconds, which fits a short progress step such as "10%". Clicking the notice brings that launch back. The close button only dismisses it.
 
+### Agent tools (WebMCP)
+
+An app can offer its own operations to AI agents. Haven registers them with the browser's agent interface ([WebMCP](https://webmachinelearning.github.io/webmcp/)) next to Haven's own tools, so an agent in the browser — or a local agent connected through a WebMCP bridge — can call "create a mind map", "list open tasks" or "attach this file" instead of clicking through the UI.
+
+The app declares tools; `execute` runs inside the app. Haven validates the declarations, prefixes the names with the app's key (`vega_maps_list` for an app id `mindoodb-app-vega`), checks permission, asks the user before consequential calls, and forwards each call over the bridge. The tools disappear when the app closes.
+
+Agents only see an app's tools while the user has **Agent tools** switched on in Haven (Settings → General) **and** has allowed this app (**Offer tools to AI agents** in the app's settings). Neither can be set by `haven-app.json`. `registerTools()` works either way; `enabled` in its answer says whether agents can call the tools right now.
+
+```ts
+import { createViewLanguage, MindooDBAppAgentToolError } from "mindoodb-app-sdk";
+
+const v = createViewLanguage<{ title: string; status: string; due: string }>();
+
+if (session.agent) {
+  await session.agent.registerTools([
+    {
+      name: "tasks_search",
+      description:
+        "Finds tasks by part of the title. Returns taskId, title, status and due date. " +
+        "Use the taskId with todo_tasks_complete.",
+      inputSchema: {
+        type: "object",
+        required: ["query"],
+        properties: { query: { type: "string", description: "Part of the title." } },
+      },
+      annotations: { readOnlyHint: true, untrustedContentHint: true },
+      async execute(input) {
+        const result = await database.documents.query({
+          filter: v.contains(v.lower(v.field("title")), v.string(String(input.query).toLowerCase())),
+          fields: ["title", "status", "due"],
+          limit: 20,
+        });
+        return { tasks: result.rows.map((row) => ({ taskId: row.docId, ...row.fields })) };
+      },
+    },
+    {
+      name: "tasks_complete",
+      description: "Marks a task as done. taskId comes from todo_tasks_search; never pass a title.",
+      inputSchema: {
+        type: "object",
+        required: ["taskId"],
+        properties: { taskId: { type: "string" } },
+      },
+      async execute(input) {
+        const taskId = String(input.taskId ?? "");
+        const task = await database.documents.get(taskId).catch(() => null);
+        if (!task) {
+          throw new MindooDBAppAgentToolError("NOT_FOUND", `No task "${taskId}".`, "call todo_tasks_search");
+        }
+        await database.documents.update(taskId, { set: { status: "done" } });
+        return { taskId, status: "done" };
+      },
+    },
+  ]);
+
+  // What the user has open, for "this task" / "the selected one". Small and semantic.
+  await session.agent.setContext({ view: "list", selectedTaskId: null });
+}
+```
+
+- **`registerTools(tools)`** replaces the app's whole tool set; call it again when the set changes (e.g. after a document opens). At most 30 tools; names are lower case, digits and `_`, starting with a letter.
+- **`description`** is written for a model: what the tool does, when to use it, where ids come from, what it returns. **`inputSchema`** is a JSON Schema object; use `enum` for fixed choices.
+- **`annotations`**: `readOnlyHint` for reads; `consequentialHint` for anything the user should confirm (sending, sharing, deleting) — Haven shows its own confirmation dialog and a refusal reaches the agent as `NOT_ALLOWED`; `untrustedContentHint` when the result contains text other people wrote.
+- **Errors**: throw `MindooDBAppAgentToolError(code, message, requiredAction?)` with `NOT_FOUND`, `INVALID_INPUT`, `INVALID_STATE`, `STATE_CHANGED`, `NOT_ALLOWED` or `FAILED`; `requiredAction` tells the agent what to do next ("call todo_tasks_search"). Any other exception becomes `FAILED`. Haven passes the agent one JSON error.
+- **Results** must be JSON. Return what changed (ids, new values), not just `ok`.
+- **`setContext(context)`** shows the app's state to agents in `haven_get_context` under the focused app.
+- **Files** never travel through the agent. `agent.provideFile(blob, { name, mimeType })` hands Haven a file the app produced and returns a `fileRef` (valid ten minutes) for the agent to pass to `haven_files_export`, which saves it into the user's exchange folder. `agent.takeFile(fileRef)` returns a `File` the agent imported for this app with `haven_files_import`.
+- A call that runs longer than two minutes fails with `FAILED`; files are limited to 50 MB.
+
+`session.agent` is absent on hosts without agent tools, so check for it. Test tools by calling `execute` directly in unit tests; the reference implementation is `src/features/agent/` in [mindoodb-app-vega](https://github.com/klehmann/mindoodb-app-vega). How to design tools that agents use well is in the [best practices guide](https://github.com/klehmann/MindooDB/blob/main/docs/best-practices.md) (section "Offer operations to AI agents").
+
 ### Host-owned drag
 
 When two apps run as visible workspace chicklets, native HTML5 drag dies at the iframe boundary. The SDK therefore hands the gesture to Haven: the source starts it, Haven draws a PNG ghost above every frame, and the target hit-tests the drop.
@@ -297,6 +359,7 @@ Each database mapped to your app carries a set of **capabilities** that Haven co
 | `history`     | Access document revision history and historical snapshots    |
 | `attachments` | List, upload, download, remove, and preview file attachments |
 | `views`       | Create app-defined virtual views for this database           |
+| `directory`   | List the tenant's users (`directory.listUsers()`), resolve signing keys |
 | `sealedchannel` | Open an encrypted channel to a tenant-joined service       |
 
 ```ts
@@ -312,6 +375,21 @@ if (!db.capabilities.includes("delete")) {
 
 When the database is readable, `documents.list()` can also expose deleted document IDs by setting `status: "all"` or `status: "deleted"`. This is useful for app-side indexes and sync checkpoints.
 
+### Directory users
+
+With the `directory` capability, `db.directory.listUsers()` returns the tenant's active usernames, e.g. for a recipient picker. For large directories ask for pages instead, with an optional case-insensitive search:
+
+```ts
+let cursor: string | null = null;
+do {
+  const page = await db.directory.listUsers({ query: "ann", cursor, limit: 50 });
+  addOptions(page.users);
+  cursor = page.nextCursor;
+} while (cursor);
+```
+
+Hosts that do not page yet answer with the full list; the SDK then filters and pages it on the client, so the paged form works with every Haven version.
+
 ### Sealed channels
 
 Some services join the user's tenant as a member of their own and then talk to your app over HTTP — the MindooMail bridge is the first. A sealed channel is how you reach one without your app ever touching key material.
@@ -757,23 +835,11 @@ Two layers are available:
 
 The end-to-end flow is the same in both cases:
 
-```
-            ┌────────────────────────────────────────────────────┐
-  edit ───► │ App buffer (local string + pending splices)        │ ──► flush
-            └─────────────────────────┬──────────────────────────┘
-                                      │ documents.update({
-                                      │   text: [{ path, baseHeads, edits }]
-                                      │ })
-                                      ▼
-            ┌────────────────────────────────────────────────────┐
-            │ Haven applies edits at `baseHeads` and merges with │
-            │ concurrent changes via Automerge                   │
-            └─────────────────────────┬──────────────────────────┘
-                                      │ canonical merged document
-                                      ▼
-            ┌────────────────────────────────────────────────────┐
-            │ App reconciles its editor with the canonical text  │
-            └────────────────────────────────────────────────────┘
+```mermaid
+flowchart TB
+  edit(["edit"]) --> buffer["App buffer<br/>(local string + pending splices)"]
+  buffer -- "flush: documents.update({ text: [{ path, baseHeads, edits }] })" --> merge["Haven applies edits at baseHeads<br/>and merges with concurrent changes via Automerge"]
+  merge -- "canonical merged document" --> reconcile["App reconciles its editor<br/>with the canonical text"]
 ```
 
 #### Text patch shape
@@ -1003,24 +1069,14 @@ If you must use binary sync, Haven decrypts the canonical document, merges incom
 
 Typical flow:
 
-```
-            ┌────────────────────────────────────────────────────┐
-  open  ──► │ getAutomergeSnapshot → load local replica          │
-            └─────────────────────────┬──────────────────────────┘
-                                      │
-  edit  ──► │ Local Automerge doc (or span edits applied locally)  │
-            └─────────────────────────┬──────────────────────────┘
-                                      │ getChangesSince(baseHeads)
-                                      ▼
-            ┌────────────────────────────────────────────────────┐
-  save  ──► │ applyAutomergeChanges({ baseHeads, replicaHeads,   │
-            │                       changes })                   │
-            └─────────────────────────┬──────────────────────────┘
-                                      │ Haven merges + persists
-                                      ▼
-            ┌────────────────────────────────────────────────────┐
-            │ Apply result.changesSince locally (or skip if empty) │
-            └────────────────────────────────────────────────────┘
+```mermaid
+flowchart TB
+  open(["open"]) --> snapshot["getAutomergeSnapshot<br/>→ load local replica"]
+  snapshot --> local["Local Automerge doc<br/>(or span edits applied locally)"]
+  editStep(["edit"]) --> local
+  local -- "getChangesSince(baseHeads)" --> apply["applyAutomergeChanges({<br/>baseHeads, replicaHeads, changes })"]
+  saveStep(["save"]) --> apply
+  apply -- "Haven merges + persists" --> result["Apply result.changesSince locally<br/>(or skip if empty)"]
 ```
 
 Bridge RPCs: `documents.automerge.getSnapshot` and `documents.automerge.applyChanges`.
@@ -1702,6 +1758,7 @@ What the page shows comes from the optional `listing` in `haven-app.json`. Haven
   "listing": {
     "summary": { "en": "Plan trips together.", "de": "Reisen gemeinsam planen." },
     "description": { "en": "First paragraph.\n\nSecond paragraph." },
+    "descriptionMarkdown": { "en": "**Plan** together.\n\n- Shared board\n- [Website](https://trips.example.com)" },
     "icon": "icon.svg",
     "screenshots": [{ "file": "screenshots/board.webp", "caption": { "en": "The trip board" } }],
     "publisher": { "name": "Mindoo GmbH", "url": "https://mindoo.de" }
@@ -1711,6 +1768,10 @@ What the page shows comes from the optional `listing` in `haven-app.json`. Haven
 
 Texts are a string or a per-locale map with an `en` fallback. Image paths are relative to the app origin or absolute `https:` URLs. The listing is display-only and grants nothing.
 
+Opening the app URL directly also puts share tags into `index.html` (`twitter:card` = `summary`, plus the Open Graph tags other apps read), with the app icon as the image. A production build takes the absolute URL from `publicUrl` in `haven-app.json`. `vite dev` uses the dev server's own origin instead, so `http://127.0.0.1:<port>/` previews against itself. Crawlers do not run the landing page's JavaScript, which is why the tags are in the HTML file.
+
+`description` is plain text. `descriptionMarkdown` is the same text with formatting, in a small Markdown subset: paragraphs, headings, bullet and numbered lists, `**bold**`, `_italic_`, `` `code` ``, `[text](https://…)`, `[text](mailto:…)` and bare `https://…` links. Links to any other scheme render as plain text. Readers that know `descriptionMarkdown` show it instead of `description`; older Haven versions ignore it, so set both if they matter. `listingMarkdownToPlainText()` derives the plain version. A publisher `url` (`https:` only) turns the publisher name into a link.
+
 For automated and manual tests use a separate test URL that frames the app with a mock host instead — see "Browser test host" in [`TESTING.md`](./TESTING.md). End users never see that page, and they never see mock data.
 
 ### Haven-hosted bundles
@@ -1818,6 +1879,10 @@ Connect options: `launchId?`, `targetOrigin?`, `connectTimeoutMs?`.
 | `hasHostFocus()`                      | `Promise<boolean>`                   |
 | `onHostFocusChange(listener)`         | `() => void` (unsubscribe)           |
 | `notify(input)`                       | `Promise<{ id: string }>`            |
+| `agent?.registerTools(tools)`         | `Promise<MindooDBAppAgentRegistration>` |
+| `agent?.setContext(context)`          | `Promise<void>`                      |
+| `agent?.provideFile(data, options)`   | `Promise<{ fileRef: string; size: number }>` |
+| `agent?.takeFile(fileRef)`            | `Promise<File>`                      |
 | `drag.setProfile(profile)`            | `Promise<void>`                      |
 | `drag.start(input)`                   | `Promise<MindooDBAppDragStartResult>` |
 | `drag.cancel()`                       | `Promise<void>`                      |

package/TESTING.md

@@ -337,16 +337,50 @@ mountHavenTestHost({
 });
 ```
 
-The page shows the app next to a control panel: theme and host-focus toggles, a file picker that decides what the app's next `attachments.scan()` returns (none means the user cancelled), and a live log of notifications, attachment previews, scans and every RPC request. The same controls are scriptable as `window.__havenTestHost`:
+The page shows the app next to a control panel:
+
+- **Host**: theme and host-focus toggles, reload the app frame.
+- **Language**: switches the launch context's locale live (`onLocaleChange`), so you see the app re-render in every language without a reload.
+- **Databases**: one checkbox per capability for every mapped database, plus **Enforce capabilities**. Changing a capability relaunches the app, as Haven does after a permission change. With enforcement on, the mock rejects every call the database was not granted with a `forbidden` error (and `documents.canCreate()` and friends answer `allowed: false`), so you can check the app's hints for missing rights.
+- **Directory**: fills the tenant directory with 0 to 500 generated users (`CN=Test User 001/O=Test`, …) for recipient pickers and paging.
+- **Scanner**: what `attachments.scan()` returns — cancel, a generated sample page, or a file you choose. The file is written to the document's attachments like Haven's scanner does, so the app can read it back.
+- A live log of notifications, attachment previews, scans and every RPC request. Click a request for its parameters, its result or error, and how long it took; binary values show as size plus a hex preview.
+
+`mockDatabasesFromDefinition` gives every database an in-memory attachment store (`attachments: "none"` restores the stateless default) and takes overrides for testing other mappings than the definition requests:
+
+```ts
+mountHavenTestHost({
+  appUrl: "/",
+  databases: mockDatabasesFromDefinition(definition, seed, {
+    overrides: {
+      main: { capabilities: ["read"] },    // read-only mapping
+      archive: { mapped: false },          // the user did not map this one
+    },
+  }),
+  enforceCapabilities: true,
+  directoryUsers: generateDirectoryUsers(120),
+  scanMode: "sample",
+});
+```
+
+The panel keeps its settings in the page URL, so a scenario can be linked or opened by Playwright directly: `/__haven-test/?db=main:read,attachments&db=archive:none&enforce=1&users=120&locale=de-DE&theme=dark` (`db=<id>:none` unmaps a database; URL settings win over the options). The same controls are scriptable as `window.__havenTestHost`:
 
 ```ts
-await page.goto("/__haven-test/");
+await page.goto("/__haven-test/?enforce=1");
 const app = page.frameLocator('[data-testid="haven-test-app-frame"]');
+await page.evaluate(() => window.__havenTestHost!.setCapabilities("main", ["read"])); // relaunches the app
+await expect(app.getByText("You can only view")).toBeVisible();
+
+await page.evaluate(() => window.__havenTestHost!.setLocale("de-DE"));
 await page.evaluate(() => window.__havenTestHost!.setNextScan({ fileName: "receipt.pdf", mimeType: "application/pdf", size: 1024 }));
 await app.getByRole("button", { name: "Scan" }).click();
 expect(await page.evaluate(() => window.__havenTestHost!.log.scans)).toHaveLength(1);
 ```
 
+`setNextScan()` decides only the next scan (pass `bytes` to attach real content); `setScanMode()` decides the ones after it. `setDirectoryUsers()` and `setEnforceCapabilities()` apply to the next call.
+
+The Level 1 and 2 helpers take the same options: `createMockMindooDBAppSession({ enforceCapabilities: true, directoryUsers: generateDirectoryUsers(120) })`, with `setCapabilities()`, `setEnforceCapabilities()` and `setDirectoryUsers()` on the controller, and `createMemoryAttachments()` for a database's `methods.attachments`. `createFakeBridgeHost({ onResponse })` reports every answer with its duration.
+
 Lower-level pieces, if you build your own page: `createBrowserTestHost({ frame, appUrl, ...mockOptions })` wires one iframe to a fake host, and `host.acceptConnection(message, ports)` answers a handshake you received yourself.
 
 Keep the test page out of production builds. The starter template builds it only for `vite dev` and when `HAVEN_TEST_HOST=1` is set (for preview deployments), so the app's public URL keeps showing its landing page.

package/dist/{chunk-6NTVTL6G.js → chunk-S73KTYZF.js}

@@ -431,6 +431,123 @@ function bindDragSource(element, options, start, follow) {
   };
 }
 
+// src/client/agentTools.ts
+var TOOL_NAME_PATTERN = /^[a-z][a-z0-9_]{0,47}$/;
+var MindooDBAppAgentToolError = class extends Error {
+  code;
+  requiredAction;
+  constructor(code, message, requiredAction) {
+    super(message);
+    this.name = "MindooDBAppAgentToolError";
+    this.code = code;
+    this.requiredAction = requiredAction;
+  }
+};
+function toJson(value) {
+  return value === void 0 ? null : JSON.parse(JSON.stringify(value));
+}
+var MindooDBAppAgentApiImpl = class {
+  constructor(rpc) {
+    this.rpc = rpc;
+    this.stopListening = rpc.addMessageListener((message) => {
+      if (message.kind === "agent-invoke") {
+        void this.invoke(message.callId, message.tool, message.input);
+      }
+    });
+  }
+  rpc;
+  tools = /* @__PURE__ */ new Map();
+  stopListening;
+  async registerTools(tools) {
+    const next = /* @__PURE__ */ new Map();
+    for (const tool of tools) {
+      if (!TOOL_NAME_PATTERN.test(tool.name)) {
+        throw new Error(`Invalid agent tool name "${tool.name}": use lower case, digits and underscores.`);
+      }
+      if (next.has(tool.name)) {
+        throw new Error(`Agent tool "${tool.name}" is registered twice.`);
+      }
+      next.set(tool.name, tool);
+    }
+    this.tools = next;
+    return await this.rpc.call("agent.registerTools", {
+      tools: tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: toJson(tool.inputSchema),
+        ...tool.annotations ? { annotations: { ...tool.annotations } } : {}
+      }))
+    });
+  }
+  async provideFile(data, options) {
+    const buffer = data instanceof Blob ? await data.arrayBuffer() : data instanceof Uint8Array ? data.slice().buffer : data;
+    return await this.rpc.call("agent.provideFile", {
+      name: options.name,
+      mimeType: options.mimeType ?? (data instanceof Blob ? data.type : void 0),
+      data: buffer
+    });
+  }
+  async takeFile(fileRef) {
+    const result = await this.rpc.call("agent.takeFile", {
+      fileRef
+    });
+    return new File([result.data], result.name, { type: result.mimeType });
+  }
+  async setContext(context) {
+    await this.rpc.call("agent.setContext", { context: context === null ? null : toJson(context) });
+  }
+  dispose() {
+    this.stopListening();
+    this.tools.clear();
+  }
+  async invoke(callId, name, input) {
+    let reply;
+    const tool = this.tools.get(name);
+    try {
+      if (!tool) {
+        throw new MindooDBAppAgentToolError("NOT_FOUND", `The app has no tool "${name}" (any more).`);
+      }
+      const result = await tool.execute(input ?? {});
+      reply = { protocol: "mindoodb-app-bridge", kind: "agent-result", callId, ok: true, result: toJson(result) };
+    } catch (error) {
+      reply = {
+        protocol: "mindoodb-app-bridge",
+        kind: "agent-result",
+        callId,
+        ok: false,
+        error: error instanceof MindooDBAppAgentToolError ? {
+          code: error.code,
+          message: error.message,
+          ...error.requiredAction ? { requiredAction: error.requiredAction } : {}
+        } : { code: "FAILED", message: error instanceof Error && error.message ? error.message : String(error) }
+      };
+    }
+    try {
+      this.rpc.postMessage(reply);
+    } catch (error) {
+      console.warn("[mindoodb-app-sdk] Could not return an agent tool result.", error);
+    }
+  }
+};
+
+// src/directoryPaging.ts
+var LIST_USERS_DEFAULT_LIMIT = 50;
+var LIST_USERS_MAX_LIMIT = 500;
+function pageUsers(users, options) {
+  const needle = options.query?.trim().toLocaleLowerCase();
+  const filtered = needle ? users.filter((user) => user.toLocaleLowerCase().includes(needle)) : [...users];
+  const limit = Math.min(
+    Math.max(1, Math.floor(options.limit ?? LIST_USERS_DEFAULT_LIMIT)),
+    LIST_USERS_MAX_LIMIT
+  );
+  const offset = Math.max(0, Number.parseInt(options.cursor ?? "0", 10) || 0);
+  const end = offset + limit;
+  return {
+    users: filtered.slice(offset, end),
+    nextCursor: end < filtered.length ? String(end) : null
+  };
+}
+
 // src/hostShortcuts.ts
 var DEFAULT_HAVEN_HOST_SHORTCUTS = [
   { action: "open-workspace", code: "Enter", shiftKey: true, metaOrCtrl: true },
@@ -1491,18 +1608,29 @@ var MindooDBAppDatabaseImpl = class {
         databaseId: this.databaseId,
         publicKeys
       }),
-      listUsers: async () => {
+      listUsers: (async (options) => {
+        let result;
         try {
-          return await this.rpc.call("directory.listUsers", {
-            databaseId: this.databaseId
-          });
+          result = await this.rpc.call(
+            "directory.listUsers",
+            options ? {
+              databaseId: this.databaseId,
+              query: options.query,
+              cursor: options.cursor ?? void 0,
+              limit: options.limit
+            } : { databaseId: this.databaseId }
+          );
         } catch (error) {
           if (!isMethodNotFoundError(error)) {
             throw error;
           }
-          return [];
+          result = [];
         }
-      }
+        if (!options) {
+          return Array.isArray(result) ? result : result.users;
+        }
+        return Array.isArray(result) ? pageUsers(result, options) : result;
+      })
     };
     this.attachments = {
       list: async (docId, options) => await this.rpc.call("attachments.list", {
@@ -1785,6 +1913,7 @@ var MindooDBAppSessionImpl = class {
       }
     };
     this.drag = new MindooDBAppDragApiImpl(this.rpc);
+    this.agent = new MindooDBAppAgentApiImpl(this.rpc);
     this.storage = {
       snapshot: async (options) => await this.rpc.call("appStorage.snapshot", {
         prefixes: options?.prefixes
@@ -1847,6 +1976,7 @@ var MindooDBAppSessionImpl = class {
   menus;
   drag;
   storage;
+  agent;
   beforeCloseListeners = /* @__PURE__ */ new Set();
   hostShortcuts = DEFAULT_HAVEN_HOST_SHORTCUTS;
   stopHostShortcuts;
@@ -2019,6 +2149,7 @@ var MindooDBAppSessionImpl = class {
     this.stopHostShortcuts();
     this.stopHostFocus();
     this.drag.dispose();
+    this.agent.dispose();
     try {
       await this.rpc.call("session.disconnect", {});
     } finally {
@@ -2087,6 +2218,8 @@ export {
   normalizeDragStartInput,
   snapshotElementToPng,
   bindDragSource,
+  MindooDBAppAgentToolError,
+  pageUsers,
   DEFAULT_HAVEN_HOST_SHORTCUTS,
   matchHostShortcut,
   isHostShortcutAction,

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { M as MindooDBAppAttachmentPreviewMode, a as MindooDBAppDragBindSourceOptions, b as MindooDBAppDragStartInput, c as MindooDBAppDragStartResult, d as MindooDBAppDragPreview, e as MindooDBAppBridge, f as MindooDBAppHostShortcutBinding, g as MindooDBAppHostShortcutAction, h as MindooDBAppHostingMode, i as MindooDBAppDefinition, j as MindooDBAppDatabase, k as MindooDBAppDocument, l as MindooDBAppRichTextSpan, m as MindooDBAppRichTextSnapshot, n as MindooDBAppCreateDocumentInput } from './types-CsKw_niD.js';
-export { o as MINDOODB_APP_DEFINITION_FILE_NAME, p as MINDOODB_APP_DEFINITION_FORMAT, q as MINDOODB_APP_DEFINITION_PERMISSIONS, r as MINDOODB_APP_DEFINITION_REGISTRATION_PERMISSIONS, s as MINDOODB_APP_DEFINITION_VERSION, t as MINDOODB_APP_LISTING_DESCRIPTION_MAX, u as MINDOODB_APP_LISTING_MAX_SCREENSHOTS, v as MINDOODB_APP_LISTING_SUMMARY_MAX, w as MINDOODB_APP_SEAL_SIGNING_DOMAIN, x as MINDOODB_APP_WELL_KNOWN_DRAG_TYPES, y as MindooDBAppAccessDecision, z as MindooDBAppAccessTier, A as MindooDBAppAttachmentApi, B as MindooDBAppAttachmentChunk, C as MindooDBAppAttachmentInfo, D as MindooDBAppAttachmentPreviewOptions, E as MindooDBAppAttachmentPreviewSession, F as MindooDBAppAutomergeChangesPatch, G as MindooDBAppAutomergeChangesSince, H as MindooDBAppAutomergeGetOptions, I as MindooDBAppAutomergePatchResult, J as MindooDBAppAutomergeSnapshot, K as MindooDBAppBridgeBeforeCloseAck, L as MindooDBAppBridgeBeforeCloseMessage, N as MindooDBAppBridgeConnectMessage, O as MindooDBAppBridgeConnectOptions, P as MindooDBAppBridgeConnectedMessage, Q as MindooDBAppBridgeDragDropMessage, R as MindooDBAppBridgeDragLeaveMessage, S as MindooDBAppBridgeDragOverMessage, T as MindooDBAppBridgeErrorPayload, U as MindooDBAppBridgeHandshakeErrorMessage, V as MindooDBAppBridgeHostFocusChangedMessage, W as MindooDBAppBridgeLocaleChangedMessage, X as MindooDBAppBridgePortMessage, Y as MindooDBAppBridgeQueryResultMessage, Z as MindooDBAppBridgeRpcError, _ as MindooDBAppBridgeRpcMessage, $ as MindooDBAppBridgeRpcRequest, a0 as MindooDBAppBridgeRpcSuccess, a1 as MindooDBAppBridgeShortcutInvokedMessage, a2 as MindooDBAppBridgeShortcutsChangedMessage, a3 as MindooDBAppBridgeStreamAbortRequest, a4 as MindooDBAppBridgeStreamAck, a5 as MindooDBAppBridgeStreamCloseRequest, a6 as MindooDBAppBridgeStreamError, a7 as MindooDBAppBridgeStreamMessage, a8 as MindooDBAppBridgeStreamOpenResult, a9 as MindooDBAppBridgeStreamReadRequest, aa as MindooDBAppBridgeStreamWriteRequest, ab as MindooDBAppBridgeThemeChangedMessage, ac as MindooDBAppBridgeUiPreferencesChangedMessage, ad as MindooDBAppBridgeViewChangedMessage, ae as MindooDBAppBridgeViewportChangedMessage, af as MindooDBAppBridgeWorkspaceFocusRequestedMessage, ag as MindooDBAppCapability, ah as MindooDBAppConfiguredViewCategorizationStyle, ai as MindooDBAppConfiguredViewColumn, aj as MindooDBAppConfiguredViewColumnRole, ak as MindooDBAppConfiguredViewExpressionMode, al as MindooDBAppConfiguredViewFieldExpression, am as MindooDBAppConfiguredViewFilterDefinition, an as MindooDBAppConfiguredViewFilterMode, ao as MindooDBAppConfiguredViewFilterRule, ap as MindooDBAppConfiguredViewFormulaExpression, aq as MindooDBAppConfiguredViewFormulaFilterDefinition, ar as MindooDBAppConfiguredViewPreviewMode, as as MindooDBAppConfiguredViewRuleFilterDefinition, at as MindooDBAppConfiguredViewRuleMatchMode, au as MindooDBAppConfiguredViewRuleOperator, av as MindooDBAppConfiguredViewValueExpression, aw as MindooDBAppCreateKeyInfo, ax as MindooDBAppCreateViewInput, ay as MindooDBAppCreateViewNavigatorInput, az as MindooDBAppDatabaseInfo, aA as MindooDBAppDefinitionDatabase, aB as MindooDBAppDefinitionListing, aC as MindooDBAppDefinitionPermission, aD as MindooDBAppDefinitionRegistrationPermission, aE as MindooDBAppDefinitionScreenshot, aF as MindooDBAppDefinitionValidation, aG as MindooDBAppDirectoryApi, aH as MindooDBAppDirectoryEntry, aI as MindooDBAppDocumentApi, aJ as MindooDBAppDocumentHeadCursorResult, aK as MindooDBAppDocumentHistoryEntry, aL as MindooDBAppDocumentListQuery, aM as MindooDBAppDocumentListResult, aN as MindooDBAppDocumentQuery, aO as MindooDBAppDocumentRevisionId, aP as MindooDBAppDocumentScanPreset, aQ as MindooDBAppDocumentSummary, aR as MindooDBAppDragApi, aS as MindooDBAppDragCancelReason, aT as MindooDBAppDragDropEvent, aU as MindooDBAppDragEffect, aV as MindooDBAppDragHoverResult, aW as MindooDBAppDragOffer, aX as MindooDBAppDragOverEvent, aY as MindooDBAppDragPointer, aZ as MindooDBAppDragProfile, a_ as MindooDBAppEntryAttachmentRef, a$ as MindooDBAppEntryProvenance, b0 as MindooDBAppExtractDocumentTextInput, b1 as MindooDBAppExtractDocumentTextResult, b2 as MindooDBAppExtractTextFormat, b3 as MindooDBAppExtractionSetup, b4 as MindooDBAppFulltextSetup, b5 as MindooDBAppHistoricalDocument, b6 as MindooDBAppHistoryQuery, b7 as MindooDBAppHostTheme, b8 as MindooDBAppIdentityApi, b9 as MindooDBAppInaccessibleDocument, ba as MindooDBAppInaccessibleDocumentListQuery, bb as MindooDBAppInaccessibleDocumentListResult, bc as MindooDBAppJsonCounterIncrementPatch, bd as MindooDBAppJsonListDeletePatch, be as MindooDBAppJsonListInsertPatch, bf as MindooDBAppJsonPatch, bg as MindooDBAppJsonSetPatch, bh as MindooDBAppJsonTextMarkPatch, bi as MindooDBAppJsonTextSplicePatch, bj as MindooDBAppJsonTextUnmarkPatch, bk as MindooDBAppJsonUnsetPatch, bl as MindooDBAppLaunchContext, bm as MindooDBAppLiveQuerySubscription, bn as MindooDBAppLocalizedText, bo as MindooDBAppMenuAnchor, bp as MindooDBAppMenuApi, bq as MindooDBAppMenuCommandItem, br as MindooDBAppMenuDismissReason, bs as MindooDBAppMenuDismissedResult, bt as MindooDBAppMenuItem, bu as MindooDBAppMenuKind, bv as MindooDBAppMenuPlacement, bw as MindooDBAppMenuPointAnchor, bx as MindooDBAppMenuRect, by as MindooDBAppMenuRectAnchor, bz as MindooDBAppMenuSelectionResult, bA as MindooDBAppMenuSeparatorItem, bB as MindooDBAppNotificationSeverity, bC as MindooDBAppNotifyInput, bD as MindooDBAppNotifyResult, bE as MindooDBAppProposeAppInput, bF as MindooDBAppProposeAppResult, bG as MindooDBAppQueryCoverage, bH as MindooDBAppQueryInclude, bI as MindooDBAppQueryIncludeCardinality, bJ as MindooDBAppQueryIncludeSlots, bK as MindooDBAppQueryResult, bL as MindooDBAppQueryRow, bM as MindooDBAppQuerySortKey, bN as MindooDBAppQueryTextClause, bO as MindooDBAppReadableAttachmentStream, bP as MindooDBAppRecipientOptions, bQ as MindooDBAppResolvedViewDefinition, bR as MindooDBAppResolvedViewSource, bS as MindooDBAppRevisionPhase, bT as MindooDBAppRevisionVerification, bU as MindooDBAppRichTextBlockSpan, bV as MindooDBAppRichTextGetOptions, bW as MindooDBAppRichTextImmutableString, bX as MindooDBAppRichTextMarkRange, bY as MindooDBAppRichTextMaterializeValue, bZ as MindooDBAppRichTextPatch, b_ as MindooDBAppRichTextScalar, b$ as MindooDBAppRichTextSpliceStep, c0 as MindooDBAppRichTextStep, c1 as MindooDBAppRichTextStepPatch, c2 as MindooDBAppRichTextTextSpan, c3 as MindooDBAppRuntime, c4 as MindooDBAppScanAttachmentOptions, c5 as MindooDBAppScanAttachmentResult, c6 as MindooDBAppScopedDocId, c7 as MindooDBAppScopedDocumentSummary, c8 as MindooDBAppSealIntent, c9 as MindooDBAppSealedChannelOpenInput, ca as MindooDBAppSealedChannelOpenResult, cb as MindooDBAppSealedChannelRequestInput, cc as MindooDBAppSession, cd as MindooDBAppShowMenuInput, ce as MindooDBAppShowMenuResult, cf as MindooDBAppSignPreview, cg as MindooDBAppSignPreviewScope, ch as MindooDBAppSignStatementInput, ci as MindooDBAppSignStatementResult, cj as MindooDBAppStorageApi, ck as MindooDBAppSummarySetup, cl as MindooDBAppTextCursorOptions, cm as MindooDBAppTextCursorPosition, cn as MindooDBAppTextCursorPositionsResult, co as MindooDBAppTextCursorsResult, cp as MindooDBAppTextEdit, cq as MindooDBAppTextPatch, cr as MindooDBAppThemeMode, cs as MindooDBAppTimestampApi, ct as MindooDBAppTimestampInput, cu as MindooDBAppTimestampProvider, cv as MindooDBAppTimestampResult, cw as MindooDBAppUiPreferences, cx as MindooDBAppUpdateDocumentInput, cy as MindooDBAppViewCursorDocumentListResult, cz as MindooDBAppViewCursorResult, cA as MindooDBAppViewEntry, cB as MindooDBAppViewEntryKind, cC as MindooDBAppViewNavigator, cD as MindooDBAppViewNavigatorExpansionState, cE as MindooDBAppViewNavigatorOpenOptions, cF as MindooDBAppViewNavigatorPageOptions, cG as MindooDBAppViewNavigatorPageResult, cH as MindooDBAppViewNavigatorRangeQuery, cI as MindooDBAppViewNavigatorSelectionState, cJ as MindooDBAppViewUpdateStats, cK as MindooDBAppViewport, cL as MindooDBAppWellKnownDragType, cM as MindooDBAppWritableAttachmentStream, cN as resolveMindooDBAppDefinitionUrl, cO as resolveMindooDBAppListingAssetUrl, cP as resolveMindooDBAppLocalizedText, cQ as validateMindooDBAppDefinition } from './types-CsKw_niD.js';
+import { M as MindooDBAppAttachmentPreviewMode, a as MindooDBAppDragBindSourceOptions, b as MindooDBAppDragStartInput, c as MindooDBAppDragStartResult, d as MindooDBAppDragPreview, e as MindooDBAppBridge, f as MindooDBAppAgentToolErrorCode, g as MindooDBAppHostShortcutBinding, h as MindooDBAppHostShortcutAction, i as MindooDBAppHostingMode, j as MindooDBAppDefinition, k as MindooDBAppDatabase, l as MindooDBAppDocument, m as MindooDBAppRichTextSpan, n as MindooDBAppRichTextSnapshot, o as MindooDBAppCreateDocumentInput } from './types-Dl70Tlfj.js';
+export { p as MINDOODB_APP_DEFINITION_FILE_NAME, q as MINDOODB_APP_DEFINITION_FORMAT, r as MINDOODB_APP_DEFINITION_PERMISSIONS, s as MINDOODB_APP_DEFINITION_REGISTRATION_PERMISSIONS, t as MINDOODB_APP_DEFINITION_VERSION, u as MINDOODB_APP_LISTING_DESCRIPTION_MAX, v as MINDOODB_APP_LISTING_MAX_SCREENSHOTS, w as MINDOODB_APP_LISTING_SUMMARY_MAX, x as MINDOODB_APP_SEAL_SIGNING_DOMAIN, y as MINDOODB_APP_WELL_KNOWN_DRAG_TYPES, z as MindooDBAppAccessDecision, A as MindooDBAppAccessTier, B as MindooDBAppAgentApi, C as MindooDBAppAgentRegistration, D as MindooDBAppAgentTool, E as MindooDBAppAgentToolAnnotations, F as MindooDBAppAgentToolDescriptor, G as MindooDBAppAttachmentApi, H as MindooDBAppAttachmentChunk, I as MindooDBAppAttachmentInfo, J as MindooDBAppAttachmentPreviewOptions, K as MindooDBAppAttachmentPreviewSession, L as MindooDBAppAutomergeChangesPatch, N as MindooDBAppAutomergeChangesSince, O as MindooDBAppAutomergeGetOptions, P as MindooDBAppAutomergePatchResult, Q as MindooDBAppAutomergeSnapshot, R as MindooDBAppBridgeAgentInvokeMessage, S as MindooDBAppBridgeAgentResultMessage, T as MindooDBAppBridgeBeforeCloseAck, U as MindooDBAppBridgeBeforeCloseMessage, V as MindooDBAppBridgeConnectMessage, W as MindooDBAppBridgeConnectOptions, X as MindooDBAppBridgeConnectedMessage, Y as MindooDBAppBridgeDragDropMessage, Z as MindooDBAppBridgeDragLeaveMessage, _ as MindooDBAppBridgeDragOverMessage, $ as MindooDBAppBridgeErrorPayload, a0 as MindooDBAppBridgeHandshakeErrorMessage, a1 as MindooDBAppBridgeHostFocusChangedMessage, a2 as MindooDBAppBridgeLocaleChangedMessage, a3 as MindooDBAppBridgePortMessage, a4 as MindooDBAppBridgeQueryResultMessage, a5 as MindooDBAppBridgeRpcError, a6 as MindooDBAppBridgeRpcMessage, a7 as MindooDBAppBridgeRpcRequest, a8 as MindooDBAppBridgeRpcSuccess, a9 as MindooDBAppBridgeShortcutInvokedMessage, aa as MindooDBAppBridgeShortcutsChangedMessage, ab as MindooDBAppBridgeStreamAbortRequest, ac as MindooDBAppBridgeStreamAck, ad as MindooDBAppBridgeStreamCloseRequest, ae as MindooDBAppBridgeStreamError, af as MindooDBAppBridgeStreamMessage, ag as MindooDBAppBridgeStreamOpenResult, ah as MindooDBAppBridgeStreamReadRequest, ai as MindooDBAppBridgeStreamWriteRequest, aj as MindooDBAppBridgeThemeChangedMessage, ak as MindooDBAppBridgeUiPreferencesChangedMessage, al as MindooDBAppBridgeViewChangedMessage, am as MindooDBAppBridgeViewportChangedMessage, an as MindooDBAppBridgeWorkspaceFocusRequestedMessage, ao as MindooDBAppCapability, ap as MindooDBAppConfiguredViewCategorizationStyle, aq as MindooDBAppConfiguredViewColumn, ar as MindooDBAppConfiguredViewColumnRole, as as MindooDBAppConfiguredViewExpressionMode, at as MindooDBAppConfiguredViewFieldExpression, au as MindooDBAppConfiguredViewFilterDefinition, av as MindooDBAppConfiguredViewFilterMode, aw as MindooDBAppConfiguredViewFilterRule, ax as MindooDBAppConfiguredViewFormulaExpression, ay as MindooDBAppConfiguredViewFormulaFilterDefinition, az as MindooDBAppConfiguredViewPreviewMode, aA as MindooDBAppConfiguredViewRuleFilterDefinition, aB as MindooDBAppConfiguredViewRuleMatchMode, aC as MindooDBAppConfiguredViewRuleOperator, aD as MindooDBAppConfiguredViewValueExpression, aE as MindooDBAppCreateKeyInfo, aF as MindooDBAppCreateViewInput, aG as MindooDBAppCreateViewNavigatorInput, aH as MindooDBAppDatabaseInfo, aI as MindooDBAppDefinitionDatabase, aJ as MindooDBAppDefinitionListing, aK as MindooDBAppDefinitionPermission, aL as MindooDBAppDefinitionRegistrationPermission, aM as MindooDBAppDefinitionScreenshot, aN as MindooDBAppDefinitionValidation, aO as MindooDBAppDirectoryApi, aP as MindooDBAppDirectoryEntry, aQ as MindooDBAppDocumentApi, aR as MindooDBAppDocumentHeadCursorResult, aS as MindooDBAppDocumentHistoryEntry, aT as MindooDBAppDocumentListQuery, aU as MindooDBAppDocumentListResult, aV as MindooDBAppDocumentQuery, aW as MindooDBAppDocumentRevisionId, aX as MindooDBAppDocumentScanPreset, aY as MindooDBAppDocumentSummary, aZ as MindooDBAppDragApi, a_ as MindooDBAppDragCancelReason, a$ as MindooDBAppDragDropEvent, b0 as MindooDBAppDragEffect, b1 as MindooDBAppDragHoverResult, b2 as MindooDBAppDragOffer, b3 as MindooDBAppDragOverEvent, b4 as MindooDBAppDragPointer, b5 as MindooDBAppDragProfile, b6 as MindooDBAppEntryAttachmentRef, b7 as MindooDBAppEntryProvenance, b8 as MindooDBAppExtractDocumentTextInput, b9 as MindooDBAppExtractDocumentTextResult, ba as MindooDBAppExtractTextFormat, bb as MindooDBAppExtractionSetup, bc as MindooDBAppFulltextSetup, bd as MindooDBAppHistoricalDocument, be as MindooDBAppHistoryQuery, bf as MindooDBAppHostTheme, bg as MindooDBAppIdentityApi, bh as MindooDBAppInaccessibleDocument, bi as MindooDBAppInaccessibleDocumentListQuery, bj as MindooDBAppInaccessibleDocumentListResult, bk as MindooDBAppJsonCounterIncrementPatch, bl as MindooDBAppJsonListDeletePatch, bm as MindooDBAppJsonListInsertPatch, bn as MindooDBAppJsonPatch, bo as MindooDBAppJsonSetPatch, bp as MindooDBAppJsonTextMarkPatch, bq as MindooDBAppJsonTextSplicePatch, br as MindooDBAppJsonTextUnmarkPatch, bs as MindooDBAppJsonUnsetPatch, bt as MindooDBAppLaunchContext, bu as MindooDBAppListUsersOptions, bv as MindooDBAppListUsersPage, bw as MindooDBAppLiveQuerySubscription, bx as MindooDBAppLocalizedText, by as MindooDBAppMenuAnchor, bz as MindooDBAppMenuApi, bA as MindooDBAppMenuCommandItem, bB as MindooDBAppMenuDismissReason, bC as MindooDBAppMenuDismissedResult, bD as MindooDBAppMenuItem, bE as MindooDBAppMenuKind, bF as MindooDBAppMenuPlacement, bG as MindooDBAppMenuPointAnchor, bH as MindooDBAppMenuRect, bI as MindooDBAppMenuRectAnchor, bJ as MindooDBAppMenuSelectionResult, bK as MindooDBAppMenuSeparatorItem, bL as MindooDBAppNotificationSeverity, bM as MindooDBAppNotifyInput, bN as MindooDBAppNotifyResult, bO as MindooDBAppProposeAppInput, bP as MindooDBAppProposeAppResult, bQ as MindooDBAppQueryCoverage, bR as MindooDBAppQueryInclude, bS as MindooDBAppQueryIncludeCardinality, bT as MindooDBAppQueryIncludeSlots, bU as MindooDBAppQueryResult, bV as MindooDBAppQueryRow, bW as MindooDBAppQuerySortKey, bX as MindooDBAppQueryTextClause, bY as MindooDBAppReadableAttachmentStream, bZ as MindooDBAppRecipientOptions, b_ as MindooDBAppResolvedViewDefinition, b$ as MindooDBAppResolvedViewSource, c0 as MindooDBAppRevisionPhase, c1 as MindooDBAppRevisionVerification, c2 as MindooDBAppRichTextBlockSpan, c3 as MindooDBAppRichTextGetOptions, c4 as MindooDBAppRichTextImmutableString, c5 as MindooDBAppRichTextMarkRange, c6 as MindooDBAppRichTextMaterializeValue, c7 as MindooDBAppRichTextPatch, c8 as MindooDBAppRichTextScalar, c9 as MindooDBAppRichTextSpliceStep, ca as MindooDBAppRichTextStep, cb as MindooDBAppRichTextStepPatch, cc as MindooDBAppRichTextTextSpan, cd as MindooDBAppRuntime, ce as MindooDBAppScanAttachmentOptions, cf as MindooDBAppScanAttachmentResult, cg as MindooDBAppScopedDocId, ch as MindooDBAppScopedDocumentSummary, ci as MindooDBAppSealIntent, cj as MindooDBAppSealedChannelOpenInput, ck as MindooDBAppSealedChannelOpenResult, cl as MindooDBAppSealedChannelRequestInput, cm as MindooDBAppSession, cn as MindooDBAppShowMenuInput, co as MindooDBAppShowMenuResult, cp as MindooDBAppSignPreview, cq as MindooDBAppSignPreviewScope, cr as MindooDBAppSignStatementInput, cs as MindooDBAppSignStatementResult, ct as MindooDBAppStorageApi, cu as MindooDBAppSummarySetup, cv as MindooDBAppTextCursorOptions, cw as MindooDBAppTextCursorPosition, cx as MindooDBAppTextCursorPositionsResult, cy as MindooDBAppTextCursorsResult, cz as MindooDBAppTextEdit, cA as MindooDBAppTextPatch, cB as MindooDBAppThemeMode, cC as MindooDBAppTimestampApi, cD as MindooDBAppTimestampInput, cE as MindooDBAppTimestampProvider, cF as MindooDBAppTimestampResult, cG as MindooDBAppUiPreferences, cH as MindooDBAppUpdateDocumentInput, cI as MindooDBAppViewCursorDocumentListResult, cJ as MindooDBAppViewCursorResult, cK as MindooDBAppViewEntry, cL as MindooDBAppViewEntryKind, cM as MindooDBAppViewNavigator, cN as MindooDBAppViewNavigatorExpansionState, cO as MindooDBAppViewNavigatorOpenOptions, cP as MindooDBAppViewNavigatorPageOptions, cQ as MindooDBAppViewNavigatorPageResult, cR as MindooDBAppViewNavigatorRangeQuery, cS as MindooDBAppViewNavigatorSelectionState, cT as MindooDBAppViewUpdateStats, cU as MindooDBAppViewport, cV as MindooDBAppWellKnownDragType, cW as MindooDBAppWritableAttachmentStream, cX as resolveMindooDBAppDefinitionUrl, cY as resolveMindooDBAppListingAssetUrl, cZ as resolveMindooDBAppLocalizedText, c_ as validateMindooDBAppDefinition } from './types-Dl70Tlfj.js';
 export { M as MINDOODB_APP_BUNDLE_ARCHIVE_FILE_NAME, a as MINDOODB_APP_BUNDLE_MANIFEST_FILE_NAME, b as MINDOODB_APP_BUNDLE_MANIFEST_FORMAT, c as MINDOODB_APP_BUNDLE_MANIFEST_VERSION, d as MindooDBAppBundleArchive, e as MindooDBAppBundleFileEntry, f as MindooDBAppBundleHash, g as MindooDBAppBundleManifest, h as MindooDBAppBundleManifestValidation, i as buildMindooDBAppBundleContentHashInput, j as isMindooDBAppBundleHash, n as normalizeMindooDBAppBundlePath, v as validateMindooDBAppBundleManifest } from './appBundleManifest-B0xfpaXG.js';
 import { MindooDBAppBooleanExpression } from 'mindoodb-view-language';
 export { MindooDBAppBooleanExpression, MindooDBAppExpression, MindooDBAppFilterDefinition, MindooDBAppViewCategoryChildrenPageRequest, MindooDBAppViewColumn, MindooDBAppViewColumnRole, MindooDBAppViewDefinition, MindooDBAppViewExpansionState, MindooDBAppViewExpressionBase, MindooDBAppViewExpressionDatePart, MindooDBAppViewExpressionOperation, MindooDBAppViewFieldExpression, MindooDBAppViewIfExpression, MindooDBAppViewLetExpression, MindooDBAppViewLiteralExpression, MindooDBAppViewLookupByPath, MindooDBAppViewOperationExpression, MindooDBAppViewOriginExpression, MindooDBAppViewPageRequest, MindooDBAppViewPageResult, MindooDBAppViewRow, MindooDBAppViewSortDirection, MindooDBAppViewTotalMode, MindooDBAppViewValueExpressionRef, MindooDBAppViewVariableExpression, createViewLanguage } from 'mindoodb-view-language';
@@ -166,6 +166,25 @@ declare function releaseMindooDBAppBridgeSessions(launchId?: string): void;
  */
 declare function createMindooDBAppBridge(): MindooDBAppBridge;
 
+/**
+ * App side of agent tools: keeps the implementations, tells Haven what exists,
+ * and answers Haven's `agent-invoke` messages.
+ *
+ * Only descriptors cross the bridge. `execute` stays in the app and runs when
+ * Haven forwards an agent's call; the outcome goes back as one `agent-result`
+ * message per call. A tool that throws {@link MindooDBAppAgentToolError}
+ * reports its code; any other exception becomes `FAILED`.
+ *
+ * @module agentTools
+ */
+
+/** Throw from `execute` to give the agent a code and, ideally, what to do next. */
+declare class MindooDBAppAgentToolError extends Error {
+    readonly code: MindooDBAppAgentToolErrorCode;
+    readonly requiredAction?: string;
+    constructor(code: MindooDBAppAgentToolErrorCode, message: string, requiredAction?: string);
+}
+
 /**
  * Haven's default host chords. Both sides of the bridge use this table so a
  * key that Haven handles on its own pages is the same key an iframe reports.
@@ -295,6 +314,64 @@ declare function buildHavenAppInstallUrl(appUrl: string, havenUrl?: string): str
  */
 declare function renderHavenAppLandingPage(options?: RenderHavenAppLandingPageOptions): Promise<HavenAppLandingPage>;
 
+/**
+ * The Markdown subset a publisher may use in `listing.descriptionMarkdown`.
+ *
+ * The text comes from a file on the publisher's server and is shown before anyone has
+ * agreed to install the app, so it is parsed into a small tree here and rendered with
+ * `createElement`/`textContent` (or Vue render functions) — never as HTML. What the
+ * subset knows:
+ *
+ * - paragraphs (blank lines), headings (`#`), bullet (`-`, `*`, `+`) and numbered lists
+ * - `**bold**`, `__bold__`, `*italic*`, `_italic_`, `` `code` ``, `\` escapes
+ * - `[text](https://…)`, `[text](mailto:…)` and bare `https://…` links
+ *
+ * Anything else stays literal text. Links are limited to `https:` and `mailto:` by
+ * {@link sanitizeListingHref}; a link with any other target renders as its text only.
+ *
+ * DOM-free on purpose, so Haven, the landing page and build scripts can share it.
+ */
+type ListingInline = {
+    type: "text";
+    text: string;
+} | {
+    type: "code";
+    text: string;
+} | {
+    type: "strong";
+    children: ListingInline[];
+} | {
+    type: "em";
+    children: ListingInline[];
+} | {
+    type: "link";
+    href: string;
+    children: ListingInline[];
+};
+type ListingBlock = {
+    type: "paragraph";
+    children: ListingInline[];
+} | {
+    type: "heading";
+    children: ListingInline[];
+} | {
+    type: "list";
+    ordered: boolean;
+    items: ListingInline[][];
+};
+/**
+ * `https:` and `mailto:` only. Embedded tab/LF/CR are stripped first, as browsers do,
+ * so `java\nscript:` cannot slip past the scheme check.
+ */
+declare function sanitizeListingHref(raw: string): string | null;
+/** Parses a description into blocks. Unknown syntax stays text; nothing is dropped. */
+declare function parseListingMarkdown(markdown: string): ListingBlock[];
+/**
+ * The same text for readers that only show plain paragraphs (`listing.description`):
+ * one paragraph per block and per list item, links as "text (url)".
+ */
+declare function listingMarkdownToPlainText(markdown: string): string;
+
 interface InstallHavenStorageShimOptions {
     /**
      * Key prefixes whose values are written through to the host and restored on the next
@@ -501,4 +578,4 @@ declare function inheritDocumentEncryption(parent: Pick<MindooDBAppDocument, "de
  */
 declare function watchWordChunks(database: MindooDBAppDatabase, parentId: string, listener: (docIds: string[]) => void): Promise<() => Promise<void>>;
 
-export { type CreateMindooDBRichTextHandleOptions, type CreateMindooDBTextBufferOptions, DEFAULT_DRAG_LONG_PRESS_MS, DEFAULT_DRAG_POINTER_THRESHOLD_PX, DEFAULT_HAVEN_HOST_SHORTCUTS, DEFAULT_HAVEN_URL, type HavenAppLandingPage, type HavenStorageShimHandle, type InstallHavenStorageShimOptions, MINDOODB_APP_HOSTING_QUERY_PARAM, MINDOODB_APP_LAUNCH_ID_QUERY_PARAM, MINDOODB_APP_MAX_DRAG_PAYLOAD_BYTES, MINDOODB_APP_MAX_DRAG_PREVIEW_BYTES, MINDOODB_APP_MAX_DRAG_PREVIEW_EDGE, MINDOODB_APP_MAX_DRAG_TYPES, MINDOODB_APP_VALUE_TAG, MINIMAL_DRAG_PREVIEW_PNG, type MindooDBAppAtomicValue, MindooDBAppAttachmentPreviewMode, MindooDBAppBridge, type MindooDBAppCounterValue, MindooDBAppCreateDocumentInput, MindooDBAppDatabase, MindooDBAppDefinition, MindooDBAppDocument, MindooDBAppDragBindSourceOptions, MindooDBAppDragInputError, MindooDBAppDragPreview, MindooDBAppDragStartInput, MindooDBAppDragStartResult, MindooDBAppHostShortcutAction, MindooDBAppHostShortcutBinding, MindooDBAppHostingMode, MindooDBAppRichTextSnapshot, MindooDBAppRichTextSpan, type MindooDBAppTimestampValue, type MindooDBAppTypedValue, MindooDBAppValue, MindooDBRichTextHandle, type MindooDBRichTextHandleChangeListener, type MindooDBRichTextHandleFlushResult, MindooDBTextBuffer, type MindooDBTextBufferFlushResult, type RenderHavenAppLandingPageOptions, abbreviateCanonicalName, applyHostedDocumentOverscrollContain, bindDragSource, buildHavenAppInstallUrl, canPreviewAttachment, createMindooDBAppBridge, createMindooDBRichTextHandle, createMindooDBTextBuffer, expandAbbreviatedName, inheritDocumentEncryption, installHavenStorageShim, installHostShortcutCapture, isHostShortcutAction, isHostedBundleRuntime, isLaunchedByHaven, isMindooDBAppDragType, matchHostShortcut, normalizeDragAccepts, normalizeDragPointerInput, normalizeDragStartInput, queryDocuments, readMindooDBAppHostingMode, readMindooDBAppLaunchId, releaseMindooDBAppBridgeSessions, renderHavenAppLandingPage, resolveCurrentHavenAppUrl, sanitizeHostShortcutBindings, snapshotElementToPng, watchWordChunks };
+export { type CreateMindooDBRichTextHandleOptions, type CreateMindooDBTextBufferOptions, DEFAULT_DRAG_LONG_PRESS_MS, DEFAULT_DRAG_POINTER_THRESHOLD_PX, DEFAULT_HAVEN_HOST_SHORTCUTS, DEFAULT_HAVEN_URL, type HavenAppLandingPage, type HavenStorageShimHandle, type InstallHavenStorageShimOptions, type ListingBlock, type ListingInline, MINDOODB_APP_HOSTING_QUERY_PARAM, MINDOODB_APP_LAUNCH_ID_QUERY_PARAM, MINDOODB_APP_MAX_DRAG_PAYLOAD_BYTES, MINDOODB_APP_MAX_DRAG_PREVIEW_BYTES, MINDOODB_APP_MAX_DRAG_PREVIEW_EDGE, MINDOODB_APP_MAX_DRAG_TYPES, MINDOODB_APP_VALUE_TAG, MINIMAL_DRAG_PREVIEW_PNG, MindooDBAppAgentToolError, MindooDBAppAgentToolErrorCode, type MindooDBAppAtomicValue, MindooDBAppAttachmentPreviewMode, MindooDBAppBridge, type MindooDBAppCounterValue, MindooDBAppCreateDocumentInput, MindooDBAppDatabase, MindooDBAppDefinition, MindooDBAppDocument, MindooDBAppDragBindSourceOptions, MindooDBAppDragInputError, MindooDBAppDragPreview, MindooDBAppDragStartInput, MindooDBAppDragStartResult, MindooDBAppHostShortcutAction, MindooDBAppHostShortcutBinding, MindooDBAppHostingMode, MindooDBAppRichTextSnapshot, MindooDBAppRichTextSpan, type MindooDBAppTimestampValue, type MindooDBAppTypedValue, MindooDBAppValue, MindooDBRichTextHandle, type MindooDBRichTextHandleChangeListener, type MindooDBRichTextHandleFlushResult, MindooDBTextBuffer, type MindooDBTextBufferFlushResult, type RenderHavenAppLandingPageOptions, abbreviateCanonicalName, applyHostedDocumentOverscrollContain, bindDragSource, buildHavenAppInstallUrl, canPreviewAttachment, createMindooDBAppBridge, createMindooDBRichTextHandle, createMindooDBTextBuffer, expandAbbreviatedName, inheritDocumentEncryption, installHavenStorageShim, installHostShortcutCapture, isHostShortcutAction, isHostedBundleRuntime, isLaunchedByHaven, isMindooDBAppDragType, listingMarkdownToPlainText, matchHostShortcut, normalizeDragAccepts, normalizeDragPointerInput, normalizeDragStartInput, parseListingMarkdown, queryDocuments, readMindooDBAppHostingMode, readMindooDBAppLaunchId, releaseMindooDBAppBridgeSessions, renderHavenAppLandingPage, resolveCurrentHavenAppUrl, sanitizeHostShortcutBindings, sanitizeListingHref, snapshotElementToPng, watchWordChunks };