mindoodb-app-sdk 0.0.65 → 0.0.67

package/README.md

@@ -327,10 +327,79 @@ if (session.agent) {
 - **`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`.
+- **`scope`**: `"app"` (default) for the app's own operations ("list documents", "create a map"), `"document"` for operations on the document it shows ("write this paragraph", "set these cells"). See *Agent tools of embedded components* below.
 - **`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.
 
+#### An op guide for edit tools
+
+Apps with an edit language (`apply_ops` batches, formatting changes) do better with short tool descriptions plus a reference the agent loads when it needs it. `createAgentGuideTool` builds that reference as a read-only tool (`ops_guide` by default): without arguments it returns the group list and one signature line per op; with `groups` it returns field tables, units, JSON examples and common mistakes of those groups.
+
+```ts
+import { agentGuideExamples, createAgentGuideTool, type MindooDBAppAgentGuideGroup } from "mindoodb-app-sdk";
+
+const GUIDE: MindooDBAppAgentGuideGroup[] = [
+  {
+    name: "blocks",
+    summary: "insert, replace, move and delete blocks",
+    intro: "Block indexes come from todo_document_read and refer to the document before the call.",
+    ops: [
+      {
+        name: "insertContent",
+        signature: "{after, markdown}",
+        fields: [
+          { name: "after", type: "integer | {heading}", required: true, description: "-1 = document start" },
+          { name: "markdown", type: "string", required: true, description: "One or more blocks." },
+        ],
+        examples: [{ op: "insertContent", after: -1, markdown: "# Agenda" }],
+      },
+    ],
+    mistakes: ["Sending indexes from an old read: pass the revision, read again when refused."],
+  },
+];
+
+const tools = [
+  createAgentGuideTool({ documents: "todo_apply_ops", groups: GUIDE }),
+  // apply_ops' description: "... Signatures and examples: todo_ops_guide."
+];
+```
+
+A group can also bring its reference as ready Markdown in `content` (TeamSlides passes GenOffice's op docs). Test the examples: `agentGuideExamples(GUIDE)` lists them, so a unit test can dry-run each one through the edit tool.
+
+#### Agent tools of embedded components
+
+Agents work on three levels: Haven's own tools (`haven_*`), the tools of the app the
+user has open, and the tools of the components that app embeds. A host such as Mindoo
+CRM offers the *workbench*: finding, creating, filing, opening and closing documents.
+The embedded editors offer the *content* of the one document each shows.
+
+- **Embedded, an app offers only its `scope: "document"` tools.** It sees just its
+  sandbox, so "list documents" or "create a document" would mislead; the host has its
+  own tools for those. Register the same tool list either way; Haven drops the rest.
+- **One component per app is active.** When a host shows two documents of the same
+  app (two text documents side by side), the app's tool names belong to the active one:
+  the newest, until the host calls `embed.setActive()`, e.g. when a tab comes to the
+  front. Components of different apps (a spreadsheet next to a text) all keep theirs.
+  Haven prefers the launch in the focused app, so a component in the CRM wins over the
+  same app running in a background tab.
+- **The host learns about its components' tools**: `embed.agentTools` is
+  `{ prefix, names, active, enabled }` or `null`, `embed.onAgentToolsChange` follows it,
+  and `embed.waitForAgentTools(timeoutMs)` resolves once the component offers tools.
+  A host's "open document" tool can wait for it and tell the agent which tools to use
+  next:
+
+```ts
+const embed = await session.embeds.open({ componentKey, databaseId, docId, container });
+await embed.setActive();
+const tools = await embed.waitForAgentTools(5000);
+return { docKey, editorTools: tools ? { prefix: tools.prefix, names: tools.names } : null };
+```
+
+In tests, `host.setEmbedAgentTools(embedId, ["text_insert"])` acts as if the component
+registered tools, and an app under test launched with `launchContext.embed` offers only
+its document tools, as in Haven.
+
 `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
@@ -426,6 +495,39 @@ await session.embedding.complete({ title }); // or session.embedding.cancel()
 Haven writes every change back to the host's database as it happens and only lets the
 component create documents that are children of the root.
 
+**Kinds, contracts and references.** Three optional fields let hosts pick components by
+what they do instead of by app:
+
+```json
+{
+  "id": "person",
+  "label": { "en": "Person", "de": "Person" },
+  "intents": ["create", "edit", "view"],
+  "match": { "form": "contactperson" },
+  "category": "form",
+  "provides": [{ "contract": "mindoo.contacts.person@1", "fields": { "parents": "companyIds" } }],
+  "references": [
+    { "field": "companyIds", "to": "mindoo.contacts.company@1", "match": { "form": "contactcompany" }, "show": ["subject"] }
+  ]
+}
+```
+
+- `category`: `editor` (content: a document, a spreadsheet, a map) or `form` (a record: a
+  company, a person); hosts may treat a component without one as an `editor`. A CRM
+  offers its editors under "New" and uses its forms elsewhere.
+- `provides`: contracts the root documents fulfil (`<name>@<major version>`), so a host
+  can rely on their shape; `fields` maps contract fields to this app's field names.
+  Another app offering the same contract can take this one's place.
+- `references`: fields that point at other root documents (not parts, unlike
+  `children`), e.g. a person's company. Embedded, the component cannot see the host's
+  database, so it asks Haven:
+
+```ts
+const companies = await session.embedding.lookup("companyIds", { query: "Mül" });
+// [{ docId, fields: { subject } }]: only documents matching the reference's `match`,
+// only its `show` fields. `docIds: [...]` fetches given ones (to show the current value).
+```
+
 **Embedding a component** (host app):
 
 ```ts
@@ -447,6 +549,25 @@ hands its connection to Haven, so the host cannot reach into the component or it
 channel. Haven tells the SDK where the container is (for the component's own menus);
 the SDK follows the container's size and position by itself.
 
+**Asking once.** The first time a host shows a component in one of its databases,
+Haven asks the user whether that app may see the document. A host that shows several
+components asks for all of them at once instead, e.g. right after `components.list`:
+
+```ts
+const { granted, pending } = await session.embeds.requestAccess({
+  components: [
+    { componentKey: sheet.key, databaseIds: ["crm"] },
+    { componentKey: person.key, databaseIds: ["contacts"] }, // default: all its databases
+  ],
+});
+```
+
+Haven lists what is not allowed yet in one dialog; the user may untick entries. What the
+user allowed or put off before is not asked again, so call it on every start. `open`
+still asks for a pending pair when it is used, and asks again when a newer version of
+the component wants more access (e.g. new `references`). In tests, `embedAccess` on the
+mock plays the user (default: allow all).
+
 **Unsaved changes.** A component reports whether it has changes it has not saved yet,
 and saves when its host asks:
 
@@ -485,6 +606,9 @@ 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`.
 
+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*.
+
 ### Databases and capabilities
 
 Each database mapped to your app carries a set of **capabilities** that Haven controls. Your app should check capabilities before attempting operations and adapt its UI accordingly.

package/TESTING.md

@@ -104,11 +104,12 @@ Each database entry can provide:
 - `info`
 - `documents` — seed documents into the mock store (used by `list`/`query` and by evaluating VirtualViews). A seed's `decryptionKeyId` is reported back by `documents.get`, like a real host; documents created through the mock report `"default"` unless `create` named a key, and person-encrypted documents (`recipients`) report none.
 - `methods.documents`
+- Document history: every write (create, update, delete, a remote update) is kept as a revision, so `listHistory` (newest first, `isCurrent` on the latest), `getAtRevision` (with `phase: "before"`) and `getAtTimestamp` return the states the document went through. Revision ids are `<docId>@<n>`; timestamps are the write's `updatedAt`, strictly increasing per document.
 - `methods.views` for session-level `createView()` and `openView()` calls (overrides the default evaluating navigator)
 - `methods.attachments`
 - `fulltextSetup` — the initial config returned by `db.getFulltextSetup()`; `db.setFulltextSetup()` overwrites it for the lifetime of the handle. Use this to test your app's full-text bootstrap logic. Note the mock evaluates `text` query clauses regardless of this config.
 - `summarySetup` — the initial config returned by `db.getSummarySetup()`; `db.setSummarySetup()` overwrites it for the lifetime of the handle. The mock's `query()` reads seeded documents directly and ignores this config; use it to test your app's summary bootstrap logic.
-- `automerge: true` — back every document with a real Automerge document, as Haven does (off by default: plain JSON with `mock-head-N` heads). `create`/`update` then return real Automerge heads, `update` applies `set`/`unset`, `json` (with `Automerge.changeAt(json.baseHeads)` when given) and `text` patches as Automerge changes with Haven's rules (missing parents and lists are created, `unset` is idempotent, `counterIncrement` needs a counter, an empty `json` patch is rejected), and `get`/`list`/`query` return the plain projection (atomic strings as strings, counters as numbers, timestamps as ISO strings). `richText` snapshots replace the value at their path and `richTextSteps` are spliced into the text without marks. Seeds are built with a fixed actor, so two mocks from the same seed have identical heads. `mockDatabasesFromDefinition(definition, seed, { automerge: true })` and the test host URL setting `automerge=1` turn it on, too.
+- `automerge: true` — back every document with a real Automerge document, as Haven does (off by default: plain JSON with `mock-head-N` heads). `create`/`update` then return real Automerge heads, `update` applies `set`/`unset`, `json` (with `Automerge.changeAt(json.baseHeads)` when given) and `text` patches as Automerge changes with Haven's rules (missing parents and lists are created, `unset` is idempotent, `counterIncrement` needs a counter, an empty `json` patch is rejected), and `get`/`list`/`query` return the plain projection (atomic strings as strings, counters as numbers, timestamps as ISO strings). `richText` patches run Automerge's `updateSpans` at their `baseHeads` and `richTextSteps` splice and mark at theirs, both validated and with MindooDB's recovery, and `getRichText` returns `Automerge.spans` — so values Automerge rejects (an `immutableString` as a mark value) fail here as they do in Haven. A `richText` snapshot written at older `baseHeads` is applied on a fork at those heads and merged back, as MindooDB does (Automerge 3.5's `updateSpans` inside `changeAt` indexes the current text), so a concurrent edit of the same text survives. As in MindooDB's `applyDocumentUpdate`, all parts of one `update` whose `baseHeads` agree are applied as one Automerge change (one history entry), all or nothing. Seeds are built with a fixed actor, so two mocks from the same seed have identical heads. `mockDatabasesFromDefinition(definition, seed, { automerge: true })` and the test host URL setting `automerge=1` turn it on, too.
 
 #### Concurrent edits from another device
 
