@jini-ai/agent-plugins 0.6.17 → 0.6.19

package/google-workspace/ui/picker-flow.mjs

@@ -0,0 +1,87 @@
+/**
+ * @file "Choose spreadsheet" in the browser, shared by the Picker panel and the form-destination
+ * panel. Resolves with the server-VERIFIED spreadsheet metadata, or null when the person cancelled
+ * (nothing is saved on cancel).
+ *
+ * Hosted: loads Google's JS Picker (the one script origin the surface's CSP allows) and opens it with
+ * the bootstrap's short-lived access token and public config, spreadsheets only, one file. The file
+ * id it returns is only a claim: it goes to `verify-picked` with the Picker session id, and only the
+ * server's answer is used.
+ *
+ * Desktop: the native Picker runs in the system browser. `start-system-picker` makes the server start
+ * that sign-in (the admin page offers the link; this frame cannot open one), then the frame polls
+ * `finish-system-picker` until the server reports a verified selection, a cancel, or the expiry.
+ */
+import { wait } from './dom.mjs';
+import { pollText } from './picker-view.mjs';
+
+const SPREADSHEET_MIME_TYPE = 'application/vnd.google-apps.spreadsheet';
+const PICKER_SCRIPT = 'https://apis.google.com/js/api.js';
+const POLL_MS = 3000;
+
+/**
+ * Loads Google's Picker library once. Rejects when the script is blocked or fails, and forgets the
+ * failure so the next "Choose spreadsheet" (the message says "try again") loads it again.
+ */
+let pickerLibrary;
+function loadPickerLibrary() {
+  pickerLibrary ??= new Promise((resolve, reject) => {
+    const script = document.createElement('script');
+    script.src = PICKER_SCRIPT;
+    script.onerror = () => { pickerLibrary = undefined; reject(new Error('Google\'s file picker could not load (a blocked script, network, or browser setting). Allow apis.google.com and try again.')); };
+    script.onload = () => window.gapi.load('picker', { callback: () => resolve(window.google.picker), onerror: script.onerror });
+    document.head.append(script);
+  });
+  return pickerLibrary;
+}
+
+/** Opens the hosted Picker; resolves with the picked file id, or null on cancel. */
+async function pickHostedFileId(config) {
+  const picker = await loadPickerLibrary();
+  return new Promise((resolve) => {
+    const view = new picker.DocsView(picker.ViewId.SPREADSHEETS).setMimeTypes(SPREADSHEET_MIME_TYPE);
+    const onEvent = (data) => {
+      const action = data[picker.Response.ACTION];
+      if (action === picker.Action.PICKED) resolve(data[picker.Response.DOCUMENTS]?.[0]?.[picker.Document.ID] ?? null);
+      else if (action === picker.Action.CANCEL) resolve(null);
+      else {
+        // Intermediate Picker events do not settle the choice.
+      }
+    };
+    new picker.PickerBuilder()
+      .setDeveloperKey(config.developerKey).setAppId(config.appId).setOAuthToken(config.accessToken)
+      .addView(view).setCallback(onEvent).build().setVisible(true);
+  });
+}
+
+/** Hosted: pick, then let the server verify. */
+async function chooseHosted({ client, bootstrap }) {
+  const fileId = await pickHostedFileId(bootstrap.picker);
+  if (fileId === null) return null;
+  const { spreadsheet } = await client.call({ action: 'verify-picked', payload: { sessionId: bootstrap.picker.sessionId, fileId } });
+  return spreadsheet;
+}
+
+/** Desktop: start, then poll until selected, cancelled, expired, or the person stops waiting. */
+async function chooseInSystemBrowser({ client, onStatus, stopped }) {
+  const { expiresAt } = await client.call({ action: 'start-system-picker', payload: {} });
+  onStatus(pollText({ status: 'waiting' }));
+  while (!stopped() && Date.now() < Date.parse(expiresAt) + POLL_MS) {
+    await wait(POLL_MS);
+    const outcome = await client.call({ action: 'finish-system-picker', payload: {} });
+    if (outcome.status === 'selected') return outcome.spreadsheet;
+    if (outcome.status !== 'waiting') { onStatus(pollText(outcome)); return null; }
+  }
+  onStatus(pollText({ status: stopped() ? 'cancelled' : 'expired' }));
+  return null;
+}
+
+/**
+ * Runs "Choose spreadsheet" for the bootstrap's mode.
+ * @param {{ client: { call: Function }, bootstrap: { mode: string, picker?: object }, onStatus: (text: string) => void, stopped?: () => boolean }} required
+ * @returns {Promise<{ spreadsheetId: string, title: string, url: string } | null>} null = nothing chosen, nothing saved.
+ */
+export function chooseSpreadsheet(required) {
+  const { client, bootstrap, onStatus, stopped = () => false } = required;
+  return bootstrap.mode === 'hosted' ? chooseHosted({ client, bootstrap }) : chooseInSystemBrowser({ client, onStatus, stopped });
+}

