@opengeni/runtime 2.5.3-canary.3 → 2.6.0-canary.1

package/src/bundled_default_skills/opengeni-visualize/assets/helpers.html

@@ -0,0 +1,349 @@
+<!--__INLINE_VISUALIZATION_FRAGMENT__-->
+<script src="https://unpkg.com/@floating-ui/core@1.7.3/dist/floating-ui.core.umd.min.js"></script>
+<script src="https://unpkg.com/@floating-ui/dom@1.7.4/dist/floating-ui.dom.umd.min.js"></script>
+<script>
+  (() => {
+    if (window.FloatingUIDOM == null) {
+      return;
+    }
+    const { autoUpdate, computePosition, flip, offset, shift, size } = window.FloatingUIDOM;
+    const tooltipPlacements = new Set(["top", "right", "bottom", "left"]);
+    const tooltipId = `codex-visualization-tooltip-${
+      window.crypto?.randomUUID?.() ?? Date.now().toString(36)
+    }`;
+    const tooltipGap = 5;
+    const hoverDelay = 700;
+    const skipDelay = 300;
+    let activeTrigger = null;
+    let pendingTrigger = null;
+    let tooltip = null;
+    let openTimeout = null;
+    let autoUpdateCleanup = null;
+    let positionRequest = 0;
+    let skipDelayUntil = 0;
+    let lastPointerWasTouch = false;
+    let pinnedByTouch = false;
+
+    const getTrigger = (target) =>
+      target?.nodeType === Node.ELEMENT_NODE ? target.closest("[data-tooltip]") : null;
+    const containsTarget = (trigger, target) =>
+      target?.nodeType != null && trigger.contains(target);
+    const getContent = (trigger) => trigger.getAttribute("data-tooltip")?.trim() ?? "";
+    const getPlacement = (trigger) => {
+      const placement = trigger.getAttribute("data-tooltip-placement");
+      return tooltipPlacements.has(placement) ? placement : "top";
+    };
+    const getTooltip = () => {
+      if (tooltip == null) {
+        tooltip = document.createElement("div");
+        tooltip.id = tooltipId;
+        tooltip.className = "tooltip";
+        tooltip.setAttribute("role", "tooltip");
+      }
+      return tooltip;
+    };
+    const setDescribedBy = (trigger, described) => {
+      const ids = new Set(
+        (trigger.getAttribute("aria-describedby") ?? "").split(/\s+/).filter(Boolean),
+      );
+      if (described) {
+        ids.add(tooltipId);
+      } else {
+        ids.delete(tooltipId);
+      }
+      if (ids.size === 0) {
+        trigger.removeAttribute("aria-describedby");
+      } else {
+        trigger.setAttribute("aria-describedby", [...ids].join(" "));
+      }
+    };
+    const clearOpenTimeout = () => {
+      if (openTimeout != null) {
+        window.clearTimeout(openTimeout);
+        openTimeout = null;
+      }
+      pendingTrigger = null;
+    };
+    const closeTooltip = (activateSkipDelay = true) => {
+      clearOpenTimeout();
+      pinnedByTouch = false;
+      positionRequest += 1;
+      autoUpdateCleanup?.();
+      autoUpdateCleanup = null;
+      if (activeTrigger == null) {
+        return;
+      }
+      setDescribedBy(activeTrigger, false);
+      activeTrigger = null;
+      tooltip?.remove();
+      if (activateSkipDelay) {
+        skipDelayUntil = Date.now() + skipDelay;
+      }
+    };
+    const updatePosition = (trigger, floating) => {
+      const request = ++positionRequest;
+      void computePosition(trigger, floating, {
+        middleware: [
+          offset(tooltipGap),
+          flip({ padding: tooltipGap }),
+          shift({ padding: tooltipGap }),
+          size({
+            padding: tooltipGap,
+            apply({ availableHeight, availableWidth, elements }) {
+              elements.floating.style.setProperty(
+                "--tooltip-available-width",
+                `${Math.max(0, availableWidth)}px`,
+              );
+              elements.floating.style.setProperty(
+                "--tooltip-available-height",
+                `${Math.max(0, availableHeight)}px`,
+              );
+            },
+          }),
+        ],
+        placement: getPlacement(trigger),
+        strategy: "fixed",
+      })
+        .then(({ x, y }) => {
+          if (activeTrigger !== trigger || request !== positionRequest) {
+            return;
+          }
+          const scale = window.devicePixelRatio || 1;
+          floating.style.transform = `translate(${Math.round(x * scale) / scale}px, ${Math.round(y * scale) / scale}px)`;
+          floating.style.visibility = "visible";
+        })
+        .catch(() => {
+          if (activeTrigger === trigger && request === positionRequest) {
+            closeTooltip(false);
+          }
+        });
+    };
+    const openTooltip = (trigger) => {
+      const content = getContent(trigger);
+      if (!trigger.isConnected || content.length === 0) {
+        return;
+      }
+      clearOpenTimeout();
+      if (activeTrigger === trigger) {
+        return;
+      }
+      closeTooltip();
+      const floating = getTooltip();
+      floating.textContent = content;
+      floating.style.visibility = "hidden";
+      floating.style.transform = "translate(0, 0)";
+      document.body.appendChild(floating);
+      activeTrigger = trigger;
+      setDescribedBy(trigger, true);
+      autoUpdateCleanup = autoUpdate(trigger, floating, () => {
+        updatePosition(trigger, floating);
+      });
+    };
+    const requestOpen = (trigger, immediate = false) => {
+      if (
+        getContent(trigger).length === 0 ||
+        activeTrigger === trigger ||
+        pendingTrigger === trigger
+      ) {
+        return;
+      }
+      clearOpenTimeout();
+      pendingTrigger = trigger;
+      const delay =
+        immediate || activeTrigger != null || Date.now() < skipDelayUntil ? 0 : hoverDelay;
+      if (delay === 0) {
+        openTooltip(trigger);
+        return;
+      }
+      openTimeout = window.setTimeout(() => {
+        openTimeout = null;
+        pendingTrigger = null;
+        openTooltip(trigger);
+      }, delay);
+    };
+    const handlePointerOpen = (event) => {
+      if (event.pointerType === "touch") {
+        return;
+      }
+      const trigger = getTrigger(event.target);
+      if (trigger == null || containsTarget(trigger, event.relatedTarget)) {
+        return;
+      }
+      requestOpen(trigger);
+    };
+    const handlePointer = (event) => {
+      lastPointerWasTouch = event.type === "pointerdown" && event.pointerType === "touch";
+    };
+    const handleTouchClick = (event) => {
+      const isTouch = event.pointerType === "touch" || lastPointerWasTouch;
+      lastPointerWasTouch = false;
+      if (!isTouch || event.detail === 0) {
+        return;
+      }
+      const trigger = getTrigger(event.target);
+      if (
+        trigger == null ||
+        !trigger.isConnected ||
+        getContent(trigger).length === 0 ||
+        (pinnedByTouch && activeTrigger === trigger)
+      ) {
+        if (pinnedByTouch) {
+          closeTooltip();
+        }
+        return;
+      }
+      openTooltip(trigger);
+      pinnedByTouch = activeTrigger === trigger;
+      window.setTimeout(() => {
+        if (activeTrigger === trigger && !trigger.isConnected) {
+          closeTooltip(false);
+        }
+      }, 0);
+    };
+    const handleLeave = (event) => {
+      if (pinnedByTouch) {
+        return;
+      }
+      const trigger = getTrigger(event.target);
+      if (trigger == null || containsTarget(trigger, event.relatedTarget)) {
+        return;
+      }
+      if (activeTrigger === trigger || pendingTrigger === trigger) {
+        closeTooltip();
+      }
+    };
+    const handleFocusIn = (event) => {
+      const trigger = getTrigger(event.target);
+      if (trigger?.matches(":focus-visible")) {
+        requestOpen(trigger, true);
+      }
+    };
+    const handleKeyDown = (event) => {
+      if (event.key === "Escape") {
+        closeTooltip();
+      }
+    };
+    const handleContextMenu = (event) => {
+      lastPointerWasTouch = false;
+      const trigger = getTrigger(event.target);
+      if (activeTrigger === trigger || pendingTrigger === trigger) {
+        closeTooltip();
+      }
+    };
+    const destroy = () => {
+      closeTooltip(false);
+      lastPointerWasTouch = false;
+      document.removeEventListener("pointerover", handlePointerOpen);
+      document.removeEventListener("pointerdown", handlePointer);
+      document.removeEventListener("pointercancel", handlePointer);
+      document.removeEventListener("click", handleTouchClick);
+      document.removeEventListener("pointerout", handleLeave);
+      document.removeEventListener("focusin", handleFocusIn);
+      document.removeEventListener("focusout", handleLeave);
+      document.removeEventListener("keydown", handleKeyDown);
+      document.removeEventListener("contextmenu", handleContextMenu);
+      tooltip = null;
+    };
+
+    document.addEventListener("pointerover", handlePointerOpen);
+    document.addEventListener("pointerdown", handlePointer);
+    document.addEventListener("pointercancel", handlePointer);
+    document.addEventListener("click", handleTouchClick);
+    document.addEventListener("pointerout", handleLeave);
+    document.addEventListener("focusin", handleFocusIn);
+    document.addEventListener("focusout", handleLeave);
+    document.addEventListener("keydown", handleKeyDown);
+    document.addEventListener("contextmenu", handleContextMenu);
+    window.addEventListener("pagehide", destroy, { once: true });
+  })();
+</script>
+<script id="codex-visualization-tabs">
+  (() => {
+    const selector = '.nav[role="tablist"] [role="tab"]';
+    const disabled = ':disabled,[aria-disabled="true"]';
+    const selectTab = (selected) => {
+      const panelId = selected.getAttribute("aria-controls");
+      for (const tab of selected.closest('[role="tablist"]').querySelectorAll('[role="tab"]')) {
+        const active = tab === selected;
+        tab.classList.toggle("active", active);
+        tab.setAttribute("aria-selected", String(active));
+        const id = tab.getAttribute("aria-controls");
+        const panel = id && document.getElementById(id);
+        if (panel != null) {
+          panel.hidden = id !== panelId;
+          if (!panel.hidden && selected.id) {
+            panel.setAttribute("aria-labelledby", selected.id);
+          }
+        }
+      }
+    };
+    const interact = (event) => {
+      const tab = event.target?.closest?.(selector);
+      if (event.defaultPrevented || tab == null || tab.matches(disabled)) {
+        return;
+      }
+      if (event.type === "click") {
+        selectTab(tab);
+        return;
+      }
+      const tabs = Array.from(
+        tab.closest('[role="tablist"]').querySelectorAll('[role="tab"]'),
+      ).filter((candidate) => !candidate.matches(disabled));
+      const current = tabs.indexOf(tab);
+      let next;
+      if (event.key === "ArrowRight" || event.key === "ArrowDown") {
+        next = (current + 1) % tabs.length;
+      } else if (event.key === "ArrowLeft" || event.key === "ArrowUp") {
+        next = (current + tabs.length - 1) % tabs.length;
+      } else if (event.key === "Home") {
+        next = 0;
+      } else if (event.key === "End") {
+        next = tabs.length - 1;
+      } else {
+        return;
+      }
+      event.preventDefault();
+      tabs[next].focus();
+      selectTab(tabs[next]);
+    };
+
+    for (const list of document.querySelectorAll('.nav[role="tablist"]')) {
+      const selected =
+        list.querySelector('[role="tab"][aria-selected="true"]') ??
+        list.querySelector('[role="tab"].active') ??
+        list.querySelector('[role="tab"]');
+      if (selected != null) {
+        selectTab(selected);
+      }
+    }
+    document.addEventListener("click", interact);
+    document.addEventListener("keydown", interact);
+    window.addEventListener(
+      "pagehide",
+      () => {
+        document.removeEventListener("click", interact);
+        document.removeEventListener("keydown", interact);
+      },
+      { once: true },
+    );
+  })();
+</script>
+<script
+  id="codex-visualization-lucide"
+  async
+  src="https://unpkg.com/lucide@1.17.0/dist/umd/lucide.js"
+></script>
+<script>
+  (() => {
+    const initialize = () => {
+      globalThis.lucide?.createIcons({ attrs: { width: 16, height: 16 } });
+    };
+    if (globalThis.lucide != null) {
+      initialize();
+      return;
+    }
+    document
+      .getElementById("codex-visualization-lucide")
+      ?.addEventListener("load", initialize, { once: true });
+  })();
+</script>