@@ -179,6 +180,24 @@ const page = await navigator.entriesForward({ limit: 100 });
 Without `mindoodb`, the testing entrypoint falls back to an empty navigator and
 logs a warning — install the peer for realistic view tests.
 
+Views configured for the app in Haven arrive in `launchContext.views`. Pass
+them there and `session.openViewNavigator(viewId, options)` evaluates them
+over their source databases' seeded documents, compiled the way Haven does
+(rule or formula filter, field or formula columns). Each call opens a
+navigator of its own with its options applied (`rootCategoryPath`,
+`includeCategories`, `includeDocuments`, …), as in Haven; disposing one does
+not affect the others. A view created with `createViewNavigator` can be
+opened again by its definition id the same way.
+
+```ts
+const mock = createMockMindooDBAppBridge({
+  launchContext: { views: [contactsByCompany] }, // a MindooDBAppResolvedViewDefinition
+  databases: [{ info: { id: "main", title: "Main", capabilities: ["read", "views"] }, documents: contacts }],
+});
+const session = await mock.bridge.connect();
+const acme = await session.openViewNavigator("contacts_by_company", { rootCategoryPath: ["ACME"] });
+```
+
 The default in-memory document store also implements `documents.query()` and `documents.liveQuery()`: expression and formula-string filters are evaluated against the seeded documents, `sortBy`/`limit`/`offset` work as documented, and live query callbacks fire automatically after `create`/`update`/`delete`/`undelete` mutations. Full-text `text` clauses are supported with a deterministic mock implementation (token matching with prefix/AND semantics and an occurrence-count `textScore`) — assert on membership and relative ordering, not absolute scores, since real hosts use a BM25-style engine. That means app code built on queries and live queries is testable at Level 1 without any extra setup:
 
 ```ts
@@ -422,6 +441,25 @@ Lower-level pieces, if you build your own page: `createBrowserTestHost({ frame,
 
 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.
 
+### Two users on two replicas
+
+The panel's **Mode** section switches between *Single user* and *Two users* (keeping the other URL settings). `/__haven-test/?twoUsers=1` (or `mountHavenTestHost({ twoUsers: true })`) shows the app twice, side by side, as two people on two devices: each frame is launched by its own mock Haven with its own replica of every database (`automerge: true`, distinct Automerge actors), so their edits really are concurrent. The bar on top:
+
+- **Auto-sync every 2 s** (on by default) merges the replicas with `syncMockReplicas`, like Haven's sync. Turn it off to keep the two apart — two devices offline — edit on both sides, then press **Sync** and watch the merge.
+- The status says "✓ in sync" or how many documents still differ.
+
+Each app sees the other's changes the way it would in Haven (changefeed, live queries, or its own polling). Use it to try "one changes the text, the other the color", "both add a slide", "both format the same word" by hand. Playwright reaches both frames as `[data-testid="haven-two-users-frame-1"]` / `-2`, and `window.__havenTwoUsers` scripts the mode (`sync()`, `setAutoSync(on)`, `differences()`, `hosts`).
+
+In Vitest, two mocks with distinct `automergeActor`s plus `syncMockReplicas(a, b)` do the same without a browser:
+
+```ts
+const a = createMockMindooDBAppSession({ databases: [def()], automergeActor: "a1".repeat(16) });
+const b = createMockMindooDBAppSession({ databases: [def()], automergeActor: "b2".repeat(16) });
+// … edit through each session, then:
+await syncMockReplicas(a, b); // documents, deletions and attachments, both ways
+expect(mockReplicaDifferences(a, b)).toBe(0);
+```
+
 ## When to use which level
 
 Choose Level 1 when:

package/dist/{chunk-BE7LLFFE.js → chunk-376SABPG.js}

@@ -363,6 +363,89 @@ function readComponentFieldMatch(value, label, errors) {
   }
   return result;
 }
+var COMPONENT_CATEGORY_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;
+var MINDOODB_APP_COMPONENT_CONTRACT_PATTERN = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+@[1-9][0-9]{0,3}$/;
+var COMPONENT_CONTRACTS_MAX = 8;
+var COMPONENT_REFERENCES_MAX = 8;
+var COMPONENT_REFERENCE_SHOW_MAX = 8;
+function readComponentContracts(value, label, errors) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (!Array.isArray(value) || value.length > COMPONENT_CONTRACTS_MAX) {
+    errors.push(`${label} must be an array of at most ${COMPONENT_CONTRACTS_MAX} contracts.`);
+    return void 0;
+  }
+  const result = [];
+  for (const [index, entry] of value.entries()) {
+    const contract = isPlainObject(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)) {
+        errors.push(`${label}[${index}].fields must map contract fields to document fields.`);
+        return void 0;
+      }
+      fields = {};
+      for (const [from, to] of Object.entries(entry.fields)) {
+        if (!COMPONENT_FIELD_PATTERN.test(from) || typeof to !== "string" || !COMPONENT_FIELD_PATTERN.test(to)) {
+          errors.push(`${label}[${index}].fields must map field names to top-level field names.`);
+          return void 0;
+        }
+        fields[from] = to;
+      }
+    }
+    result.push({ contract, ...fields && Object.keys(fields).length ? { fields } : {} });
+  }
+  return result.length ? result : void 0;
+}
+function readComponentReferences(value, label, rootMatch, errors) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (!Array.isArray(value) || value.length > COMPONENT_REFERENCES_MAX) {
+    errors.push(`${label} must be an array of at most ${COMPONENT_REFERENCES_MAX} references.`);
+    return void 0;
+  }
+  const result = [];
+  const fieldsSeen = /* @__PURE__ */ new Set();
+  for (const [index, entry] of value.entries()) {
+    const at = `${label}[${index}]`;
+    if (!isPlainObject(entry)) {
+      errors.push(`${at} must be an object.`);
+      return void 0;
+    }
+    const field = typeof entry.field === "string" ? entry.field.trim() : "";
+    if (!COMPONENT_FIELD_PATTERN.test(field) || field in rootMatch || fieldsSeen.has(field)) {
+      errors.push(`${at}.field must be a top-level field name, not a match field and not used twice.`);
+      return void 0;
+    }
+    fieldsSeen.add(field);
+    const to = typeof entry.to === "string" ? entry.to.trim() : void 0;
+    if (entry.to !== void 0 && !MINDOODB_APP_COMPONENT_CONTRACT_PATTERN.test(to ?? "")) {
+      errors.push(`${at}.to must look like "mindoo.contacts.company@1".`);
+      return void 0;
+    }
+    const match = readComponentFieldMatch(entry.match, `${at}.match`, errors);
+    if (!match) {
+      return void 0;
+    }
+    if (!Object.keys(match).length) {
+      errors.push(`${at}.match must name at least one field, or every document could be referenced.`);
+      return void 0;
+    }
+    const show = Array.isArray(entry.show) ? entry.show.filter((name) => typeof name === "string" && COMPONENT_FIELD_PATTERN.test(name)) : [];
+    if (!show.length || show.length !== entry.show.length || show.length > COMPONENT_REFERENCE_SHOW_MAX) {
+      errors.push(`${at}.show must list 1-${COMPONENT_REFERENCE_SHOW_MAX} top-level field names.`);
+      return void 0;
+    }
+    result.push({ field, ...to ? { to } : {}, match, show: [...new Set(show)] });
+  }
+  return result.length ? result : void 0;
+}
 function readComponents(value, errors) {
   if (value === void 0 || value === null) {
     return void 0;
@@ -475,6 +558,16 @@ function readComponents(value, errors) {
       }
       children = { linkField, ...childMatch && Object.keys(childMatch).length ? { match: childMatch } : {} };
     }
+    let category;
+    if (entry.category !== void 0) {
+      category = typeof entry.category === "string" ? entry.category.trim() : "";
+      if (!COMPONENT_CATEGORY_PATTERN.test(category)) {
+        errors.push(`${label}.category must be 1-32 lowercase letters, digits or "-", e.g. "editor" or "form".`);
+        return;
+      }
+    }
+    const provides = readComponentContracts(entry.provides, `${label}.provides`, errors);
+    const references = readComponentReferences(entry.references, `${label}.references`, match, errors);
     if (errors.length !== errorCount) {
       return;
     }
@@ -486,7 +579,10 @@ function readComponents(value, errors) {
       intents,
       match,
       ...create ? { create } : {},
-      ...children ? { children } : {}
+      ...children ? { children } : {},
+      ...category ? { category } : {},
+      ...provides ? { provides } : {},
+      ...references ? { references } : {}
     });
   });
   return result.length ? result : void 0;