package/google-workspace/ui/picker-view.mjs

@@ -0,0 +1,44 @@
+/**
+ * @file What "Choose spreadsheet" says at each step: pure text for the bootstrap modes and the desktop
+ * poll outcomes, shared by the Picker panel and the form-destination panel. No DOM, so the rule that
+ * a cancel changes nothing is stated (and testable) in one place.
+ */
+
+/** Shown whenever a form destination is saved or removed: local deletes never purge Google's rows. */
+export const EXTERNAL_ROWS_NOTE = 'Rows this site writes stay in the spreadsheet: removing this destination, or deleting the form or its submissions on this site, does not delete them.';
+
+export const CANCELLED_TEXT = 'No spreadsheet was chosen. Your saved settings did not change.';
+
+const POLL_TEXT = Object.freeze({
+  waiting: 'Choose the spreadsheet in your browser. Use the "Continue to sign-in" button the admin page shows above this panel; Google opens its file picker after the sign-in.',
+  expired: 'The file picker link expired before a spreadsheet was chosen. Your saved settings did not change; start again.',
+  none: 'No file picker is open. Start again.',
+  cancelled: CANCELLED_TEXT,
+});
+
+/**
+ * The line shown for a bootstrap mode before anything is chosen.
+ * @param {{ bootstrap: { mode: string, message?: string } | undefined }} required
+ * @returns {string}
+ */
+export function pickerIntro(required, _optional = {}) {
+  const { bootstrap } = required;
+  if (bootstrap === undefined) return 'The panel did not receive its start data in time. Close it and open it again.';
+  if (bootstrap.mode === 'unavailable') return bootstrap.message ?? 'Google Sheets is not ready. Check the Google Workspace connection panel.';
+  if (bootstrap.mode === 'hosted') return 'Choose a Google Sheets spreadsheet. This site gets access to that one file only.';
+  return 'Choose a Google Sheets spreadsheet. Google\'s file picker opens in your browser; this site gets access to that one file only.';
+}
+
+/**
+ * The line for a desktop poll outcome (`selected` is rendered by the caller with the file's title).
+ * @param {{ status: 'waiting' | 'expired' | 'none' | 'cancelled' }} required
+ * @returns {string}
+ */
+export function pollText(required, _optional = {}) {
+  return POLL_TEXT[required.status] ?? POLL_TEXT.none;
+}
+
+/** The line for a verified selection. */
+export function selectedText(required, _optional = {}) {
+  return `Chosen: ${required.spreadsheet.title}.`;
+}

package/google-workspace/ui/picker.handler.mjs

