@matterfact/embed 0.9.0 → 0.11.0

package/README.md

@@ -164,6 +164,60 @@ in the widget (authorized by the signed-in user's own matterfact access — no t
 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
@@ -382,6 +436,74 @@ 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.
+
+### Telemetry — `onEvent`
+
+One hook pipes the whole widget into your own observability — lifecycle (`ready`, `open`,
+`close`, `navigate`, `auth`, `error`), each chat turn (`chat`), and every tool call (`tool`):
+
+```tsx
+<MatterfactAgent
+  onEvent={(e) => myTelemetry.track(`mf.${e.type}`, e)}
+/>
+```
+
+Fire-and-forget and fully isolated — a throw or a slow callback here never blocks or breaks the
+widget, a tool call, or a run. Chat events are content-free (phase + opaque chat id, never
+message text). `onToolEvent` still works as a tool-only subset for back-compat.
+
+**→ Full event reference: [`docs/telemetry.md`](docs/telemetry.md).**
+
 ## Microphone / dictation
 
 The composer supports voice dictation; the loader grants the iframe `allow="microphone"`.

package/dist/{chunk-6EM7T2JV.js → chunk-AANODHBV.js}

@@ -376,6 +376,157 @@ 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 emitEvent(win, e) {
+  const cb = mfGlobal(win).onEvent;
+  if (typeof cb !== "function") return;
+  try {
+    cb(e);
+  } catch {
+  }
+}
+function emitToolEvent(win, e) {
+  emitEvent(win, { type: "tool", ...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;
@@ -503,12 +654,31 @@ 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() });
@@ -599,10 +769,7 @@ function watchNavigation() {
     void publishContext();
     publishArtifactGrants();
     publishSitemap();
-    send?.({
-      type: "host.tools",
-      tools: advertiseTools(typeof window !== "undefined" ? window : void 0)
-    });
+    publishTools();
   };
   navFire = fire;
   for (const name of ["pushState", "replaceState"]) {
@@ -646,7 +813,7 @@ function describeControl(el) {
   return describe(el);
 }
 async function loadSnapshotModule() {
-  const m = await import("./snapshot-4GXT6PKZ.js");
+  const m = await import("./snapshot-2V5SDSH2.js");
   snapshotModule = m;
   return m;
 }
@@ -710,10 +877,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,
@@ -791,10 +972,30 @@ 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)
+    });
   }
 }
 
@@ -806,6 +1007,7 @@ export {
   readPageContext,
   provideContext,
   grantsFromIframeSrcs,
+  readDeclaredGrants,
   navigateHost,
   sendSnapshot,
   sendRegion,
@@ -813,4 +1015,4 @@ export {
   stop,
   start
 };
-//# sourceMappingURL=chunk-6EM7T2JV.js.map
+//# sourceMappingURL=chunk-AANODHBV.js.map