@matterfact/embed 0.8.0 → 0.10.0

package/README.md

@@ -92,6 +92,132 @@ Script-tag / non-React hosts can use the iframe directly (the Share dialog shows
 ></iframe>
 ```
 
+## Linking your app's matterfact content
+
+A co-embedded `<MatterfactArtifact>` (above) is found automatically. But your app may
+render matterfact content another way — a report/dossier you pulled from matterfact and
+render yourself, or artifacts spread across many routes. Tell the agent where that content
+lives with a **site map**: your routes, each tagged with what kind of matterfact content
+it carries. The agent uses it to reason about — and navigate toward — content the user
+isn't currently looking at.
+
+```tsx
+<MatterfactAgent
+  sitemap={[
+    {
+      path: '/company/:ticker/dossier',
+      label: 'Company Dossier',
+      content: { kind: 'mf-document', doctype: 'company_dossier' },
+    },
+    {
+      path: '/talent/exec-departures',
+      label: 'Exec Departures',
+      content: { kind: 'mf-artifact', slug: 'exec-departure-tracker' },
+    },
+    { path: '/screener', label: 'Screener', content: { kind: 'host-data' } },
+  ]}
+/>
+```
+
+```js
+// script tag — same shape
+window.matterfact = {
+  sitemap: [
+    /* … */
+  ],
+};
+```
+
+Each entry is **classification only** — a route pattern, a label, and a `content` tag:
+
+- `{ kind: 'mf-artifact', slug }` — a matterfact artifact rendered on that route.
+- `{ kind: 'mf-document', doctype }` — a matterfact document/report (dossier, etc.).
+- `{ kind: 'host-data' }` — your own data; not matterfact content.
+
+**Never put a capability token in the site map.** It is app-wide and rides on every turn;
+the concrete artifact/document on the _current_ page arrives separately (the live artifact
+iframe, or per-page context — see below), where the token belongs.
+
+### Documents on the current page
+
+For a matterfact **document** the user is looking at, hand the agent its id via page
+context (the same `context.entities` you already declare — see _What the agent can see_):
+
+```tsx
+<MatterfactAgent
+  getPageContext={() => ({
+    route: '/company/:ticker/dossier',
+    entities: [
+      {
+        kind: 'document',
+        id: currentDoc.mfDocId, // the matterfact MF_DOC_ID
+        label: currentDoc.title,
+        data: { href: location.href }, // optional: enables the panel's "open on page" deeplink
+      },
+    ],
+  })}
+/>
+```
+
+The agent can then cite the document inline as a chip; clicking it opens a read-only viewer
+in the widget (authorized by the signed-in user's own matterfact access — no token), with an
+optional **Open on page** deeplink back to your route. matterfact resolves the document from
+its own systems by `MF_DOC_ID`; it never reads your database.
+
+### Content the user _isn't_ looking at
+
+The site map tells the agent a route _carries_ matterfact content; the two props below let it
+actually **reach** that content from anywhere, without the user navigating there first.
+
+**Boards on any route — `artifacts`.** Declare your matterfact artifacts once and the agent
+can open any of them from any page, even routes where you don't embed the `<MatterfactArtifact>`
+iframe:
+
+```tsx
+<MatterfactAgent
+  artifacts={[
+    { slug: 'exec-departure-tracker', owner: 'you@firm.com', token: '…', label: 'Talent Bank' },
+    { slug: 'global-datacenter-buildout', owner: 'you@firm.com', token: '…', label: 'Data Centers' },
+  ]}
+/>
+```
+
+```js
+// script tag — same shape
+window.matterfact = { artifacts: [{ slug: '…', owner: '…', token: '…', label: '…' }] };
+```
+
+This replaces the old workaround of mounting hidden, zero-size `<MatterfactArtifact>` iframes
+just to make a board's grant reachable. The `token` stays in this host-page config and in the
+grant channel — it never enters the chat transcript or reaches the model.
+
+**A resolver for content you look up per-request — `resolve`.** When your set of documents or
+boards is per-user or per-ticker (too large to declare), give the agent a function that turns a
+classification into a concrete reference. matterfact defines the tool contract (name, arguments,
+result shape, and how the agent uses it — so it costs you no agent-instruction budget); you
+supply the implementation:
+
+```tsx
+<MatterfactAgent
+  resolve={{
+    // doctype + a key (e.g. a ticker) -> the matterfact document id, from YOUR lookup.
+    document: async ({ doctype, key }) => {
+      const row = await myHub.lookup(doctype, key);
+      return { id: row.MF_DOC_ID, label: `${key} ${doctype}`, href: hrefFor(doctype, key) };
+    },
+    // a slug -> a read grant, when you resolve boards dynamically instead of declaring them.
+    artifact: async ({ slug }) => myHub.artifactGrant(slug),
+  }}
+/>
+```
+
+The agent calls `mf.resolveDocument` / `mf.resolveArtifact` when the site map shows the content
+lives on another route, gets back an id (and, for a document, an optional `href` deeplink), and
+cites it as a chip — exactly as for on-page content. **matterfact never queries your data**: your
+function runs the lookup, matterfact only ever receives the id it returns. `resolve` is a host
+tool (see [Host tools](#host-tools)), so your app's `host_tools` policy must allow `mf.*` — it
+does by default.
+
 ## Signing users in
 
 By default the widget runs its own sign-in in a popup (the only way an embedded frame can
@@ -310,6 +436,71 @@ Everything else about page observation still applies here: values are redacted b
 leaves the page, row counts are capped, and `pageContext={false}` turns this off along with
 everything else (see above).
 
+## Host tools
+
+`hoist.navigate` above is one instance of a general mechanism: **the host page can offer the
+agent tools to call**. There are three kinds, distinguished by who owns the contract and who
+runs the code:
+
+| Prefix     | Contract   | Runs where          | Examples                                         |
+| ---------- | ---------- | ------------------- | ------------------------------------------------ |
+| `hoist.*`  | matterfact | the widget's adapter | `hoist.navigate` (above)                          |
+| `mf.*`     | matterfact | **your** function    | `mf.resolveDocument`, `mf.resolveArtifact` (above) |
+| `app.*`    | **you**    | **your** function    | anything you declare                              |
+
+`hoist.*` and `mf.*` you get by turning on the features above. `app.*` is your own tools, which
+you declare with the `tools` prop:
+
+```tsx
+<MatterfactAgent
+  tools={[
+    {
+      name: 'exportBook', // advertised to the agent as `app.exportBook`
+      description: 'Export the current book to CSV.',
+      inputSchema: { type: 'object', properties: { scope: { type: 'string' } } },
+      confirm: 'required', // 'required' (default) shows an approval card; 'auto' runs without asking
+      handler: async ({ scope }) => myApp.exportBook(scope),
+    },
+  ]}
+/>
+```
+
+```js
+// script tag — same shape
+window.matterfact = { tools: [{ name: '…', description: '…', handler: async () => {} }] };
+```
+
+Names are namespaced into `app.` automatically, so a host tool can never collide with a
+matterfact one. A tool's `handler` result and any error it throws are **redacted before leaving
+the page**; a handler that throws, rejects, or hangs (beyond 30s) becomes a normal "not
+completed" result the agent reads and adapts to — never a crash. Like `actions`, changing the
+_shape_ of your tools (a name, description, schema, or confirm policy) remounts the widget so the
+new set is advertised; changing only a handler's body does not, so an inline `handler` closure
+won't churn the chat session.
+
+### Who decides which tools are exposed
+
+Advertising a tool is necessary but not sufficient: **which tools an app may actually expose is
+a server-side setting** on your embed app (`host_tools`: `off` / `allowlist` / `all`, plus an
+allow-list of names). The default allows matterfact's own `hoist.*` and `mf.*` and denies
+arbitrary `app.*` until an operator grants it — so `resolve` works out of the box, and turning on
+your first `app.*` tool is a deliberate decision made in the admin console, not something a page
+can do on its own. Ask your matterfact contact to enable the `app.*` names you need.
+
+### Watching tool calls — `onToolEvent`
+
+Pipe every advertise / call / result into your own telemetry:
+
+```tsx
+<MatterfactAgent
+  onToolEvent={(e) => myTelemetry.track('mf_tool', e)} // { phase, name, toolClass, args?, ok?, error?, ms? }
+/>
+```
+
+It's fire-and-forget and fully isolated — a throw or a slow callback here never blocks or breaks
+a tool call. matterfact also keeps its own durable audit of every call (visible to operators in
+the admin console), independent of this hook.
+
 ## Microphone / dictation
 
 The composer supports voice dictation; the loader grants the iframe `allow="microphone"`.

package/dist/{chunk-R2ZEJARX.js → chunk-4AE5WINC.js}

@@ -374,6 +374,148 @@ function executeHostTool(call, win = typeof window !== "undefined" ? window : vo
   }
 }
 
+// src/adapters/registry.ts
+var MAX_TOOLS = 16;
+var HOST_HANDLER_TIMEOUT_MS = 3e4;
+function mfGlobal(win) {
+  return win?.matterfact ?? {};
+}
+function toolClass(name) {
+  if (name.startsWith("hoist.")) return "hoist";
+  if (name.startsWith("mf.")) return "mf";
+  return "app";
+}
+function emitToolEvent(win, e) {
+  const cb = mfGlobal(win).onToolEvent;
+  if (typeof cb !== "function") return;
+  try {
+    cb(e);
+  } catch {
+  }
+}
+function mfTools(win) {
+  const { document: document2, artifact } = mfGlobal(win).resolve ?? {};
+  const out = [];
+  if (typeof document2 === "function") {
+    out.push({
+      name: "mf.resolveDocument",
+      description: 'Resolve a matterfact document (dossier, report, briefing) that is NOT on the current page to a concrete id. Call it with the document type and a key (e.g. a ticker) when the site map shows the document lives on another route. Returns {id, label, href}. Cite the result inline as <MFRef kind="document" id="<id>" label="<label>" /> \u2014 it renders as a chip that opens the document in the side panel; href is its "open on page" deeplink.',
+      inputSchema: {
+        type: "object",
+        properties: {
+          doctype: { type: "string" },
+          key: { type: "string" }
+        },
+        required: ["doctype", "key"]
+      },
+      readOnly: true,
+      confirm: "auto"
+    });
+  }
+  if (typeof artifact === "function") {
+    out.push({
+      name: "mf.resolveArtifact",
+      description: 'Resolve a matterfact artifact (an interactive board) that is NOT co-embedded on the current page to a read grant. Call it with the artifact slug. Returns {id, owner, token, label}; the grant is applied for you. Cite the result inline as <MFRef kind="artifact" id="<id>" label="<label>" /> \u2014 it renders as a chip that opens the artifact in the side panel.',
+      inputSchema: {
+        type: "object",
+        properties: { slug: { type: "string" } },
+        required: ["slug"]
+      },
+      readOnly: true,
+      confirm: "auto"
+    });
+  }
+  return out;
+}
+var APP_NAME_RE = /^[A-Za-z0-9._-]+$/;
+function appName(name) {
+  return name.startsWith("app.") ? name : `app.${name}`;
+}
+function appTools(win) {
+  const defs = mfGlobal(win).tools;
+  if (!Array.isArray(defs)) return [];
+  const out = [];
+  for (const d of defs) {
+    const raw = (d?.name ?? "").trim();
+    if (!raw || typeof d.handler !== "function") continue;
+    const name = appName(raw);
+    if (!APP_NAME_RE.test(name)) continue;
+    out.push({
+      name,
+      description: String(d.description ?? `Run the host tool ${name}.`),
+      inputSchema: d.inputSchema ?? { type: "object", properties: {} },
+      readOnly: false,
+      confirm: d.confirm === "auto" ? "auto" : "required"
+    });
+  }
+  return out;
+}
+function advertise(win = typeof window !== "undefined" ? window : void 0) {
+  const merged = [];
+  const seen = /* @__PURE__ */ new Set();
+  const push = (tools) => {
+    for (const t of tools) {
+      if (seen.has(t.name)) continue;
+      seen.add(t.name);
+      merged.push(t);
+    }
+  };
+  try {
+    push(advertiseTools(win));
+  } catch {
+  }
+  try {
+    push(mfTools(win));
+    push(appTools(win));
+  } catch {
+  }
+  return merged.slice(0, MAX_TOOLS);
+}
+function timeout(ms) {
+  return new Promise(
+    (_, reject) => setTimeout(() => reject(new Error("host tool timed out")), ms)
+  );
+}
+function redactResult(value) {
+  if (value === void 0 || value === null) return value;
+  if (typeof value === "string") return redact(value);
+  try {
+    return JSON.parse(redact(JSON.stringify(value)));
+  } catch {
+    return redact(String(value));
+  }
+}
+async function execute(call, win = typeof window !== "undefined" ? window : void 0) {
+  const cls = toolClass(call.name);
+  try {
+    if (cls === "hoist") {
+      return executeHostTool(call, win);
+    }
+    const handler = resolveHandler(win, call.name);
+    if (!handler) return { ok: false, error: "unknown tool" };
+    const result = await Promise.race([
+      Promise.resolve(handler(call.args ?? {})),
+      timeout(HOST_HANDLER_TIMEOUT_MS)
+    ]);
+    return { ok: true, result: redactResult(result) };
+  } catch (e) {
+    return {
+      ok: false,
+      error: redact(e instanceof Error ? e.message : "host tool failed")
+    };
+  }
+}
+function resolveHandler(win, name) {
+  const mf = mfGlobal(win);
+  if (name === "mf.resolveDocument") return mf.resolve?.document;
+  if (name === "mf.resolveArtifact") return mf.resolve?.artifact;
+  if (name.startsWith("app.")) {
+    const def = (mf.tools ?? []).find((d) => appName((d?.name ?? "").trim()) === name);
+    return def?.handler;
+  }
+  return void 0;
+}
+
 // src/context.ts
 var widgetOrigin = "";
 var MAX_ACTIVITY = 40;
@@ -479,6 +621,7 @@ async function publishContext() {
 }
 function provideContext() {
   void publishContext();
+  publishSitemap();
 }
 function grantsFromIframeSrcs(srcs, origin) {
   const out = [];
@@ -500,16 +643,56 @@ function grantsFromIframeSrcs(srcs, origin) {
   }
   return out;
 }
+function readDeclaredGrants() {
+  const declared = window.matterfact?.artifacts;
+  if (!Array.isArray(declared)) return [];
+  const out = [];
+  for (const a of declared) {
+    const id = (a?.slug || "").trim();
+    const owner = (a?.owner || "").trim();
+    const token = (a?.token || "").trim();
+    if (!id || !owner || !token) continue;
+    if (out.some((g) => g.id === id)) continue;
+    out.push({ id, owner, token });
+  }
+  return out;
+}
 function readArtifactGrants() {
   if (!widgetOrigin) return [];
   const srcs = Array.from(document.querySelectorAll("iframe")).map(
     (f) => f.getAttribute("src") || ""
   );
-  return grantsFromIframeSrcs(srcs, widgetOrigin);
+  const scanned = grantsFromIframeSrcs(srcs, widgetOrigin);
+  const out = [...scanned];
+  for (const g of readDeclaredGrants()) {
+    if (!out.some((s) => s.id === g.id)) out.push(g);
+  }
+  return out;
 }
 function publishArtifactGrants() {
   send?.({ type: "host.artifactGrants", grants: readArtifactGrants() });
 }
+function readSitemap2() {
+  const s = window.matterfact?.sitemap;
+  return Array.isArray(s) ? s : [];
+}
+function publishSitemap() {
+  if (!pageContextOn) return;
+  const sitemap = readSitemap2();
+  if (sitemap.length) send?.({ type: "host.sitemap", sitemap });
+}
+function navigateHost(href) {
+  if (typeof href !== "string" || !href) return;
+  let target;
+  try {
+    target = new URL(href, location.href);
+  } catch {
+    return;
+  }
+  if (target.protocol !== "http:" && target.protocol !== "https:") return;
+  if (target.origin !== location.origin) return;
+  location.assign(target.href);
+}
 function pushActivity(e) {
   activity.push({ ...e, seq: ++activitySeq, ts: Date.now() });
   if (activity.length > MAX_ACTIVITY) activity.shift();
@@ -574,10 +757,8 @@ function watchNavigation() {
     pushActivity({ type: "nav", summary: `navigated to ${url}` });
     void publishContext();
     publishArtifactGrants();
-    send?.({
-      type: "host.tools",
-      tools: advertiseTools(typeof window !== "undefined" ? window : void 0)
-    });
+    publishSitemap();
+    publishTools();
   };
   navFire = fire;
   for (const name of ["pushState", "replaceState"]) {
@@ -620,7 +801,7 @@ function describeControl(el) {
   return describe(el);
 }
 async function loadSnapshotModule() {
-  const m = await import('./snapshot-GL4YBMXD.js');
+  const m = await import('./snapshot-CRY2IBX6.js');
   snapshotModule = m;
   return m;
 }
@@ -684,10 +865,24 @@ async function callTool(call, emit) {
     });
     return;
   }
-  const r = executeHostTool(
-    call,
-    typeof window !== "undefined" ? window : void 0
-  );
+  const win = typeof window !== "undefined" ? window : void 0;
+  const cls = toolClass(call.name);
+  const startedAt = Date.now();
+  emitToolEvent(win, {
+    phase: "call",
+    name: call.name,
+    toolClass: cls,
+    args: call.args
+  });
+  const r = await execute(call, win);
+  emitToolEvent(win, {
+    phase: "result",
+    name: call.name,
+    toolClass: cls,
+    ok: r.ok,
+    error: r.error,
+    ms: Date.now() - startedAt
+  });
   emit({
     type: "host.toolResult",
     callId: call.callId,
@@ -736,6 +931,7 @@ function start(emit, origin, pageContext = true, provider) {
   if (pageContextOn) {
     void publishContext();
     publishArtifactGrants();
+    publishSitemap();
     watchNavigation();
     document.addEventListener("click", onClick, {
       capture: true,
@@ -764,13 +960,33 @@ function start(emit, origin, pageContext = true, provider) {
   const theme = matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
   emit({ type: "host.theme", mode: theme });
   if (pageContextOn) {
-    const tools = advertiseTools(
-      typeof window !== "undefined" ? window : void 0
-    );
-    if (tools.length) emit({ type: "host.tools", tools });
+    const w = typeof window !== "undefined" ? window : void 0;
+    const tools = advertise(w);
+    if (tools.length) {
+      emit({ type: "host.tools", tools });
+      for (const t of tools) {
+        emitToolEvent(w, {
+          phase: "advertise",
+          name: t.name,
+          toolClass: toolClass(t.name)
+        });
+      }
+    }
+  }
+}
+function publishTools() {
+  const win = typeof window !== "undefined" ? window : void 0;
+  const tools = advertise(win);
+  send?.({ type: "host.tools", tools });
+  for (const t of tools) {
+    emitToolEvent(win, {
+      phase: "advertise",
+      name: t.name,
+      toolClass: toolClass(t.name)
+    });
   }
 }
 
-export { artifactIdFromPath, buildPageContext, callTool, grantsFromIframeSrcs, isPrivate, provideContext, readPageContext, redact, sendRegion, sendSnapshot, start, stop };
-//# sourceMappingURL=chunk-R2ZEJARX.js.map
-//# sourceMappingURL=chunk-R2ZEJARX.js.map
+export { artifactIdFromPath, buildPageContext, callTool, grantsFromIframeSrcs, isPrivate, navigateHost, provideContext, readDeclaredGrants, readPageContext, redact, sendRegion, sendSnapshot, start, stop };
+//# sourceMappingURL=chunk-4AE5WINC.js.map
+//# sourceMappingURL=chunk-4AE5WINC.js.map