@@ -0,0 +1,56 @@
+/**
+ * @file Server-side handlers of the "Choose spreadsheet" panel (`ui/picker.html`), loaded by the host
+ * as this surface's `handlerModule` (never served to the frame).
+ *
+ * Exists so a person can grant the site one spreadsheet under `drive.file` the only way that grants it:
+ * Google's Picker (hosted: the JS Picker in the panel; desktop: the native Picker in the system
+ * browser). A selection is saved to the plugin's settings only after `lib/picker-flow.mjs` verified
+ * it (session, account, spreadsheet type, real Sheets access); the frame and chat get metadata only.
+ * A cancelled pick saves nothing.
+ */
+import { createPickerFlow, metadataOf, pollReply, readPickedSpreadsheets, rememberPickedSpreadsheet } from '../lib/picker-flow.mjs';
+import { withSurfaceFailures } from '../lib/surface-actions.mjs';
+
+/**
+ * Builds the panel's handler module.
+ * @param {object} [_required]
+ * @param {{ now?: () => number, randomId?: () => string }} [optional] Passed to the Picker flow (tests).
+ * @returns {{ bootstrap: Function, actions: Record<string, Function> }} The `handlerModule` default export shape.
+ * @complexity O(1) to build; see each action.
+ */
+export function createPickerHandlers(_required = {}, optional = {}) {
+  const flow = createPickerFlow({}, optional);
+  const listed = async (capabilities) => ({ spreadsheets: (await readPickedSpreadsheets({ state: capabilities.state })).map(metadataOf) });
+
+  return {
+    bootstrap: (call) => flow.bootstrap(call),
+    actions: {
+      /** The spreadsheets picked so far (metadata), newest first. */
+      'list-picked': ({ capabilities, fail }) => withSurfaceFailures({ fail, run: () => listed(capabilities) }),
+
+      /** Hosted Picker result → verified → saved → metadata. */
+      'verify-picked': (call) => withSurfaceFailures({
+        fail: call.fail,
+        run: async () => {
+          const spreadsheet = await flow.verifyHosted(call);
+          await rememberPickedSpreadsheet({ state: call.capabilities.state, spreadsheet });
+          return { spreadsheet: metadataOf(spreadsheet) };
+        },
+      }),
+
+      'start-system-picker': (call) => withSurfaceFailures({ fail: call.fail, run: () => flow.startSystemBrowser(call) }),
+
+      /** Desktop poll; a verified selection is saved before it is reported. */
+      'finish-system-picker': (call) => withSurfaceFailures({
+        fail: call.fail,
+        run: async () => {
+          const outcome = await flow.finishSystemBrowser(call);
+          if (outcome.status === 'selected') await rememberPickedSpreadsheet({ state: call.capabilities.state, spreadsheet: outcome.spreadsheet });
+          return pollReply({ outcome });
+        },
+      }),
+    },
+  };
+}
+
+export default createPickerHandlers();

package/google-workspace/ui/picker.html

@@ -0,0 +1,17 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Choose spreadsheet</title>
+<!-- Static and secret-free: served without credentials. Start data arrives in the host's init message. -->
+<link rel="stylesheet" href="panel.css">
+<script type="module" src="picker.mjs"></script>
+</head>
+<body>
+<main>
+<h1 class="sr-only">Choose spreadsheet</h1>
+<div id="app" aria-live="polite"><p class="muted">Loading…</p></div>
+</main>
+</body>
+</html>

package/google-workspace/ui/picker.mjs