@@ -1174,7 +1270,8 @@ var MindooDBAppAgentApiImpl = class {
         name: tool.name,
         description: tool.description,
         inputSchema: toJson(tool.inputSchema),
-        ...tool.annotations ? { annotations: { ...tool.annotations } } : {}
+        ...tool.annotations ? { annotations: { ...tool.annotations } } : {},
+        ...tool.scope ? { scope: tool.scope } : {}
       }))
     });
   }
@@ -1438,6 +1535,8 @@ var MindooDBAppEmbedImpl = class {
   dirtyListeners = /* @__PURE__ */ new Set();
   dirtyState = void 0;
   tracker = null;
+  toolsState = null;
+  toolsListeners = /* @__PURE__ */ new Set();
   get placement() {
     return this.frame ? "frame" : "overlay";
   }
@@ -1470,6 +1569,56 @@ var MindooDBAppEmbedImpl = class {
     }
     await this.rpc.call("embeds.save", { embedId: this.embedId });
   }
+  async setActive() {
+    if (this.closedEvent) {
+      return;
+    }
+    await this.rpc.call("embeds.setActive", { embedId: this.embedId });
+  }
+  get agentTools() {
+    return this.toolsState;
+  }
+  onAgentToolsChange(listener) {
+    this.toolsListeners.add(listener);
+    return () => {
+      this.toolsListeners.delete(listener);
+    };
+  }
+  /** Haven reported the component's agent tools. */
+  setAgentToolsState(tools) {
+    if (this.closedEvent) {
+      return;
+    }
+    this.toolsState = tools ? { ...tools, names: [...tools.names] } : null;
+    this.toolsListeners.forEach((listener) => {
+      try {
+        listener(this.toolsState);
+      } catch (error) {
+        console.error("MindooDB embed agent tools listener failed.", error);
+      }
+    });
+  }
+  waitForAgentTools(timeoutMs = 1e4) {
+    if (this.toolsState?.names.length) {
+      return Promise.resolve(this.toolsState);
+    }
+    if (this.closedEvent) {
+      return Promise.resolve(null);
+    }
+    return new Promise((resolve) => {
+      const finish = (tools) => {
+        clearTimeout(timer);
+        stopTools();
+        stopClosed();
+        resolve(tools);
+      };
+      const timer = setTimeout(() => finish(null), timeoutMs);
+      const stopTools = this.onAgentToolsChange((tools) => {
+        if (tools?.names.length) finish(tools);
+      });
+      const stopClosed = this.onClosed(() => finish(null));
+    });
+  }
   async setRect(rect) {
     if (this.closedEvent) {
       return;
@@ -1524,6 +1673,15 @@ var MindooDBAppEmbedImpl = class {
     });
     this.listeners.clear();
     this.dirtyListeners.clear();
+    this.toolsState = null;
+    this.toolsListeners.forEach((listener) => {
+      try {
+        listener(null);
+      } catch (error) {
+        console.error("MindooDB embed agent tools listener failed.", error);
+      }
+    });
+    this.toolsListeners.clear();
   }
 };
 var MindooDBAppEmbedsClient = class {
@@ -1547,6 +1705,16 @@ var MindooDBAppEmbedsClient = class {
         }
         return;
       }
