@agent-native/core 0.15.12 → 0.16.0

package/dist/client/host-bridge.js

@@ -0,0 +1,745 @@
+export const AGENT_NATIVE_HOST_BRIDGE_VERSION = "0.1.0";
+export const AGENT_NATIVE_HOST_MESSAGE_TYPES = {
+    READY: "agentNative.host.ready",
+    INIT: "agentNative.host.init",
+    GET_CONTEXT: "agentNative.host.getContext",
+    CONTEXT: "agentNative.host.context",
+    AUTH: "agentNative.host.auth",
+    LIST_ACTIONS: "agentNative.host.listActions",
+    ACTIONS: "agentNative.host.actions",
+    RUN_ACTION: "agentNative.host.runAction",
+    ACTION_RESULT: "agentNative.host.actionResult",
+    COMMAND: "agentNative.host.command",
+    COMMAND_RESULT: "agentNative.host.commandResult",
+    ERROR: "agentNative.host.error",
+};
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeOrigin(value) {
+    if (!value)
+        return null;
+    if (value === "*")
+        return "*";
+    try {
+        return new URL(value).origin;
+    }
+    catch {
+        return null;
+    }
+}
+function getWindowFromSource(source) {
+    if (!source || !("postMessage" in source))
+        return null;
+    return source;
+}
+function messageError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+function serializeForMessage(value, label) {
+    if (value === undefined)
+        return value;
+    try {
+        return JSON.parse(JSON.stringify(value));
+    }
+    catch {
+        throw new Error(`${label} must be JSON-serializable`);
+    }
+}
+function requestId() {
+    return `host-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function sessionId() {
+    return `session-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function createHostSession(session) {
+    const now = new Date().toISOString();
+    const base = typeof session === "string"
+        ? { id: session }
+        : session && typeof session === "object"
+            ? session
+            : {};
+    return {
+        id: base.id || sessionId(),
+        connectedAt: base.connectedAt || now,
+        url: base.url ||
+            (typeof window !== "undefined" ? window.location.href : undefined),
+        ...base,
+    };
+}
+function attachSession(context, session) {
+    return serializeForMessage({
+        ...context,
+        session: {
+            ...session,
+            ...(context.session ?? {}),
+        },
+    }, "Host context");
+}
+function truncate(value, maxLength) {
+    if (!value)
+        return undefined;
+    const normalized = value.replace(/\s+/g, " ").trim();
+    if (normalized.length <= maxLength)
+        return normalized;
+    return `${normalized.slice(0, Math.max(0, maxLength - 1))}…`;
+}
+function resolveSnapshotRoot(root) {
+    if (typeof document === "undefined")
+        return null;
+    if (typeof root === "function")
+        return root() ?? null;
+    return root ?? document.body ?? document.documentElement;
+}
+function readElementText(root) {
+    if (typeof document === "undefined")
+        return root.textContent ?? undefined;
+    try {
+        const showText = typeof NodeFilter === "undefined" ? 4 : NodeFilter.SHOW_TEXT;
+        const walker = document.createTreeWalker(root, showText);
+        const parts = [];
+        while (walker.nextNode()) {
+            const text = walker.currentNode.textContent?.trim();
+            if (text)
+                parts.push(text);
+        }
+        return parts.join(" ");
+    }
+    catch {
+        return root.textContent ?? undefined;
+    }
+}
+function defaultContext() {
+    if (typeof window === "undefined")
+        return {};
+    return {
+        url: window.location.href,
+        title: typeof document !== "undefined" ? document.title : undefined,
+        route: {
+            pathname: window.location.pathname,
+            search: window.location.search,
+            hash: window.location.hash,
+        },
+    };
+}
+export function readAgentNativeScreenContext(options = {}) {
+    const base = defaultContext();
+    if (typeof window === "undefined")
+        return base;
+    const root = resolveSnapshotRoot(options.root);
+    const selectionText = typeof window.getSelection === "function"
+        ? window.getSelection()?.toString().trim() || undefined
+        : undefined;
+    const maxTextLength = options.maxTextLength ?? 6000;
+    const maxHtmlLength = options.maxHtmlLength ?? 20000;
+    const includeVisibleText = options.includeVisibleText ?? true;
+    const includeDomHtml = options.includeDomHtml ?? false;
+    const selection = selectionText
+        ? { ...(base.selection ?? {}), type: "text", text: selectionText }
+        : base.selection;
+    return {
+        ...base,
+        selection,
+        screen: {
+            url: base.url,
+            title: base.title,
+            route: base.route,
+            selection,
+            visibleText: includeVisibleText && root
+                ? truncate(readElementText(root), maxTextLength)
+                : undefined,
+            html: includeDomHtml && root
+                ? truncate(root.outerHTML ?? undefined, maxHtmlLength)
+                : undefined,
+            viewport: {
+                width: window.innerWidth,
+                height: window.innerHeight,
+                scrollX: window.scrollX,
+                scrollY: window.scrollY,
+            },
+        },
+    };
+}
+async function resolveHostContext(getContext) {
+    const base = defaultContext();
+    const custom = getContext ? await getContext() : undefined;
+    if (!custom)
+        return serializeForMessage(base, "Host context");
+    const merged = {
+        ...base,
+        ...custom,
+        route: base.route || custom.route
+            ? { ...(base.route ?? {}), ...(custom.route ?? {}) }
+            : undefined,
+    };
+    return serializeForMessage(merged, "Host context");
+}
+async function resolveHostAuth(auth) {
+    const value = typeof auth === "function" ? await auth() : auth;
+    if (!value)
+        return undefined;
+    const payload = typeof value === "string" ? { token: value } : value;
+    if (!payload || typeof payload !== "object")
+        return undefined;
+    const headers = payload.headers && typeof payload.headers === "object"
+        ? Object.fromEntries(Object.entries(payload.headers).map(([key, val]) => [
+            key,
+            String(val),
+        ]))
+        : undefined;
+    return serializeForMessage({ ...payload, headers }, "Host auth payload");
+}
+async function resolveClientActions(actions) {
+    const value = typeof actions === "function" ? await actions() : actions;
+    return Array.isArray(value) ? value : [];
+}
+function toActionManifest(action) {
+    if (!action?.name || !action.description)
+        return null;
+    const { run: _run, ...manifest } = action;
+    return serializeForMessage({
+        source: "client",
+        availability: "browser-session",
+        ...manifest,
+        schema: manifest.schema ?? manifest.parameters,
+    }, "Client action manifest");
+}
+async function resolveActionManifest(actions) {
+    const resolved = await resolveClientActions(actions);
+    return resolved
+        .map(toActionManifest)
+        .filter(Boolean);
+}
+async function findClientAction(actions, name) {
+    const resolved = await resolveClientActions(actions);
+    return resolved.find((action) => action.name === name);
+}
+function dispatchHostEvent(type, payload) {
+    if (typeof window === "undefined")
+        return { dispatched: true };
+    window.dispatchEvent(new CustomEvent(type, {
+        detail: payload,
+    }));
+    return { dispatched: true };
+}
+export const defaultAgentNativeHostCommands = {
+    navigate: ({ payload }) => dispatchHostEvent("agentNative:navigate", payload),
+    refreshData: ({ payload }) => dispatchHostEvent("agentNative:refresh-data", payload),
+    "refresh-data": ({ payload }) => dispatchHostEvent("agentNative:refresh-data", payload),
+    remountView: ({ payload }) => dispatchHostEvent("agentNative:remount-view", payload),
+    "remount-view": ({ payload }) => dispatchHostEvent("agentNative:remount-view", payload),
+    hardReload: () => {
+        if (typeof window !== "undefined")
+            window.location.reload();
+        return { reloading: true };
+    },
+    "hard-reload": () => {
+        if (typeof window !== "undefined")
+            window.location.reload();
+        return { reloading: true };
+    },
+    openResource: ({ payload }) => dispatchHostEvent("agentNative:open-resource", payload),
+    "open-resource": ({ payload }) => dispatchHostEvent("agentNative:open-resource", payload),
+};
+function isIncomingHostMessage(value) {
+    if (!isRecord(value))
+        return false;
+    return (value.type === AGENT_NATIVE_HOST_MESSAGE_TYPES.READY ||
+        value.type === AGENT_NATIVE_HOST_MESSAGE_TYPES.GET_CONTEXT ||
+        value.type === AGENT_NATIVE_HOST_MESSAGE_TYPES.LIST_ACTIONS ||
+        value.type === AGENT_NATIVE_HOST_MESSAGE_TYPES.RUN_ACTION ||
+        value.type === AGENT_NATIVE_HOST_MESSAGE_TYPES.COMMAND);
+}
+export function createAgentNativeHostBridge(options) {
+    let targetWindow = options.targetWindow ?? null;
+    let started = false;
+    const allowedOrigin = normalizeOrigin(options.agentOrigin);
+    const targetOrigin = allowedOrigin && allowedOrigin !== "*" ? allowedOrigin : "*";
+    const session = createHostSession(options.session);
+    function emit(event) {
+        options.onEvent?.(event);
+    }
+    function trusted(event) {
+        if (allowedOrigin &&
+            allowedOrigin !== "*" &&
+            event.origin !== allowedOrigin) {
+            emit({ type: "ignored", reason: "origin", origin: event.origin });
+            return false;
+        }
+        if (targetWindow && event.source !== targetWindow) {
+            emit({ type: "ignored", reason: "source", origin: event.origin });
+            return false;
+        }
+        return true;
+    }
+    function post(message) {
+        if (!targetWindow)
+            return false;
+        targetWindow.postMessage(message, targetOrigin);
+        return true;
+    }
+    async function sendInit(requestId) {
+        const message = {
+            type: AGENT_NATIVE_HOST_MESSAGE_TYPES.INIT,
+            version: AGENT_NATIVE_HOST_BRIDGE_VERSION,
+            requestId,
+        };
+        try {
+            message.session = session;
+            message.context = attachSession(await resolveHostContext(options.getContext), session);
+        }
+        catch (error) {
+            message.contextError = messageError(error).message;
+            emit({ type: "error", requestId, error: messageError(error) });
+        }
+        try {
+            message.auth = await resolveHostAuth(options.auth);
+        }
+        catch (error) {
+            message.authError = messageError(error).message;
+            emit({ type: "error", requestId, error: messageError(error) });
+        }
+        try {
+            message.actions = await resolveActionManifest(options.actions);
+        }
+        catch (error) {
+            message.actionsError = messageError(error).message;
+            emit({ type: "error", requestId, error: messageError(error) });
+        }
+        const sent = post(message);
+        if (sent)
+            emit({ type: "init", requestId });
+        return sent;
+    }
+    async function sendContext(requestId) {
+        try {
+            const context = attachSession(await resolveHostContext(options.getContext), session);
+            const sent = post({
+                type: AGENT_NATIVE_HOST_MESSAGE_TYPES.CONTEXT,
+                ok: true,
+                requestId,
+                context,
+            });
+            if (sent)
+                emit({ type: "context", requestId });
+            return sent;
+        }
+        catch (error) {
+            const err = messageError(error);
+            emit({ type: "error", requestId, error: err });
+            return post({
+                type: AGENT_NATIVE_HOST_MESSAGE_TYPES.CONTEXT,
+                ok: false,
+                requestId,
+                error: err.message,
+            });
+        }
+    }
+    async function sendAuth(requestId) {
+        try {
+            const auth = await resolveHostAuth(options.auth);
+            const sent = post({
+                type: AGENT_NATIVE_HOST_MESSAGE_TYPES.AUTH,
+                ok: true,
+                requestId,
+                auth,
+            });
+            if (sent)
+                emit({ type: "auth", requestId });
+            return sent;
+        }
+        catch (error) {
+            const err = messageError(error);
+            emit({ type: "error", requestId, error: err });
+            return post({
+                type: AGENT_NATIVE_HOST_MESSAGE_TYPES.AUTH,
+                ok: false,
+                requestId,
+                error: err.message,
+            });
+        }
+    }
+    async function sendActions(requestId) {
+        try {
+            const actions = await resolveActionManifest(options.actions);
+            const sent = post({
+                type: AGENT_NATIVE_HOST_MESSAGE_TYPES.ACTIONS,
+                ok: true,
+                requestId,
+                actions,
+            });
+            if (sent)
+                emit({ type: "actions", requestId, count: actions.length });
+            return sent;
+        }
+        catch (error) {
+            const err = messageError(error);
+            emit({ type: "error", requestId, error: err });
+            return post({
+                type: AGENT_NATIVE_HOST_MESSAGE_TYPES.ACTIONS,
+                ok: false,
+                requestId,
+                error: err.message,
+            });
+        }
+    }
+    async function runHostCommand(command, payload, requestId, event) {
+        const handler = options.commands?.[command] ?? defaultAgentNativeHostCommands[command];
+        if (!handler) {
+            throw new Error(`No host command handler registered for "${command}"`);
+        }
+        return handler({
+            command,
+            payload,
+            requestId,
+            origin: event.origin,
+        }, event);
+    }
+    function needsApproval(action) {
+        return (action.destructive === true ||
+            action.requiresApproval === true ||
+            typeof action.requiresApproval === "object" ||
+            Boolean(action.approval));
+    }
+    function approvalConfig(action) {
+        if (action.approval)
+            return action.approval;
+        return typeof action.requiresApproval === "object"
+            ? action.requiresApproval
+            : undefined;
+    }
+    async function assertActionApproved(action, args, context, requestId, event) {
+        if (!needsApproval(action))
+            return;
+        const manifest = toActionManifest(action);
+        const response = await runHostCommand("requestApproval", {
+            action: manifest,
+            args,
+            context,
+            session,
+            approval: approvalConfig(action),
+        }, requestId, event);
+        const approved = response === true ||
+            (isRecord(response) &&
+                (response.approved === true || response.ok === true));
+        if (!approved)
+            throw new Error(`Client action "${action.name}" was not approved`);
+    }
+    async function handleAction(message, event) {
+        if (message.type !== AGENT_NATIVE_HOST_MESSAGE_TYPES.RUN_ACTION)
+            return;
+        const name = typeof message.name === "string" ? message.name : "";
+        const requestId = message.requestId;
+        const args = "args" in message ? message.args : message.payload;
+        try {
+            if (!name)
+                throw new Error("Missing client action name");
+            const action = await findClientAction(options.actions, name);
+            if (!action) {
+                throw new Error(`No client action registered for "${name}"`);
+            }
+            const context = attachSession(await resolveHostContext(options.getContext), session);
+            await assertActionApproved(action, args, context, requestId, event);
+            emit({ type: "action", name, requestId, origin: event.origin });
+            const result = await action.run(args, {
+                requestId,
+                origin: event.origin,
+                context,
+                session,
+                event,
+                refresh: (payload) => runHostCommand("refreshData", payload, requestId, event),
+                command: (command, payload) => runHostCommand(command, payload, requestId, event),
+            });
+            post({
+                type: AGENT_NATIVE_HOST_MESSAGE_TYPES.ACTION_RESULT,
+                ok: true,
+                requestId,
+                result: serializeForMessage(result, "Client action result"),
+            });
+        }
+        catch (error) {
+            const err = messageError(error);
+            emit({ type: "error", requestId, error: err, origin: event.origin });
+            post({
+                type: AGENT_NATIVE_HOST_MESSAGE_TYPES.ACTION_RESULT,
+                ok: false,
+                requestId,
+                error: err.message,
+            });
+        }
+    }
+    async function handleCommand(message, event) {
+        if (message.type !== AGENT_NATIVE_HOST_MESSAGE_TYPES.COMMAND)
+            return;
+        const command = typeof message.command === "string" ? message.command : "";
+        const requestId = message.requestId;
+        try {
+            if (!command)
+                throw new Error("Missing host command");
+            emit({ type: "command", command, requestId, origin: event.origin });
+            const result = await runHostCommand(command, message.payload, requestId, event);
+            post({
+                type: AGENT_NATIVE_HOST_MESSAGE_TYPES.COMMAND_RESULT,
+                ok: true,
+                requestId,
+                result: serializeForMessage(result, "Host command result"),
+            });
+        }
+        catch (error) {
+            const err = messageError(error);
+            emit({ type: "error", requestId, error: err, origin: event.origin });
+            post({
+                type: AGENT_NATIVE_HOST_MESSAGE_TYPES.COMMAND_RESULT,
+                ok: false,
+                requestId,
+                error: err.message,
+            });
+        }
+    }
+    function onMessage(event) {
+        const message = event.data;
+        if (!isIncomingHostMessage(message))
+            return;
+        if (!trusted(event))
+            return;
+        const sourceWindow = getWindowFromSource(event.source);
+        if (!targetWindow && sourceWindow)
+            targetWindow = sourceWindow;
+        if (message.type === AGENT_NATIVE_HOST_MESSAGE_TYPES.READY) {
+            emit({
+                type: "ready",
+                requestId: message.requestId,
+                origin: event.origin,
+            });
+            void sendInit(message.requestId);
+        }
+        else if (message.type === AGENT_NATIVE_HOST_MESSAGE_TYPES.GET_CONTEXT) {
+            void sendContext(message.requestId);
+        }
+        else if (message.type === AGENT_NATIVE_HOST_MESSAGE_TYPES.LIST_ACTIONS) {
+            void sendActions(message.requestId);
+        }
+        else if (message.type === AGENT_NATIVE_HOST_MESSAGE_TYPES.RUN_ACTION) {
+            void handleAction(message, event);
+        }
+        else if (message.type === AGENT_NATIVE_HOST_MESSAGE_TYPES.COMMAND) {
+            void handleCommand(message, event);
+        }
+        else {
+            emit({ type: "ignored", reason: "message", origin: event.origin });
+        }
+    }
+    const bridge = {
+        start() {
+            if (started || typeof window === "undefined")
+                return bridge;
+            window.addEventListener("message", onMessage);
+            started = true;
+            return bridge;
+        },
+        stop() {
+            if (!started || typeof window === "undefined")
+                return;
+            window.removeEventListener("message", onMessage);
+            started = false;
+        },
+        setTargetWindow(nextTargetWindow) {
+            targetWindow = nextTargetWindow;
+        },
+        post,
+        sendInit,
+        sendContext,
+        refreshContext: sendContext,
+        sendAuth,
+        sendActions,
+    };
+    return bridge;
+}
+function getFrameTargetWindow(targetWindow) {
+    if (targetWindow)
+        return targetWindow;
+    if (typeof window === "undefined")
+        return null;
+    try {
+        return window.parent !== window ? window.parent : window;
+    }
+    catch {
+        return window.parent;
+    }
+}
+function isTrustedHostResponse(event, targetWindow, hostOrigin) {
+    if (event.source !== targetWindow)
+        return false;
+    const origin = normalizeOrigin(hostOrigin);
+    if (origin && origin !== "*" && event.origin !== origin)
+        return false;
+    return true;
+}
+function requestFromHost(message, responseType, pick, options = {}) {
+    return new Promise((resolve, reject) => {
+        const targetWindow = getFrameTargetWindow(options.targetWindow);
+        if (!targetWindow || typeof window === "undefined") {
+            reject(new Error("No host window is available"));
+            return;
+        }
+        const id = typeof message.requestId === "string" ? message.requestId : requestId();
+        const timeoutMs = options.timeoutMs ?? 3000;
+        let settled = false;
+        const cleanup = () => {
+            window.removeEventListener("message", onMessage);
+            clearTimeout(timer);
+        };
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            fn();
+        };
+        const timer = setTimeout(() => {
+            finish(() => reject(new Error("Timed out waiting for host response")));
+        }, timeoutMs);
+        function onMessage(event) {
+            if (!isTrustedHostResponse(event, targetWindow, options.hostOrigin)) {
+                return;
+            }
+            if (!isRecord(event.data))
+                return;
+            if (event.data.type !== responseType)
+                return;
+            if (event.data.requestId !== id)
+                return;
+            const response = pick(event.data);
+            if (response.ok === true) {
+                finish(() => resolve(response.value));
+            }
+            else {
+                const error = response.error;
+                finish(() => reject(error));
+            }
+        }
+        window.addEventListener("message", onMessage);
+        targetWindow.postMessage({ ...message, requestId: id }, options.targetOrigin ?? options.hostOrigin ?? "*");
+    });
+}
+export function announceAgentNativeFrameReady(options = {}) {
+    const targetWindow = getFrameTargetWindow(options.targetWindow);
+    if (!targetWindow)
+        return;
+    targetWindow.postMessage({
+        type: AGENT_NATIVE_HOST_MESSAGE_TYPES.READY,
+        version: AGENT_NATIVE_HOST_BRIDGE_VERSION,
+        requestId: requestId(),
+    }, options.targetOrigin ?? options.hostOrigin ?? "*");
+}
+export function requestAgentNativeHostContext(options = {}) {
+    return requestFromHost({ type: AGENT_NATIVE_HOST_MESSAGE_TYPES.GET_CONTEXT }, AGENT_NATIVE_HOST_MESSAGE_TYPES.CONTEXT, (message) => {
+        if (message.ok === false) {
+            return {
+                ok: false,
+                error: new Error(typeof message.error === "string"
+                    ? message.error
+                    : "Host context request failed"),
+            };
+        }
+        return {
+            ok: true,
+            value: (message.context ?? {}),
+        };
+    }, options);
+}
+export function requestAgentNativeHostActions(options = {}) {
+    return requestFromHost({ type: AGENT_NATIVE_HOST_MESSAGE_TYPES.LIST_ACTIONS }, AGENT_NATIVE_HOST_MESSAGE_TYPES.ACTIONS, (message) => {
+        if (message.ok === false) {
+            return {
+                ok: false,
+                error: new Error(typeof message.error === "string"
+                    ? message.error
+                    : "Host actions request failed"),
+            };
+        }
+        return {
+            ok: true,
+            value: Array.isArray(message.actions)
+                ? message.actions
+                : [],
+        };
+    }, options);
+}
+export function runAgentNativeHostAction(name, args, options = {}) {
+    return requestFromHost({
+        type: AGENT_NATIVE_HOST_MESSAGE_TYPES.RUN_ACTION,
+        name,
+        args,
+    }, AGENT_NATIVE_HOST_MESSAGE_TYPES.ACTION_RESULT, (message) => {
+        if (message.ok === false) {
+            return {
+                ok: false,
+                error: new Error(typeof message.error === "string"
+                    ? message.error
+                    : "Host action failed"),
+            };
+        }
+        return { ok: true, value: message.result };
+    }, options);
+}
+export function sendAgentNativeHostCommand(command, payload, options = {}) {
+    return requestFromHost({
+        type: AGENT_NATIVE_HOST_MESSAGE_TYPES.COMMAND,
+        command,
+        payload,
+    }, AGENT_NATIVE_HOST_MESSAGE_TYPES.COMMAND_RESULT, (message) => {
+        if (message.ok === false) {
+            return {
+                ok: false,
+                error: new Error(typeof message.error === "string"
+                    ? message.error
+                    : "Host command failed"),
+            };
+        }
+        return { ok: true, value: message.result };
+    }, options);
+}
+export function onAgentNativeHostInit(handler, options = {}) {
+    if (typeof window === "undefined")
+        return () => { };
+    const targetWindow = getFrameTargetWindow(options.targetWindow);
+    if (!targetWindow)
+        return () => { };
+    function onMessage(event) {
+        if (!isTrustedHostResponse(event, targetWindow, options.hostOrigin)) {
+            return;
+        }
+        if (!isRecord(event.data))
+            return;
+        if (event.data.type !== AGENT_NATIVE_HOST_MESSAGE_TYPES.INIT)
+            return;
+        handler({
+            version: typeof event.data.version === "string" ? event.data.version : undefined,
+            context: isRecord(event.data.context)
+                ? event.data.context
+                : undefined,
+            auth: isRecord(event.data.auth)
+                ? event.data.auth
+                : undefined,
+            actions: Array.isArray(event.data.actions)
+                ? event.data.actions
+                : undefined,
+            session: isRecord(event.data.session)
+                ? event.data.session
+                : undefined,
+            contextError: typeof event.data.contextError === "string"
+                ? event.data.contextError
+                : undefined,
+            authError: typeof event.data.authError === "string"
+                ? event.data.authError
+                : undefined,
+            actionsError: typeof event.data.actionsError === "string"
+                ? event.data.actionsError
+                : undefined,
+        });
+    }
+    window.addEventListener("message", onMessage);
+    return () => window.removeEventListener("message", onMessage);
+}
+//# sourceMappingURL=host-bridge.js.map