@@ -0,0 +1,88 @@
+/**
+ * @file The "Choose spreadsheet" panel in the browser: one button that runs the Picker flow, and the
+ * list of spreadsheets already chosen (metadata the server verified and saved). Their ids are what a
+ * person gives chat or the form-destination panel; a pasted link grants nothing.
+ */
+import { connectToHost, failureText, h, notice, show, tip } from './dom.mjs';
+import { chooseSpreadsheet } from './picker-flow.mjs';
+import { CANCELLED_TEXT, pickerIntro, selectedText } from './picker-view.mjs';
+
+let client;
+let app;
+let status;
+/** 'info' while choosing or after a choice, 'error' after a failure (the status line's colour). */
+let statusTone;
+let waiting;
+let stopRequested;
+let picked;
+
+function render(bootstrap) {
+  const ready = bootstrap !== undefined && bootstrap.mode !== 'unavailable';
+  // Ready: the intro is the heading's explanation and Choose sits in the header; otherwise the
+  // reason it is unavailable is the visible notice.
+  show(app,
+    ready ? null : h('p', { class: 'notice warn intro' }, [pickerIntro({ bootstrap })]),
+    status ? notice({ text: status, tone: statusTone }) : null,
+    h('section', { class: 'card', 'aria-labelledby': 'picked-heading' }, [
+      h('div', { class: 'head' }, [
+        h('h2', { id: 'picked-heading' }, ['Chosen spreadsheets']),
+        ready ? tip('About choosing a spreadsheet', pickerIntro({ bootstrap }), { bodyClass: 'intro' }) : null,
+        ready ? h('div', { class: 'actions end' }, [
+          h('button', { type: 'button', class: 'primary', disabled: waiting, onClick: () => choose(bootstrap) }, ['Choose spreadsheet']),
+          waiting && bootstrap.mode === 'system-browser' ? h('button', { type: 'button', onClick: () => { stopRequested = true; status = 'Stopping…'; render(bootstrap); } }, ['Stop waiting']) : null,
+        ]) : null,
+      ]),
+      picked.length === 0 ? h('p', { class: 'muted empty' }, ['None yet.']) : h('ul', { class: 'rows' }, picked.map((sheet) => h('li', { class: 'sheet' }, [
+        h('strong', {}, [sheet.title]), ' ', h('code', {}, [sheet.spreadsheetId]),
+      ]))),
+    ]));
+}
+
+async function refresh(bootstrap) {
+  picked = (await client.call({ action: 'list-picked', payload: {} })).spreadsheets;
+  render(bootstrap);
+}
+
+async function choose(bootstrap) {
+  waiting = true;
+  stopRequested = false;
+  status = '';
+  statusTone = 'info';
+  render(bootstrap);
+  try {
+    // The Choose button stays disabled while waiting; "Stop waiting" stays usable.
+    const chosen = await chooseSpreadsheet({ client, bootstrap, onStatus: (text) => { status = text; render(bootstrap); }, stopped: () => stopRequested });
+    if (chosen) status = selectedText({ spreadsheet: chosen });
+    else status ||= CANCELLED_TEXT;
+  } catch (error) {
+    status = failureText(error);
+    statusTone = 'error';
+  }
+  waiting = false;
+  // A failed refresh must still re-render: the last render showed Choose disabled (waiting).
+  await refresh(bootstrap).catch((error) => { status = failureText(error); statusTone = 'error'; render(bootstrap); });
+}
+
+/**
+ * Starts the panel in a frame: connects to the host and lists the chosen spreadsheets once the host's
+ * init arrives. Exported so a test can start a fresh panel (fresh state) in its own jsdom window; the
+ * last line starts the real one.
+ * @param {{ window: Window, document: Document }} required
+ */
+export function initPickerPanel(required) {
+  client = connectToHost({ window: required.window });
+  app = required.document.getElementById('app');
+  status = '';
+  statusTone = 'info';
+  waiting = false;
+  stopRequested = false;
+  picked = [];
+  client.ready.then(load);
+}
+
+/** The first list; a failure the host calls retryable offers "Try again" (another list). */
+function load() {
+  return refresh(client.bootstrap()).catch((error) => show(app, notice({ text: failureText(error), retry: error?.retryable === true ? load : undefined })));
+}
+
+initPickerPanel({ window, document });

package/google-workspace/ui/surface-client.mjs