+      if (message.event?.type === "agentTools") {
+        const { embedId, agentTools } = message.event;
+        const embed2 = this.open.get(embedId);
+        if (embed2) {
+          embed2.setAgentToolsState(agentTools ?? null);
+        } else {
+          this.earlyTools.set(embedId, agentTools ?? null);
+        }
+        return;
+      }
       if (message.event?.type !== "closed") {
         return;
       }
@@ -1591,6 +1759,10 @@ var MindooDBAppEmbedsClient = class {
           this.earlyDirty.delete(embed.embedId);
           embed.setDirtyState(earlyDirty);
         }
+        if (this.earlyTools.has(embed.embedId)) {
+          embed.setAgentToolsState(this.earlyTools.get(embed.embedId) ?? null);
+          this.earlyTools.delete(embed.embedId);
+        }
         const early = this.early.get(embed.embedId);
         if (early) {
           this.early.delete(embed.embedId);
@@ -1599,6 +1771,29 @@ var MindooDBAppEmbedsClient = class {
           this.open.set(embed.embedId, embed);
         }
         return embed;
+      },
+      requestAccess: async (input) => {
+        const components = (input?.components ?? []).map((entry) => ({
+          componentKey: String(entry.componentKey),
+          ...entry.databaseIds ? { databaseIds: entry.databaseIds.map(String) } : {},
+          ...entry.intent === "view" ? { intent: "view" } : {}
+        }));
+        try {
+          const response = await this.rpc.call("embeds.requestAccess", {
+            input: { components }
+          });
+          return { granted: response?.granted ?? [], pending: response?.pending ?? [] };
+        } catch (error) {
+          if (!(error instanceof Error && error.name === "method-not-found")) {
+            throw error;
+          }
+          return {
+            granted: [],
+            pending: components.flatMap(
+              (entry) => (entry.databaseIds ?? []).map((databaseId) => ({ componentKey: entry.componentKey, databaseId }))
+            )
+          };
+        }
       }
     };
     this.embedding = {
@@ -1617,6 +1812,15 @@ var MindooDBAppEmbedsClient = class {
       setDirty: async (dirty) => {
         await this.rpc.call("embedding.setDirty", { dirty: dirty === true });
       },
+      lookup: async (field, options) => {
+        const result = await this.rpc.call("embedding.lookup", {
+          field: String(field),
+          ...options?.query ? { query: String(options.query) } : {},
+          ...options?.docIds ? { docIds: options.docIds.map(String) } : {},
+          ...options?.limit ? { limit: Number(options.limit) } : {}
+        });
+        return Array.isArray(result) ? result : [];
+      },
       onSaveRequest: (handler) => {
         this.saveHandler = handler;
         return () => {
@@ -1635,6 +1839,7 @@ var MindooDBAppEmbedsClient = class {
   /** Events that arrived before `embeds.open` resolved with their id. */
   early = /* @__PURE__ */ new Map();
   earlyDirty = /* @__PURE__ */ new Map();
+  earlyTools = /* @__PURE__ */ new Map();
   stopListening;
   /** This app as a component: what to do when its host asks it to save. */
   saveHandler = null;
@@ -3370,6 +3575,7 @@ export {
   validateMindooDBAppAccepts,
   mindooDBAppAcceptMatchesType,
   MINDOODB_APP_COMPONENTS_MAX,
+  MINDOODB_APP_COMPONENT_CONTRACT_PATTERN,
   validateMindooDBAppComponents,
   mindooDBAppComponentFieldsMatch,
   resolveMindooDBAppLocalizedText,