package/src/bundled_site_skills/opengeni-sites/SKILL.md

@@ -15,6 +15,13 @@ provider-specific API wrapper, or OpenGeni-only build CLI.
 
 ## Start from the durable Site
 
+- For an existing page the user wants to view and share, consider Sites before
+  choosing a temporary tunnel or another server. Inspect whether it can be
+  packaged as self-contained HTML, preserve its design and behavior, and retain
+  editable source when available. A local preview alone is still appropriate
+  when that is all the user requests. Explain workspace access for the published
+  link; do not imply it is public to anyone. If the app requires a backend that
+  Sites cannot host, explain that constraint instead of dropping functionality.
 - For a new Site, create a normal project directory with `package.json`,
   `index.html`, TypeScript/React source, styles, tests, and any ordinary build
   configuration the app needs.
@@ -112,6 +119,41 @@ Exercise the real interactions at desktop and mobile widths, inspect console
 errors, and take a screenshot when visual quality matters. Do not declare the
 Site complete from compilation alone.
 
+## Plain HTML without a browser build
+
+For a small HTML-only Site, use ordinary HTML, CSS, and JavaScript. If it calls
+OpenGeni tools or SDK methods, place this exact optional tag before your own
+scripts (without async, defer, or type="module"):
+
+```html
+<script src="/__opengeni/site-tools/client.js"></script>
+<script>
+  const site = createOpenGeniSiteClient();
+  // Use the actual tool paths discovered with ogtool on site.tools.
+  // site.client is the same ordinary SDK client as in a React Site.
+</script>
+```
+
+The existing preview handler above serves this script. Serve the raw HTML with
+`new Response(Bun.file("./index.html"))` alongside its tool route; no browser
+build is needed. In the published viewer, the host resolves the tag to its
+browser client. Both use the same SDK implementation and existing tool bridge.
+Opening the file directly supplies no tool host. There are no credentials in
+the tag or HTML. Declare requested tools and handle errors as for any Site.
+
+Use the exact package pins above for the preview host. The preview runtime comes
+from that installed SDK; the published runtime comes from the viewer's deployed
+SDK. The tag does not install dependencies, replace React imports, or change Bun.
+For TypeScript checking, React components, or imported browser dependencies,
+use the normal typed SDK and build workflow above. Do not use both client-loading
+paths in one document.
+
+Publish the original HTML containing the tag, not the served client script or
+transformed viewer document. For this path, upload `index.html` wherever the
+publishing instructions below use `dist/index.html`. Inline ordinary styles,
+scripts, and assets as usual; the OpenGeni client tag is resolved by the host.
+An HTML-only Site can be a small widget; it does not require a full-page layout.
+
 ## Prefer OpenGeni's UI and typed client
 
 - Prefer `@opengeni/react` components and compiled CSS for OpenGeni-native