@@ -0,0 +1,227 @@
+// Verbatim copy of @jini-ai/agent-plugins dist/admin-surfaces/surface-client.js (Jini db1e99fb + host theme tokens + frame height).
+// The surface is plain static files served without credentials, so it carries its own copy of the
+// self-contained protocol client instead of importing the package; refresh it when the protocol changes.
+/**
+ * @file The surface-side half of the admin-surface message protocol, for a plugin's own UI.
+ *
+ * Self-contained on purpose (no imports): a plugin's surface is plain static files, so it may import
+ * this module from the package or copy the compiled file next to its entry. The constants repeat
+ * `./protocol.ts`; the vertical-slice test proves the two still agree.
+ *
+ * Trust rules it applies: it accepts init only from its parent window (once), learns the host's
+ * origin from that init and posts only to that origin (never "*"), and accepts a response only from
+ * the parent, from that origin, for this mount, for a request it still has pending, in a valid shape.
+ *
+ * Theme: the host may send its design tokens with init and again in `theme` messages (`./theme.ts`).
+ * The client applies the `--jini-*` ones with a safe value as custom properties on the surface's root
+ * element (CSSOM `setProperty`, which a CSP without 'unsafe-inline' allows), plus `color-scheme` and
+ * `data-jini-scheme`, so the surface's own stylesheet can follow the admin's look and light/dark mode.
+ */
+const PROTOCOL = 'jini.admin-surface';
+const VERSION = 1;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const THEME_TOKEN = /^--jini-[a-z0-9-]{1,60}$/;
+const UNSAFE_THEME_VALUE = /url\(|image\(|image-set\(|[;{}<>\\@]/i;
+const MAX_THEME_TOKENS = 100;
+/** Rejection value of `call` when the host refused the action or the request timed out. */
+export class AdminSurfaceCallError extends Error {
+    code;
+    retryable;
+    constructor(required) {
+        super(required.message);
+        this.name = 'AdminSurfaceCallError';
+        this.code = required.code;
+        this.retryable = required.retryable;
+    }
+}
+function isMessage(data, kind) {
+    if (typeof data !== 'object' || data === null)
+        return false;
+    const message = data;
+    return message.protocol === PROTOCOL && message.version === VERSION && message.kind === kind;
+}
+function isFailure(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const error = value;
+    return typeof error.code === 'string' && typeof error.message === 'string' && typeof error.retryable === 'boolean';
+}
+/** The host's theme with every unknown name or unsafe value dropped; undefined when it is not a theme. */
+function acceptedTheme(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const { scheme, tokens } = value;
+    if ((scheme !== 'light' && scheme !== 'dark') || typeof tokens !== 'object' || tokens === null)
+        return undefined;
+    const safe = Object.entries(tokens).slice(0, MAX_THEME_TOKENS).filter(([name, token]) => {
+        if (!THEME_TOKEN.test(name) || typeof token !== 'string') return false;
+        return token.length > 0 && token.length <= 200 && !UNSAFE_THEME_VALUE.test(token);
+    });
+    return { scheme, tokens: Object.fromEntries(safe) };
+}
+/** The browser root when there is a document (none in a server-side test). */
+function documentRoot() {
+    const doc = globalThis.document;
+    return doc?.documentElement ?? null;
+}
+/**
+ * The browser's size source: the body's height including what overflows it (an open toggletip), re-read
+ * on resize, DOM changes, hover and focus (hover/focus can show a CSS-only tooltip). Null without a DOM.
+ */
+function documentSize() {
+    const scope = globalThis;
+    const body = scope.document?.body;
+    if (!body || !scope.ResizeObserver || !scope.MutationObserver)
+        return null;
+    const { ResizeObserver: Resize, MutationObserver: Mutation } = scope;
+    return (onHeight) => {
+        const measure = () => {
+            const style = getComputedStyle(body);
+            // scrollHeight is rounded to whole pixels; the box height keeps the fraction, which would
+            // otherwise leave a 1px inner scrollbar.
+            const content = Math.max(body.scrollHeight, body.getBoundingClientRect().height);
+            onHeight(Math.ceil(content + parseFloat(style.marginTop || '0') + parseFloat(style.marginBottom || '0')));
+        };
+        const resize = new Resize(measure);
+        const mutation = new Mutation(measure);
+        resize.observe(body);
+        mutation.observe(body, { subtree: true, childList: true, attributes: true, characterData: true });
+        body.addEventListener('mouseover', measure);
+        body.addEventListener('focusin', measure);
+        measure();
+        return () => { resize.disconnect(); mutation.disconnect(); body.removeEventListener('mouseover', measure); body.removeEventListener('focusin', measure); };
+    };
+}
+/** A response has `ok: true` with a result, or `ok: false` with a well-formed failure. */
+function isWellFormedResponse(message) {
+    return message.ok === true ? Object.hasOwn(message, 'result') : message.ok === false && isFailure(message.error);
+}
+/**
+ * Connects a surface to its host. In a browser:
+ * `createAdminSurfaceClient({ parent: window.parent, listen: (h) => { addEventListener('message', h); return () => removeEventListener('message', h); } })`.
+ * @param optional.timeoutMs - How long `call` waits for a response before rejecting with `timeout`.
+ * @complexity O(1) per message.
+ */
+export function createAdminSurfaceClient(required, optional = {}) {
+    const timeoutMs = optional.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const nowMs = optional.nowMs ?? Date.now;
+    const pending = new Map();
+    let init;
+    let nextRequest = 0;
+    // The Promise executor runs synchronously, so `resolveReady` is assigned before anything can call it.
+    let resolveReady;
+    const ready = new Promise((resolve) => { resolveReady = resolve; });
+    const themeRoot = optional.themeRoot === undefined ? documentRoot() : optional.themeRoot;
+    let currentTheme;
+    const size = optional.size === undefined ? documentSize() : optional.size;
+    let stopSize;
+    let lastHeight = -1;
+    /** Tells the host this surface's height (only when it changed), so the frame fits its content. */
+    function reportHeight(height) {
+        if (init === undefined || !Number.isFinite(height) || height === lastHeight)
+            return;
+        lastHeight = height;
+        required.parent.postMessage({ protocol: PROTOCOL, version: VERSION, kind: 'resize', mountId: init.mountId, height }, init.origin);
+    }
+    /** Replaces the applied tokens: a token the new theme no longer sends falls back to the surface's CSS. */
+    function applyTheme(value) {
+        const next = acceptedTheme(value);
+        if (next === undefined)
+            return;
+        if (themeRoot !== null) {
+            for (const name of Object.keys(currentTheme?.tokens ?? {}))
+                if (!(name in next.tokens))
+                    themeRoot.style.removeProperty(name);
+            for (const [name, token] of Object.entries(next.tokens))
+                themeRoot.style.setProperty(name, token);
+            themeRoot.style.setProperty('color-scheme', next.scheme);
+            themeRoot.setAttribute('data-jini-scheme', next.scheme);
+        }
+        currentTheme = next;
+    }
+    function onInit(event, data) {
+        if (init !== undefined || typeof data.mountId !== 'string')
+            return;
+        init = { mountId: data.mountId, origin: event.origin, bootstrap: data.bootstrap };
+        applyTheme(data.theme);
+        stopSize = size?.(reportHeight);
+        resolveReady();
+    }
+    function onResponse(event, data) {
+        if (event.origin !== init?.origin || data.mountId !== init.mountId || typeof data.requestId !== 'string')
+            return;
+        const waiting = pending.get(data.requestId);
+        if (waiting === undefined || !isWellFormedResponse(data))
+            return;
+        pending.delete(data.requestId);
+        clearTimeout(waiting.timer);
+        if (data.ok === true)
+            waiting.resolve(data.result);
+        else
+            waiting.reject(new AdminSurfaceCallError(data.error));
+    }
+    const unsubscribe = required.listen((event) => {
+        if (event.source !== required.parent)
+            return;
+        if (isMessage(event.data, 'init'))
+            onInit(event, event.data);
+        else if (isMessage(event.data, 'theme')) {
+            if (event.origin === init?.origin && event.data.mountId === init.mountId)
+                applyTheme(event.data.theme);
+        }
+        else if (isMessage(event.data, 'action-response'))
+            onResponse(event, event.data);
+        else {
+            // Ignore message kinds outside the admin-surface protocol.
+        }
+    });
+    /** Posts one request of `kind` to the host origin and waits for its `action-response`. */
+    async function send(kind, fields) {
+        if (init === undefined)
+            await ready;
+        const { mountId, origin } = init;
+        nextRequest += 1;
+        const requestId = `r${nextRequest}`;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                pending.delete(requestId);
+                reject(new AdminSurfaceCallError({ code: 'timeout', message: 'The host did not answer in time. Try again.', retryable: true }));
+            }, timeoutMs);
+            pending.set(requestId, { resolve, reject, timer });
+            required.parent.postMessage({ protocol: PROTOCOL, version: VERSION, kind, mountId, requestId, ...fields }, origin);
+        });
+    }
+    /** Asks the host to run one declared action; resolves with its result. */
+    function call(input) {
+        return send('action-request', { action: input.action, payload: input.payload });
+    }
+    /** Asks the host to open `url` outside the sandbox; only https links on the surface's declared
+     * `linkOrigins` open, and the host decides how (new tab, system browser). Rejects with the host's refusal. */
+    async function openLink(input) {
+        await send('open-link', { url: input.url });
+    }
+    /** The bootstrap `data` the host sent with init, or `undefined` once it has expired (or none was sent). */
+    function bootstrap() {
+        const envelope = init?.bootstrap;
+        if (typeof envelope !== 'object' || envelope === null)
+            return undefined;
+        const { expiresAt, data } = envelope;
+        return typeof expiresAt === 'number' && nowMs() < expiresAt ? data : undefined;
+    }
+    /** The host's theme as applied, or `undefined` when the host sent none. */
+    function theme() {
+        return currentTheme;
+    }
+    /** Stops listening and rejects every pending call. */
+    function close() {
+        unsubscribe();
+        stopSize?.();
+        for (const [requestId, waiting] of pending) {
+            clearTimeout(waiting.timer);
+            waiting.reject(new AdminSurfaceCallError({ code: 'closed', message: 'The surface was closed before the host answered.', retryable: false }));
+            pending.delete(requestId);
+        }
+    }
+    return { ready, call, openLink, bootstrap, theme, close };
+}
+//# sourceMappingURL=surface-client.js.map

