mindoodb-app-sdk 0.0.73 → 0.0.74

package/README.md

@@ -266,7 +266,7 @@ Haven uses the app's registration label as the headline and ignores any title fr
 
 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 tool prefix (`vega_maps_list` for `"agentToolPrefix": "vega"` in `haven-app.json`; without it Haven derives one from the app id or label), checks permission, asks the user before consequential calls, and forwards each call over the bridge. The tools disappear when the app closes.
+The app declares tools; `execute` runs inside the app. Haven validates the declarations, prefixes the names with the app's tool prefix (`todo_list` for `"agentToolPrefix": "todo"` in `haven-app.json`; without it Haven derives one from the app id or label), 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.
 
@@ -420,7 +420,7 @@ Agents only see an app's tools while it runs. To pick the right app first, they
 - **`summary`**: neutral, 1-3 sentences, at most 400 characters per locale; `en` is required.
 - **`capabilities`**: 1-8 entries; `tools` names the tools as in `registerTools` (no prefix, no `haven_*`). Together they should cover every tool.
 - **`examples`**, **`limits`**: up to 8 strings per locale.
-- **`guide`**: Markdown how-to per locale, a path relative to `haven-app.json` (at most 8 KB): typical steps, where ids come from, pitfalls. Parameter tables belong in the tools (or `ops_guide`), not here.
+- **`guide`**: Markdown how-to per locale, a path relative to `haven-app.json` (at most 8 KB): typical steps, where ids come from, pitfalls. Parameter tables belong in the tools (or `ops_guide`), not here. Haven fetches it cross-origin, so serve it with `Access-Control-Allow-Origin: *` like `haven-app.json` (Cloudflare: an `/agent/*` rule in `public/_headers`).
 
 Keep the profile honest with a unit test: `checkAgentManifest` from `mindoodb-app-sdk/testing` compares it with the registered tools and fails when a capability or the guide names a tool that does not exist (`assertAgentManifest` throws instead):
 