@@ -259,13 +301,38 @@ access limitation. Missing publishing access itself still blocks publication.
    SDK operations, with no direct `site.tools` calls, should publish
    `requestedTools: []`.
 4. The immutable requested set is only a maximum allowlist; publishing it grants
-   no tool authority and requires no separate tool approval. Site calls do not open
-   per-call approval dialogs.
+   no tool authority and requires no separate tool approval. Execution still follows
+   normal tool approval rules; handle approval-required responses in the UI.
 5. The host intersects that set with the viewer's
    live workspace, permission, and connection authority on every call. Handle
    missing tools, revoked connections, stale catalogs, and access loss as normal
    user-visible error states.
 
+## Show a visualization or Site inside chat
+
+For an inline visualization stored directly in a chat response, read
+`opengeni-visualize`. That path does not require publishing a Site.
+
+To embed a published Site, use a fenced `opengeni-site` block containing JSON:
+
+```opengeni-site
+{"siteId":"<artifact.id>","versionId":"<published version.id>"}
+```
+
+Use the actual returned ids. `versionId` is optional; omitting it loads the
+current version when the embed opens. Including it preserves the intended
+version. The viewer can choose another version within the embed without
+publishing or rolling back the Site. The embed uses the same Site renderer,
+reload/full-screen controls, tool declarations and viewer permissions as the
+Site page. Embeds resolve in the chat's workspace. Keep a normal Site link when
+it helps the user reopen or share it. Archived or inaccessible Sites display
+an unavailable state.
+
+Use inline HTML for a visualization that belongs in this response. Use a Site
+for a reusable app or durable page, and embed it when useful. Both can be small;
+neither requires a dashboard or full-page layout. React Sites still use the
+normal build and publish workflow.
+
 ## Publish one immutable version
 
 1. Call `opengeni__artifacts_prepare_upload` (no hashes or sizes required).