package/higgsfield-media/mcp.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {
+    "higgsfield": {
+      "type": "streamable-http",
+      "url": "https://mcp.higgsfield.ai/mcp"
+    }
+  }
+}

package/higgsfield-media/plugin.json

@@ -0,0 +1,109 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "higgsfield-media",
+  "version": "1.1.0",
+  "description": "Generates images or video through Higgsfield's hosted MCP server, follows asynchronous jobs, then imports the returned asset into this site's Media library. Connect with agent_plugin_connect and the person's browser sign-in, never an API key. Discover this account's current tools, schemas and model entitlements; the worked model and plan examples are historical, not guarantees. Covers operator write grants, polling without sync:true, connection recovery and media_import_from_url.",
+  "author": "Tovu",
+  "license": "Apache-2.0",
+  "keywords": [
+    "higgsfield",
+    "image",
+    "image-generation",
+    "generate",
+    "media",
+    "media-library",
+    "import",
+    "external-mcp",
+    "federation",
+    "mcp",
+    "oauth",
+    "async",
+    "job-status",
+    "polling",
+    "cdn",
+    "photo",
+    "photograph",
+    "picture",
+    "illustration",
+    "art",
+    "artwork",
+    "visual",
+    "graphic",
+    "connect",
+    "connection",
+    "sign-in",
+    "login",
+    "authorize",
+    "authentication",
+    "credential",
+    "setup",
+    "onboarding",
+    "getting-started",
+    "api-key",
+    "text-to-image",
+    "higgsfield-media",
+    "media:image",
+    "media:video"
+  ],
+  "extensions": {
+    "tovu": {
+      "vendorAliases": ["higgsfield"],
+      "summary": "Makes AI images with Higgsfield and saves them to your Media library. You sign in to Higgsfield once in your browser.",
+      "mcpServers": {
+        "higgsfield": {
+          "tovuAuthMode": "oauth",
+          "tovuDefaultTools": {
+            "allow": [
+              "generate_image",
+              "generate_video",
+              "models_explore",
+              "job_status",
+              "jobs_wait",
+              "show_generations",
+              "reveal_generation",
+              "show_generation_by_ids"
+            ],
+            "write": [
+              "generate_image",
+              "generate_video",
+              "reveal_generation"
+            ],
+            "read": [
+              "models_explore",
+              "job_status",
+              "jobs_wait",
+              "show_generations",
+              "show_generation_by_ids"
+            ]
+          }
+        }
+      },
+      "id": "tovu/higgsfield-media",
+      "provides": [
+        "media:image",
+        "media:video"
+      ],
+      "credentialCards": [
+        {
+          "target": "higgsfield-media",
+          "title": "Connect Higgsfield",
+          "label": "Higgsfield account",
+          "category": "media",
+          "intro": "Connect Higgsfield to generate images or video and save the finished files in this site’s Media library.",
+          "usedFor": [
+            "Checks available image and video models and generation progress",
+            "Generates images and videos using your account's credits"
+          ],
+          "keyHint": "Browser sign-in only; this connection does not accept a pasted API key.",
+          "saveKind": "oauth",
+          "permissions": "Signing in turns on model discovery, job status and generation. Generation uses the models and credits available on your account. You can turn any tool off later in the connection settings. Review the permissions on the sign-in page.",
+          "baseUrl": "https://mcp.higgsfield.ai"
+        }
+      ],
+      "toolKeywords": {
+        "external_mcp_list": "higgsfield",
+        "external_mcp_save": "higgsfield"
+      }
+    }
+  }
+}