@@ -436,7 +436,27 @@ const warnings = assertAgentManifest({
 expect(warnings).toEqual([]); // every tool belongs to a capability
 ```
 
-`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").
+`session.agent` is absent on hosts without agent tools, so check for it. `registerTools()` answers `{ enabled, exposedNames }`: show from `enabled` whether agents can call the tools right now (and that **Offer tools to AI agents** switches them on), and use `exposedNames` when you display the names agents see. There is no event when the user changes the setting later; register again (e.g. when the app regains focus) to refresh it.
+
+#### A recommended tool set for a data app
+
+What the open-source SDK example app and TodoManager offer, from small to large:
+
+- `get_context`: the open database, read-only or not, the signed-in user, today's date, what is selected. Agents call it first.
+- `list` / `search`: exact criteria through `documents.query` filters on the summary buffer, topics through a full-text `text` clause, bounded output with `truncated`. Check `db.getFulltextSetup()` first: Haven rejects `text` with `fulltext-not-enabled` when the database has no index, while the mock answers anyway.
+- `get`, `create`, `update`, `delete` over a small public model, never storage field names; `delete` with `consequentialHint`. Batch with lists so one call is one step.
+- `undo` (and `history`/`redo` in larger apps): every write call is one undo step marked as made by an agent; undo refuses with `STATE_CHANGED` when the document changed since, so agents never overwrite user work.
+- `users_search` when the app stores people: look names up in the tenant directory (`directory` permission) and store the directory id.
+
+Small reference: `src/features/agent/` and `src/app/useAgentSection.ts` in [mindoodb-app-example](https://github.com/klehmann/mindoodb-app-example) (eight tools, undo, profile test). Full-size: `src/features/agent/` in [mindoodb-app-todomanager](https://github.com/klehmann/mindoodb-app-todomanager) (search, undo/redo/history, directory lookup, agent profile). Both are open source; copy from them.
+
+#### Testing agent tools
+
+- **Unit**: call `execute` directly with a database from `createMockMindooDBAppSession`.
+- **End to end**: `createFakeBridgeHost({ agentToolPrefix, agentToolsEnabled, agentConsent })` connects the real bridge; `host.agent.tools()`, `host.agent.context()` and `host.agent.call(name, input)` act as the agent, and `call` answers `{ ok, result }` or `{ ok: false, error }`; `agentConsent: "deny"` plays a user who declines a `consequentialHint` call (`NOT_ALLOWED`).
+- **In the browser**: the `/__haven-test/` page (`mountHavenTestHost`) lists the tools with a call button. Pass `agentToolPrefix: definition.agentToolPrefix`; without it the page derives the prefix from the app id, so the names differ from Haven's.
+
+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
 
@@ -740,6 +760,30 @@ answers like a current Haven, so the SDK frames that URL in the container. Both
 controllers simulate unsaved changes: `setEmbedDirty`, `failNextEmbedSave`, and for an
 app under test that is a component, `getEmbeddingDirty` and `requestEmbeddingSave`.
 
+**Host checklist.** What a host needs beyond the calls above (the "Embedded editors" tab of
+[mindoodb-app-example](https://github.com/klehmann/mindoodb-app-example) is a small
+complete host, `src/app/useEmbedsSection.ts`):
+
+- `embeds.open` rejects with an `Error` whose `name` says why: `declined` (the user said
+  no), `component-not-found` (the app is not installed or no longer offers it),
+  `forbidden`, `database-not-found`, `document-not-found`, `invalid-request`,
+  `unsupported` (a Haven without components). Explain these to the user.
+- `requestAccess` never asks again for what the user put off; Haven asks for it when the
+  document is opened. So say "Haven asks when you open one" instead of offering "ask again".
+- `createFields` may contain nested values; copy it with a JSON round trip, not
+  `structuredClone`, when the component sits in Vue reactive state.
+- Keep fields of your own on the root top-level and prefixed (`exampleEditor`), so
+  queries find them without `setSummarySetup`; nested fields (`crm.folders`) need a summary
+  setup first.
+- Copy the component's `children` link onto the root (or remember it) so you can still
+  delete a document with all its children after the providing app was uninstalled.
+- Keep the container mounted while the editor should live: removing the element (a tab
+  rendered with `v-if`) closes the editor. Hide it with `v-show` and
+  `embed.setVisible(false)` instead.
+- With `placement === "overlay"` the SDK follows the container on resize and scroll, not
+  when content above it changes height; keep banners and confirm bars out of the space
+  above an open editor.
+
 A host with agent tools marks the component in the front tab with `embed.setActive()`
 and reads `embed.agentTools`; see *Agent tools of embedded components*.
 
@@ -1065,7 +1109,7 @@ An id in `dependencyIds` may name a revision the timeline does not list, because
 
 ### Granular JSON edits
 
-When you need to edit nested objects or lists inside a document — not just top-level fields — describe the change as a **granular JSON patch** rather than rewriting the whole document. This is the model behind structured collaborative editing in apps like [`mindoodb-app-teamgrid`](https://github.com/klehmann/mindoodb-app-teamgrid), where two users can insert different rows into the same worksheet on different devices and the merge keeps both sides cleanly.
+When you need to edit nested objects or lists inside a document — not just top-level fields — describe the change as a **granular JSON patch** rather than rewriting the whole document. This is the model behind structured collaborative editing in apps like TeamGrid, where two users can insert different rows into the same worksheet on different devices and the merge keeps both sides cleanly.
 
 A JSON patch is a bag of four operation kinds applied at specific JSON paths inside `document.data`, all carried with the document version (`baseHeads`) the app was looking at when it composed them:
 
@@ -1366,11 +1410,11 @@ Buffer API at a glance:
 
 #### End-to-end sample
 
-The [`mindoodb-app-teamedit`](https://github.com/klehmann/mindoodb-app-teamedit) sample wires `MindooDBTextBuffer` to a Milkdown markdown editor with Save / Refresh / preview pane, and is the recommended starting point for building your own collaborative text app.
+TeamEdit wires `MindooDBTextBuffer` to a Milkdown markdown editor with Save / Refresh / preview pane; its code is not public, so build on the snippets above.
 
 ### Collaborative rich-text editing
 
-For structured documents that need formatting — headings, bold/italic runs, lists, tables, fonts, colors — use the **rich-text patch API**. This is the surface behind the Word/.docx mode in [`mindoodb-app-teamedit`](https://github.com/klehmann/mindoodb-app-teamedit), where two users can edit the same document at the same time and Haven merges both formatting and structure on its side via Automerge's rich-text CRDT.
+For structured documents that need formatting — headings, bold/italic runs, lists, tables, fonts, colors — use the **rich-text patch API**. This is the surface behind TeamEdit's Word/.docx mode, where two users can edit the same document at the same time and Haven merges both formatting and structure on its side via Automerge's rich-text CRDT.
 
 Rich-text fields are stored internally as Automerge rich-text, but apps never see Automerge directly. The bridge speaks JSON and represents a rich-text field as an ordered list of **spans** — text runs with marks for inline formatting, plus block markers for paragraphs, headings, lists, and tables:
 
@@ -1480,7 +1524,7 @@ Like the text buffer, the rich-text handle always sends the original `baseHeads`
 
 #### End-to-end sample
 
-The Word/.docx mode in [`mindoodb-app-teamedit`](https://github.com/klehmann/mindoodb-app-teamedit) is the **only supported in-repo use case** for the Automerge binary sync API below — it needs a local replica and binary flush because `set`/`unset` and the JSON patch APIs are not sufficient for that editor. For span-only rich-text apps, use `createMindooDBRichTextHandle` instead.
+TeamEdit's Word/.docx mode is the **only supported in-repo use case** for the Automerge binary sync API below — it needs a local replica and binary flush because `set`/`unset` and the JSON patch APIs are not sufficient for that editor. For span-only rich-text apps, use `createMindooDBRichTextHandle` instead.
 
 ### Automerge binary sync (advanced)
 
@@ -1589,7 +1633,7 @@ Requires the `update` capability (same as other write operations). For historica
 
 #### Reference implementation (not a template)
 
-TeamEdit's Word/.docx mode is why these RPCs exist — see `wordAutomergeHandle.ts` in [`mindoodb-app-teamedit`](https://github.com/klehmann/mindoodb-app-teamedit). Treat it as a reference for an unsupported edge case, not as a pattern to copy into new apps.
+TeamEdit's Word/.docx mode is why these RPCs exist. Treat them as an unsupported edge case, not as a pattern for new apps.
 
 ### Queries & Live Queries
 

package/dist/index.js

@@ -1,3 +1,13 @@
+import {
+  MINDOODB_APP_BUNDLE_ARCHIVE_FILE_NAME,
+  MINDOODB_APP_BUNDLE_MANIFEST_FILE_NAME,
+  MINDOODB_APP_BUNDLE_MANIFEST_FORMAT,
+  MINDOODB_APP_BUNDLE_MANIFEST_VERSION,
+  buildMindooDBAppBundleContentHashInput,
+  isMindooDBAppBundleHash,
+  normalizeMindooDBAppBundlePath,
+  validateMindooDBAppBundleManifest
+} from "./chunk-LT4FK6LU.js";
 import {
   DEFAULT_DRAG_LONG_PRESS_MS,
   DEFAULT_DRAG_POINTER_THRESHOLD_PX,
@@ -88,16 +98,6 @@ import {
   validateMindooDBAppComponents,
   validateMindooDBAppDefinition
 } from "./chunk-FKTNDDWB.js";
-import {
-  MINDOODB_APP_BUNDLE_ARCHIVE_FILE_NAME,
-  MINDOODB_APP_BUNDLE_MANIFEST_FILE_NAME,
-  MINDOODB_APP_BUNDLE_MANIFEST_FORMAT,
-  MINDOODB_APP_BUNDLE_MANIFEST_VERSION,
-  buildMindooDBAppBundleContentHashInput,
-  isMindooDBAppBundleHash,
-  normalizeMindooDBAppBundlePath,
-  validateMindooDBAppBundleManifest
-} from "./chunk-LT4FK6LU.js";
 
 // src/types.ts
 var MINDOODB_APP_WELL_KNOWN_DRAG_TYPES = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindoodb-app-sdk",
-  "version": "0.0.73",
+  "version": "0.0.74",
   "engines": {
     "node": ">=22.13.0"
   },