package/src/gmail-rest-mcp.ts

@@ -354,7 +354,8 @@ export class GmailRestMcpServer implements LocalMcpBridgeServer {
       forceRefresh: false,
       ...(this.options.subjectId ? { subjectId: this.options.subjectId } : {}),
     });
-    if (result.status !== "ok") {
+    if (result.status === "auth_needed") {
+      await this.reportAuthNeeded(result);
       throw new GmailRestAuthError("Authentication required for Gmail");
     }
     this.options.onResolvedConnectionId?.(result.connectionId);
@@ -683,6 +684,28 @@ export class GmailRestMcpServer implements LocalMcpBridgeServer {
     };
   }
 
+  private async reportAuthNeeded(
+    result: Extract<ResolveCredentialResult, { status: "auth_needed" }>,
+    toolName?: string,
+  ): Promise<void> {
+    await this.options.onAuthNeeded?.({
+      serverId: this.options.serverId,
+      ...(toolName ? { toolName } : {}),
+      providerDomain: result.providerDomain,
+      ...(result.provider ? { provider: result.provider } : {}),
+      reason: result.reason,
+      ...(result.connectionId ? { connectionId: result.connectionId } : {}),
+      ...(result.authoritySource === "host" || this.options.connectionRef.authoritySource === "host"
+        ? { authoritySource: "host" as const }
+        : {}),
+      ...(result.scopes ? { scopes: result.scopes } : {}),
+      ...(result.resource ? { resource: result.resource } : {}),
+      ...(result.selectedResources ? { selectedResources: result.selectedResources } : {}),
+      ...(result.authorizationUrl ? { authorizationUrl: result.authorizationUrl } : {}),
+      ...(this.options.subjectId ? { subjectId: this.options.subjectId } : {}),
+    });
+  }
+
   private async request<T>(
     toolName: string,
     urlInput: string | URL,
@@ -708,23 +731,7 @@ export class GmailRestMcpServer implements LocalMcpBridgeServer {
         ...(this.options.subjectId ? { subjectId: this.options.subjectId } : {}),
       });
       if (result.status === "auth_needed") {
-        await this.options.onAuthNeeded?.({
-          serverId: this.options.serverId,
-          toolName,
-          providerDomain: result.providerDomain,
-          ...(result.provider ? { provider: result.provider } : {}),
-          reason: result.reason,
-          ...(result.connectionId ? { connectionId: result.connectionId } : {}),
-          ...(result.authoritySource === "host" ||
-          this.options.connectionRef.authoritySource === "host"
-            ? { authoritySource: "host" as const }
-            : {}),
-          ...(result.scopes ? { scopes: result.scopes } : {}),
-          ...(result.resource ? { resource: result.resource } : {}),
-          ...(result.selectedResources ? { selectedResources: result.selectedResources } : {}),
-          ...(result.authorizationUrl ? { authorizationUrl: result.authorizationUrl } : {}),
-          ...(this.options.subjectId ? { subjectId: this.options.subjectId } : {}),
-        });
+        await this.reportAuthNeeded(result, toolName);
         throw new GmailRestAuthError("Authentication required for Gmail");
       }
       this.options.onResolvedConnectionId?.(result.connectionId);

package/src/operational-instructions.ts

@@ -72,21 +72,11 @@ Your answer is being rendered by an application for the user. Follow these guide
   * Do not provide ranges of lines.
   * Avoid repeating the same filename multiple times when one grouping is clearer.
 
-### Visualizations
+### Visuals in chat
 
-Use a visualization only when it makes an important relationship materially easier to understand than prose or a short list. Do not add one merely because an answer has components or steps.
+Use inline HTML when an interactive visualization materially helps the user; read the opengeni-visualize skill first. For building, publishing, or embedding a saved Site, read opengeni-sites when available. Use ordinary Markdown for simple explanations and tables.
 
-Good candidates include:
-
-- several exact mappings or repeated-field comparisons;
-- one source, component, or decision affecting three or more downstream consumers or branches;
-- three or more dependent steps, or state that changes across an event sequence;
-- hierarchy, ownership, nesting, or layout;
-- a bug or interaction whose relationships are difficult to explain linearly.
-
-Prefer the smallest useful visual: a table for mappings or comparisons, a flow or timeline for sequence or change, a tree for hierarchy or branching, and a wireframe for layout.
-
-Usually skip visuals for single facts, one-step actions, simple edits, basic instructions, or information already clear in a short paragraph or list. Compact notation and small examples do not count as visualizations.
+Display images with ![descriptive alt text](artifact:<artifactId>). Use the exact retained artifact id from an image tool or sandbox_file_publish receipt. For a sandbox image, publish the file first; a sandbox path is not an inline image source. Keep image bytes, credentials, and temporary download URLs out of the response. Ordinary public image URLs also work. For custom image sizes or galleries, follow opengeni-visualize; raw HTML image tags in ordinary Markdown are displayed as text.
 
 # Rules for getting work done