toolPreloadBridge.ts

/**
 * Tool Preload Bridge
 *
 * This script runs in each tool's BrowserView before the tool loads.
 * It exposes the toolboxAPI to the tool via contextBridge, providing
 * secure access to PPTB functionality through IPC.
 *
 * This is similar to extension host preload scripts, providing isolated contexts.
 */

import { contextBridge, ipcRenderer } from "electron";
// Reverted to importing centralized channel definitions from single source file.
// Ensure BrowserView preload can resolve this module (see ToolWindowManager sandbox setting).
import {
    CONNECTION_CHANNELS,
    DATAVERSE_CHANNELS,
    EVENT_CHANNELS,
    FILESYSTEM_CHANNELS,
    POWERPLATFORM_CHANNELS,
    SETTINGS_CHANNELS,
    TERMINAL_CHANNELS,
    TOOL_CHANNELS,
    TOOL_WINDOW_CHANNELS,
    UTIL_CHANNELS,
} from "../common/ipc/channels";
import { logInfo } from "../common/logger";
import type { DataverseBatchRequest, EntityRelatedMetadataPath, EntityRelatedMetadataResponse } from "../common/types";

// Tool context received from main process
let toolContext: Record<string, unknown> | null = null;

// Promise that resolves when toolContext is ready
// This prevents race conditions where tool code tries to use the API before context is received
// Pattern: Create a promise and capture its resolve function for later use
let resolveToolContext!: () => void; // Definite assignment assertion - will be set immediately below

// Initialize the promise and capture the resolve function
const toolContextReady = new Promise<void>((resolve) => {
    resolveToolContext = resolve;
});

// Listen for context from main process
ipcRenderer.on("toolbox:context", (event, context) => {
    // Merge new context with existing to preserve all fields
    toolContext = { ...toolContext, ...context };
    logInfo("[ToolPreloadBridge] Received tool context update", {
        toolId: typeof context?.toolId === "string" ? context.toolId : undefined,
        instanceId: typeof context?.instanceId === "string" ? context.instanceId : undefined,
        hasCaller: typeof context?.callerInstanceId === "string",
        hasPrefillData: context?.prefillData !== undefined,
        hasPrimaryConnection: typeof context?.connectionId === "string",
        hasSecondaryConnection: typeof context?.secondaryConnectionId === "string",
    });
    // Resolve the promise so any pending API calls can proceed (only once)
    if (resolveToolContext) {
        resolveToolContext();
        resolveToolContext = null as any; // Only resolve once
    }
});

// Constants for timeout configuration
const TOOL_CONTEXT_TIMEOUT_MS = 10000;
const TOOL_CONTEXT_TIMEOUT_ERROR = "Tool context initialization timed out after 10 seconds. The tool may not have been initialized properly.";

// Helper to wrap a promise with a timeout
function withTimeout<T>(promise: Promise<T>, timeoutMs: number, errorMessage: string): Promise<T> {
    let timeoutHandle: NodeJS.Timeout | undefined;

    const timeoutPromise = new Promise<T>((_, reject) => {
        timeoutHandle = setTimeout(() => {
            timeoutHandle = undefined;
            reject(new Error(errorMessage));
        }, timeoutMs);
    });

    return Promise.race([
        promise.then(
            (result) => {
                if (timeoutHandle) clearTimeout(timeoutHandle);
                return result;
            },
            (error) => {
                if (timeoutHandle) clearTimeout(timeoutHandle);
                throw error;
            },
        ),
        timeoutPromise,
    ]);
}

// Helper to ensure toolContext is ready before proceeding
async function ensureToolContext(): Promise<string> {
    await withTimeout(toolContextReady, TOOL_CONTEXT_TIMEOUT_MS, TOOL_CONTEXT_TIMEOUT_ERROR);
    // After promise resolves, toolContext must be set and have a toolId
    if (!toolContext || typeof toolContext.toolId !== "string") {
        throw new Error("Tool context not initialized properly");
    }
    return toolContext.toolId;
}

async function getToolIdentifiers(): Promise<{ toolId: string; instanceId: string | null }> {
    await withTimeout(toolContextReady, TOOL_CONTEXT_TIMEOUT_MS, TOOL_CONTEXT_TIMEOUT_ERROR);
    if (!toolContext || typeof toolContext.toolId !== "string") {
        throw new Error("Tool context not initialized properly");
    }

    const instanceId = typeof toolContext.instanceId === "string" ? toolContext.instanceId : null;
    return { toolId: toolContext.toolId, instanceId };
}

// Helper to make IPC calls and return promises
function ipcInvoke(channel: string, ...args: unknown[]): Promise<unknown> {
    return ipcRenderer.invoke(channel, ...args);
}

type PowerPlatformCategory =
    | "Analytics"
    | "AppManagement"
    | "Authorization"
    | "Connectivity"
    | "CopilotStudio"
    | "Dynamics"
    | "EnvironmentManagement"
    | "Governance"
    | "Licensing"
    | "PowerApps"
    | "PowerAutomate"
    | "PowerPages"
    | "ResourceQuery"
    | "UserManagement"
    | "WorkflowAgents";

type PowerPlatformMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";

const POWER_PLATFORM_CATEGORIES: PowerPlatformCategory[] = [
    "Analytics",
    "AppManagement",
    "Authorization",
    "Connectivity",
    "CopilotStudio",
    "Dynamics",
    "EnvironmentManagement",
    "Governance",
    "Licensing",
    "PowerApps",
    "PowerAutomate",
    "PowerPages",
    "ResourceQuery",
    "UserManagement",
    "WorkflowAgents",
];

const buildPowerPlatformCategoryClient = (category: PowerPlatformCategory) => ({
    Get: (path = "", connectionTarget?: "primary" | "secondary", headers?: Record<string, string>) =>
        ipcInvoke(POWERPLATFORM_CHANNELS.REQUEST, category, "GET" as PowerPlatformMethod, path, undefined, headers, connectionTarget),
    Post: (path = "", body?: unknown, connectionTarget?: "primary" | "secondary", headers?: Record<string, string>) =>
        ipcInvoke(POWERPLATFORM_CHANNELS.REQUEST, category, "POST" as PowerPlatformMethod, path, body, headers, connectionTarget),
    Put: (path = "", body?: unknown, connectionTarget?: "primary" | "secondary", headers?: Record<string, string>) =>
        ipcInvoke(POWERPLATFORM_CHANNELS.REQUEST, category, "PUT" as PowerPlatformMethod, path, body, headers, connectionTarget),
    Patch: (path = "", body?: unknown, connectionTarget?: "primary" | "secondary", headers?: Record<string, string>) =>
        ipcInvoke(POWERPLATFORM_CHANNELS.REQUEST, category, "PATCH" as PowerPlatformMethod, path, body, headers, connectionTarget),
    Delete: (path = "", connectionTarget?: "primary" | "secondary", headers?: Record<string, string>, body?: unknown) =>
        ipcInvoke(POWERPLATFORM_CHANNELS.REQUEST, category, "DELETE" as PowerPlatformMethod, path, body, headers, connectionTarget),
});

const powerPlatformApi = POWER_PLATFORM_CATEGORIES.reduce(
    (acc, category) => {
        acc[category] = buildPowerPlatformCategoryClient(category);
        return acc;
    },
    {} as Record<PowerPlatformCategory, ReturnType<typeof buildPowerPlatformCategoryClient>>,
);

type ToolSafeConnection = {
    id: string;
    name: string;
    url: string;
    environment: "Dev" | "Test" | "UAT" | "Production";
    createdAt?: string;
    lastUsedAt?: string;
    isActive?: boolean;
    category?: string;
    environmentColor?: string;
    categoryColor?: string;
    enabledForPowerPlatformAPI?: boolean;
    scopesForPowerPlatformAPI?: string[];
};

function toToolSafeConnection(connection: unknown): ToolSafeConnection | null {
    if (!connection || typeof connection !== "object") {
        return null;
    }

    const source = connection as Record<string, unknown>;
    const environment = source.environment;

    if (typeof source.id !== "string" || typeof source.name !== "string" || typeof source.url !== "string") {
        return null;
    }

    if (environment !== "Dev" && environment !== "Test" && environment !== "UAT" && environment !== "Production") {
        return null;
    }

    return {
        id: source.id,
        name: source.name,
        url: source.url,
        environment,
        createdAt: typeof source.createdAt === "string" ? source.createdAt : undefined,
        lastUsedAt: typeof source.lastUsedAt === "string" ? source.lastUsedAt : undefined,
        isActive: typeof source.isActive === "boolean" ? source.isActive : undefined,
        category: typeof source.category === "string" ? source.category : undefined,
        environmentColor: typeof source.environmentColor === "string" ? source.environmentColor : undefined,
        categoryColor: typeof source.categoryColor === "string" ? source.categoryColor : undefined,
        enabledForPowerPlatformAPI: typeof source.enabledForPowerPlatformAPI === "boolean" ? source.enabledForPowerPlatformAPI : undefined,
        scopesForPowerPlatformAPI:
            Array.isArray(source.scopesForPowerPlatformAPI) && source.scopesForPowerPlatformAPI.every((scope) => typeof scope === "string") ? source.scopesForPowerPlatformAPI : undefined,
    };
}

// Expose toolboxAPI to the tool window
contextBridge.exposeInMainWorld("toolboxAPI", {
    // Tool Info
    getToolContext: async () => {
        await withTimeout(toolContextReady, TOOL_CONTEXT_TIMEOUT_MS, TOOL_CONTEXT_TIMEOUT_ERROR);
        return toolContext;
    },
    preventClose: () => ipcInvoke(TOOL_WINDOW_CHANNELS.PREVENT_CLOSE),
    releasePreventClose: () => ipcInvoke(TOOL_WINDOW_CHANNELS.RELEASE_PREVENT_CLOSE),

    // Connections API
    connections: {
        // Get tool's primary connection from context
        getActiveConnection: async () => {
            await withTimeout(toolContextReady, TOOL_CONTEXT_TIMEOUT_MS, TOOL_CONTEXT_TIMEOUT_ERROR);
            if (!toolContext || typeof toolContext.connectionId !== "string") {
                return null;
            }
            const connection = await ipcInvoke(CONNECTION_CHANNELS.GET_CONNECTION_BY_ID, toolContext.connectionId);
            return toToolSafeConnection(connection);
        },
        // Secondary connection methods for multi-connection tools
        getSecondaryConnection: async () => {
            await withTimeout(toolContextReady, TOOL_CONTEXT_TIMEOUT_MS, TOOL_CONTEXT_TIMEOUT_ERROR);
            if (!toolContext || typeof toolContext.secondaryConnectionId !== "string") {
                return null;
            }
            const connection = await ipcInvoke(CONNECTION_CHANNELS.GET_CONNECTION_BY_ID, toolContext.secondaryConnectionId);
            return toToolSafeConnection(connection);
        },
    },

    // Dataverse API
    dataverse: {
        getSystemUsers: (connectionTarget?: "primary" | "secondary") => ipcInvoke(DATAVERSE_CHANNELS.GET_SYSTEM_USERS, connectionTarget),
        create: (entityLogicalName: string, record: Record<string, unknown>, connectionTarget?: "primary" | "secondary") =>
            ipcInvoke(DATAVERSE_CHANNELS.CREATE, entityLogicalName, record, connectionTarget),
        retrieve: (entityLogicalName: string, id: string, columns?: string[], connectionTarget?: "primary" | "secondary") =>
            ipcInvoke(DATAVERSE_CHANNELS.RETRIEVE, entityLogicalName, id, columns, connectionTarget),
        update: (entityLogicalName: string, id: string, record: Record<string, unknown>, connectionTarget?: "primary" | "secondary") =>
            ipcInvoke(DATAVERSE_CHANNELS.UPDATE, entityLogicalName, id, record, connectionTarget),
        delete: (entityLogicalName: string, id: string, connectionTarget?: "primary" | "secondary") => ipcInvoke(DATAVERSE_CHANNELS.DELETE, entityLogicalName, id, connectionTarget),
        retrieveMultiple: (fetchXml: string, connectionTarget?: "primary" | "secondary") => ipcInvoke(DATAVERSE_CHANNELS.RETRIEVE_MULTIPLE, fetchXml, connectionTarget),
        execute: (request: Record<string, unknown>, connectionTarget?: "primary" | "secondary") => ipcInvoke(DATAVERSE_CHANNELS.EXECUTE, request, connectionTarget),
        fetchXmlQuery: (fetchXml: string, connectionTarget?: "primary" | "secondary") => ipcInvoke(DATAVERSE_CHANNELS.FETCH_XML_QUERY, fetchXml, connectionTarget),
        getEntityMetadata: (entityLogicalName: string, searchByLogicalName: boolean, selectColumns?: string[], connectionTarget?: "primary" | "secondary") =>
            ipcInvoke(DATAVERSE_CHANNELS.GET_ENTITY_METADATA, entityLogicalName, searchByLogicalName, selectColumns, connectionTarget),
        getAllEntitiesMetadata: (selectColumns?: string[], connectionTarget?: "primary" | "secondary") => ipcInvoke(DATAVERSE_CHANNELS.GET_ALL_ENTITIES_METADATA, selectColumns, connectionTarget),
        getEntityRelatedMetadata: <P extends EntityRelatedMetadataPath>(entityLogicalName: string, relatedPath: P, selectColumns?: string[], connectionTarget?: "primary" | "secondary") =>
            ipcInvoke(DATAVERSE_CHANNELS.GET_ENTITY_RELATED_METADATA, entityLogicalName, relatedPath, selectColumns, connectionTarget) as Promise<EntityRelatedMetadataResponse<P>>,
        getSolutions: (selectColumns: string[], connectionTarget?: "primary" | "secondary") => ipcInvoke(DATAVERSE_CHANNELS.GET_SOLUTIONS, selectColumns, connectionTarget),
        getCSDLDocument: (connectionTarget?: "primary" | "secondary") => ipcInvoke(DATAVERSE_CHANNELS.GET_CSDL_DOCUMENT, connectionTarget),
        queryData: (odataQuery: string, connectionTarget?: "primary" | "secondary") => ipcInvoke(DATAVERSE_CHANNELS.QUERY_DATA, odataQuery, connectionTarget),
        publishCustomizations: (tableLogicalName?: string, connectionTarget?: "primary" | "secondary") => ipcInvoke(DATAVERSE_CHANNELS.PUBLISH_CUSTOMIZATIONS, tableLogicalName, connectionTarget),
        createMultiple: (entityLogicalName: string, records: Record<string, unknown>[], connectionTarget?: "primary" | "secondary") =>
            ipcInvoke(DATAVERSE_CHANNELS.CREATE_MULTIPLE, entityLogicalName, records, connectionTarget),
        updateMultiple: (entityLogicalName: string, records: Record<string, unknown>[], connectionTarget?: "primary" | "secondary") =>
            ipcInvoke(DATAVERSE_CHANNELS.UPDATE_MULTIPLE, entityLogicalName, records, connectionTarget),
        getEntitySetName: (entityLogicalName: string) => ipcInvoke(DATAVERSE_CHANNELS.GET_ENTITY_SET_NAME, entityLogicalName),
        associate: (primaryEntityName: string, primaryEntityId: string, relationshipName: string, relatedEntityName: string, relatedEntityId: string, connectionTarget?: "primary" | "secondary") =>
            ipcInvoke(DATAVERSE_CHANNELS.ASSOCIATE, primaryEntityName, primaryEntityId, relationshipName, relatedEntityName, relatedEntityId, connectionTarget),
        disassociate: (primaryEntityName: string, primaryEntityId: string, relationshipName: string, relatedEntityId: string, connectionTarget?: "primary" | "secondary") =>
            ipcInvoke(DATAVERSE_CHANNELS.DISASSOCIATE, primaryEntityName, primaryEntityId, relationshipName, relatedEntityId, connectionTarget),
        deploySolution: (
            base64SolutionContent: string | ArrayBuffer | ArrayBufferView,
            options?: {
                importJobId?: string;
                publishWorkflows?: boolean;
                overwriteUnmanagedCustomizations?: boolean;
                skipProductUpdateDependencies?: boolean;
                convertToManaged?: boolean;
            },
            connectionTarget?: "primary" | "secondary",
        ) => ipcInvoke(DATAVERSE_CHANNELS.DEPLOY_SOLUTION, base64SolutionContent, options, connectionTarget),
        getImportJobStatus: (importJobId: string, connectionTarget?: "primary" | "secondary") => ipcInvoke(DATAVERSE_CHANNELS.GET_IMPORT_JOB_STATUS, importJobId, connectionTarget),
        // Metadata helper utilities
        buildLabel: (text: string, languageCode?: number) => ipcInvoke(DATAVERSE_CHANNELS.BUILD_LABEL, text, languageCode),
        getAttributeODataType: (attributeType: string) => ipcInvoke(DATAVERSE_CHANNELS.GET_ATTRIBUTE_ODATA_TYPE, attributeType),
        // Entity (Table) metadata operations
        createEntityDefinition: (entityDefinition: Record<string, unknown>, options?: Record<string, unknown>, connectionTarget?: "primary" | "secondary") =>
            ipcInvoke(DATAVERSE_CHANNELS.CREATE_ENTITY_DEFINITION, entityDefinition, options, connectionTarget),
        updateEntityDefinition: (entityIdentifier: string, entityDefinition: Record<string, unknown>, options?: Record<string, unknown>, connectionTarget?: "primary" | "secondary") =>
            ipcInvoke(DATAVERSE_CHANNELS.UPDATE_ENTITY_DEFINITION, entityIdentifier, entityDefinition, options, connectionTarget),
        deleteEntityDefinition: (entityIdentifier: string, connectionTarget?: "primary" | "secondary") => ipcInvoke(DATAVERSE_CHANNELS.DELETE_ENTITY_DEFINITION, entityIdentifier, connectionTarget),
        // Attribute (Column) metadata operations
        createAttribute: (entityLogicalName: string, attributeDefinition: Record<string, unknown>, options?: Record<string, unknown>, connectionTarget?: "primary" | "secondary") =>
            ipcInvoke(DATAVERSE_CHANNELS.CREATE_ATTRIBUTE, entityLogicalName, attributeDefinition, options, connectionTarget),
        updateAttribute: (
            entityLogicalName: string,
            attributeIdentifier: string,
            attributeDefinition: Record<string, unknown>,
            options?: Record<string, unknown>,
            connectionTarget?: "primary" | "secondary",
        ) => ipcInvoke(DATAVERSE_CHANNELS.UPDATE_ATTRIBUTE, entityLogicalName, attributeIdentifier, attributeDefinition, options, connectionTarget),
        deleteAttribute: (entityLogicalName: string, attributeIdentifier: string, connectionTarget?: "primary" | "secondary") =>
            ipcInvoke(DATAVERSE_CHANNELS.DELETE_ATTRIBUTE, entityLogicalName, attributeIdentifier, connectionTarget),
        createPolymorphicLookupAttribute: (entityLogicalName: string, attributeDefinition: Record<string, unknown>, options?: Record<string, unknown>, connectionTarget?: "primary" | "secondary") =>
            ipcInvoke(DATAVERSE_CHANNELS.CREATE_POLYMORPHIC_LOOKUP_ATTRIBUTE, entityLogicalName, attributeDefinition, options, connectionTarget),
        // Relationship metadata operations
        createRelationship: (relationshipDefinition: Record<string, unknown>, options?: Record<string, unknown>, connectionTarget?: "primary" | "secondary") =>
            ipcInvoke(DATAVERSE_CHANNELS.CREATE_RELATIONSHIP, relationshipDefinition, options, connectionTarget),
        updateRelationship: (relationshipIdentifier: string, relationshipDefinition: Record<string, unknown>, options?: Record<string, unknown>, connectionTarget?: "primary" | "secondary") =>
            ipcInvoke(DATAVERSE_CHANNELS.UPDATE_RELATIONSHIP, relationshipIdentifier, relationshipDefinition, options, connectionTarget),
        deleteRelationship: (relationshipIdentifier: string, connectionTarget?: "primary" | "secondary") => ipcInvoke(DATAVERSE_CHANNELS.DELETE_RELATIONSHIP, relationshipIdentifier, connectionTarget),
        // Global option set (choice) metadata operations
        createGlobalOptionSet: (optionSetDefinition: Record<string, unknown>, options?: Record<string, unknown>, connectionTarget?: "primary" | "secondary") =>
            ipcInvoke(DATAVERSE_CHANNELS.CREATE_GLOBAL_OPTION_SET, optionSetDefinition, options, connectionTarget),
        updateGlobalOptionSet: (optionSetIdentifier: string, optionSetDefinition: Record<string, unknown>, options?: Record<string, unknown>, connectionTarget?: "primary" | "secondary") =>
            ipcInvoke(DATAVERSE_CHANNELS.UPDATE_GLOBAL_OPTION_SET, optionSetIdentifier, optionSetDefinition, options, connectionTarget),
        deleteGlobalOptionSet: (optionSetIdentifier: string, connectionTarget?: "primary" | "secondary") =>
            ipcInvoke(DATAVERSE_CHANNELS.DELETE_GLOBAL_OPTION_SET, optionSetIdentifier, connectionTarget),
        // Option value modification actions
        insertOptionValue: (params: Record<string, unknown>, connectionTarget?: "primary" | "secondary") => ipcInvoke(DATAVERSE_CHANNELS.INSERT_OPTION_VALUE, params, connectionTarget),
        updateOptionValue: (params: Record<string, unknown>, connectionTarget?: "primary" | "secondary") => ipcInvoke(DATAVERSE_CHANNELS.UPDATE_OPTION_VALUE, params, connectionTarget),
        deleteOptionValue: (params: Record<string, unknown>, connectionTarget?: "primary" | "secondary") => ipcInvoke(DATAVERSE_CHANNELS.DELETE_OPTION_VALUE, params, connectionTarget),
        orderOption: (params: Record<string, unknown>, connectionTarget?: "primary" | "secondary") => ipcInvoke(DATAVERSE_CHANNELS.ORDER_OPTION, params, connectionTarget),
    },

    // Utils API
    utils: {
        showNotification: (options: Record<string, unknown>) => ipcInvoke(UTIL_CHANNELS.SHOW_NOTIFICATION, options),
        openInConnectionBrowser: (url: string, connectionTarget?: "primary" | "secondary") => ipcInvoke(UTIL_CHANNELS.OPEN_IN_CONNECTION_BROWSER, url, connectionTarget),
        copyToClipboard: (text: string) => ipcInvoke(UTIL_CHANNELS.COPY_TO_CLIPBOARD, text),
        getCurrentTheme: () => ipcInvoke(UTIL_CHANNELS.GET_CURRENT_THEME),
        executeParallel: async <T = unknown>(...operations: Array<Promise<T> | (() => Promise<T>)>) => {
            const promises = operations.map((op) => (typeof op === "function" ? op() : op));
            return Promise.all(promises);
        },
    },

    // FileSystem API
    fileSystem: {
        readText: (path: string) => ipcInvoke(FILESYSTEM_CHANNELS.READ_TEXT, path),
        readBinary: (path: string) => ipcInvoke(FILESYSTEM_CHANNELS.READ_BINARY, path),
        exists: (path: string) => ipcInvoke(FILESYSTEM_CHANNELS.EXISTS, path),
        stat: (path: string) => ipcInvoke(FILESYSTEM_CHANNELS.STAT, path),
        readDirectory: (path: string) => ipcInvoke(FILESYSTEM_CHANNELS.READ_DIRECTORY, path),
        writeText: (path: string, content: string) => ipcInvoke(FILESYSTEM_CHANNELS.WRITE_TEXT, path, content),
        createDirectory: (path: string) => ipcInvoke(FILESYSTEM_CHANNELS.CREATE_DIRECTORY, path),
        saveFile: (defaultPath: string, content: unknown, filters?: Array<{ name: string; extensions: string[] }>) => ipcInvoke(FILESYSTEM_CHANNELS.SAVE_FILE, defaultPath, content, filters),
        selectPath: (options?: Record<string, unknown>) => ipcInvoke(FILESYSTEM_CHANNELS.SELECT_PATH, options),
    },

    // Terminal API
    terminal: {
        create: async (options: Record<string, unknown>) => {
            const { toolId, instanceId } = await getToolIdentifiers();
            return ipcInvoke(TERMINAL_CHANNELS.CREATE_TERMINAL, toolId, instanceId, options);
        },
        execute: (terminalId: string, command: string) => ipcInvoke(TERMINAL_CHANNELS.EXECUTE_COMMAND, terminalId, command),
        close: (terminalId: string) => ipcInvoke(TERMINAL_CHANNELS.CLOSE_TERMINAL, terminalId),
        get: (terminalId: string) => ipcInvoke(TERMINAL_CHANNELS.GET_TERMINAL, terminalId),
        list: async () => {
            const { toolId, instanceId } = await getToolIdentifiers();
            return ipcInvoke(TERMINAL_CHANNELS.GET_TOOL_TERMINALS, toolId, instanceId);
        },
        setVisibility: (terminalId: string, visible: boolean) => ipcInvoke(TERMINAL_CHANNELS.SET_VISIBILITY, terminalId, visible),
    },

    // Events API
    events: {
        on: (callback: (event: unknown, payload: unknown) => void) => {
            const listener = (event: unknown, payload: unknown) => callback(event, payload);
            ipcRenderer.on(EVENT_CHANNELS.TOOLBOX_EVENT, listener);
            return () => ipcRenderer.removeListener(EVENT_CHANNELS.TOOLBOX_EVENT, listener);
        },
        off: (callback: (event: unknown, payload: unknown) => void) => {
            ipcRenderer.removeListener(EVENT_CHANNELS.TOOLBOX_EVENT, callback);
        },
        getHistory: (limit?: number) => ipcInvoke(UTIL_CHANNELS.GET_EVENT_HISTORY, limit),
    },

    // Settings API (tool-specific)
    settings: {
        getAll: async () => {
            const toolId = await ensureToolContext();
            return ipcInvoke(SETTINGS_CHANNELS.TOOL_SETTINGS_GET_ALL, toolId);
        },
        get: async (key: string) => {
            const toolId = await ensureToolContext();
            return ipcInvoke(SETTINGS_CHANNELS.TOOL_SETTINGS_GET, toolId, key);
        },
        set: async (key: string, value: unknown) => {
            const toolId = await ensureToolContext();
            return ipcInvoke(SETTINGS_CHANNELS.TOOL_SETTINGS_SET, toolId, key, value);
        },
        setAll: async (settings: Record<string, unknown>) => {
            const toolId = await ensureToolContext();
            return ipcInvoke(SETTINGS_CHANNELS.TOOL_SETTINGS_SET_ALL, toolId, settings);
        },
    },

    // Invocation API (inter-tool launch context)
    invocation: {
        /**
         * Returns the prefill data that was passed by the caller tool when it launched this tool,
         * or null if this tool was not launched via an inter-tool invocation.
         *
         * If available, invocation metadata is exposed under `__pptb`.
         */
        getLaunchContext: async (): Promise<Record<string, unknown> | null> => {
            await withTimeout(toolContextReady, TOOL_CONTEXT_TIMEOUT_MS, TOOL_CONTEXT_TIMEOUT_ERROR);
            if (!toolContext) {
                return null;
            }
            const prefillData = toolContext.prefillData;
            if (prefillData === null || prefillData === undefined || typeof prefillData !== "object" || Array.isArray(prefillData)) {
                return null;
            }

            const launchContext = { ...(prefillData as Record<string, unknown>) };
            const invocationContext = toolContext.invocationContext;
            if (invocationContext && typeof invocationContext === "object" && !Array.isArray(invocationContext)) {
                launchContext.__pptb = invocationContext;
            }

            return launchContext;
        },

        /**
         * Returns data to the caller tool that launched this tool.
         * If this tool was not launched by another tool the call is a no-op.
         *
         * @param returnData The data to pass back to the caller
         */
        returnData: async (returnData: Record<string, unknown>): Promise<void> => {
            await withTimeout(toolContextReady, TOOL_CONTEXT_TIMEOUT_MS, TOOL_CONTEXT_TIMEOUT_ERROR);
            if (!toolContext || typeof toolContext.callerInstanceId !== "string") {
                return;
            }
            const { instanceId } = await getToolIdentifiers();
            if (!instanceId) {
                return;
            }
            await ipcInvoke(TOOL_WINDOW_CHANNELS.RETURN_INVOCATION_DATA, instanceId, returnData);
        },

        /**
         * Launch another tool from within this tool, optionally passing prefill data.
         * Returns a Promise that resolves with the data the target tool returns via returnData(),
         * or null if the target tool closes without returning data.
         *
         * @param targetToolId The npm package name (toolId) of the tool to launch
         * @param prefillData Data to pre-populate the target tool's state
         * @param options Connection overrides for the target tool
         */
        launchTool: async (
            targetToolId: string,
            prefillData: Record<string, unknown> = {},
            options?: { primaryConnectionId?: string | null; secondaryConnectionId?: string | null; noReturn?: boolean },
        ): Promise<unknown> => {
            const { instanceId: callerInstanceId } = await getToolIdentifiers();
            if (!callerInstanceId) {
                throw new Error("Cannot launch a tool from an uninitialized tool context");
            }

            // Resolve the public package name to the target's internal runtime identity.
            const tool = await ipcInvoke(TOOL_CHANNELS.RESOLVE_INVOCATION_TARGET, targetToolId, callerInstanceId);
            if (!tool || typeof tool !== "object" || !("id" in tool) || typeof tool.id !== "string") {
                throw new Error(`Tool not found: ${targetToolId}`);
            }

            // Generate a unique instanceId for the callee (mirrors the pattern used in the renderer)
            const calleeInstanceId = `${tool.id}-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;

            const primaryConnectionId = options?.primaryConnectionId !== undefined ? options.primaryConnectionId : (toolContext?.connectionId ?? null); // FXS auto-inherit: use caller's active connection
            const secondaryConnectionId = options?.secondaryConnectionId !== undefined ? options.secondaryConnectionId : null;
            const noReturn = options?.noReturn ?? false;

            return ipcInvoke(TOOL_WINDOW_CHANNELS.LAUNCH_WITH_CONTEXT, callerInstanceId, calleeInstanceId, tool, primaryConnectionId, secondaryConnectionId, prefillData, noReturn);
        },

        /**
         * Find installed tools that declare a given capability tag in their pptb.config.json.
         *
         * @param tag The capability tag to search for (e.g. "entity-picker")
         * @returns A list of matching installed tools
         */
        findToolsByCapability: async (tag: string): Promise<unknown[]> => {
            return ipcInvoke(TOOL_WINDOW_CHANNELS.FIND_TOOLS_BY_CAPABILITY, tag) as Promise<unknown[]>;
        },

        /**
         * Returns the list of known (registered) capability tags from the capability registry.
         * Backed by Supabase with a built-in fallback for offline use.
         *
         * @returns Array of { tag, description } entries
         */
        getKnownCapabilityTags: async (): Promise<Array<{ tag: string; description: string }>> => {
            return ipcInvoke(TOOL_CHANNELS.GET_KNOWN_CAPABILITY_TAGS) as Promise<Array<{ tag: string; description: string }>>;
        },
    },

    // Power Platform API - generic HTTP methods for all categories
    powerplatform: powerPlatformApi,
});

// Dataverse is intentionally exposed only as a standalone API.
contextBridge.exposeInMainWorld("dataverseAPI", {
    create: (entityLogicalName: string, record: Record<string, unknown>, connectionTarget?: "primary" | "secondary", additionalHeaders?: Record<string, string>) =>
        ipcInvoke(DATAVERSE_CHANNELS.CREATE, entityLogicalName, record, connectionTarget, additionalHeaders),
    retrieve: (entityLogicalName: string, id: string, columns?: string[], connectionTarget?: "primary" | "secondary", additionalHeaders?: Record<string, string>) =>
        ipcInvoke(DATAVERSE_CHANNELS.RETRIEVE, entityLogicalName, id, columns, connectionTarget, additionalHeaders),
    update: (entityLogicalName: string, id: string, record: Record<string, unknown>, connectionTarget?: "primary" | "secondary", additionalHeaders?: Record<string, string>) =>
        ipcInvoke(DATAVERSE_CHANNELS.UPDATE, entityLogicalName, id, record, connectionTarget, additionalHeaders),
    delete: (entityLogicalName: string, id: string, connectionTarget?: "primary" | "secondary", additionalHeaders?: Record<string, string>) =>
        ipcInvoke(DATAVERSE_CHANNELS.DELETE, entityLogicalName, id, connectionTarget, additionalHeaders),
    retrieveMultiple: (fetchXml: string, connectionTarget?: "primary" | "secondary", additionalHeaders?: Record<string, string>) =>
        ipcInvoke(DATAVERSE_CHANNELS.RETRIEVE_MULTIPLE, fetchXml, connectionTarget, additionalHeaders),
    execute: (request: Record<string, unknown>, connectionTarget?: "primary" | "secondary", additionalHeaders?: Record<string, string>) =>
        ipcInvoke(DATAVERSE_CHANNELS.EXECUTE, request, connectionTarget, additionalHeaders),
    fetchXmlQuery: (fetchXml: string, connectionTarget?: "primary" | "secondary", additionalHeaders?: Record<string, string>) =>
        ipcInvoke(DATAVERSE_CHANNELS.FETCH_XML_QUERY, fetchXml, connectionTarget, additionalHeaders),
    getEntityMetadata: (entityLogicalName: string, searchByLogicalName: boolean, selectColumns?: string[], connectionTarget?: "primary" | "secondary", additionalHeaders?: Record<string, string>) =>
        ipcInvoke(DATAVERSE_CHANNELS.GET_ENTITY_METADATA, entityLogicalName, searchByLogicalName, selectColumns, connectionTarget, additionalHeaders),
    getAllEntitiesMetadata: (selectColumns?: string[], connectionTarget?: "primary" | "secondary", additionalHeaders?: Record<string, string>) =>
        ipcInvoke(DATAVERSE_CHANNELS.GET_ALL_ENTITIES_METADATA, selectColumns, connectionTarget, additionalHeaders),
    getEntityRelatedMetadata: <P extends EntityRelatedMetadataPath>(
        entityLogicalName: string,
        relatedPath: P,
        selectColumns?: string[],
        connectionTarget?: "primary" | "secondary",
        additionalHeaders?: Record<string, string>,
    ) => ipcInvoke(DATAVERSE_CHANNELS.GET_ENTITY_RELATED_METADATA, entityLogicalName, relatedPath, selectColumns, connectionTarget, additionalHeaders) as Promise<EntityRelatedMetadataResponse<P>>,
    getSolutions: (selectColumns: string[], connectionTarget?: "primary" | "secondary", additionalHeaders?: Record<string, string>) =>
        ipcInvoke(DATAVERSE_CHANNELS.GET_SOLUTIONS, selectColumns, connectionTarget, additionalHeaders),
    getCSDLDocument: (connectionTarget?: "primary" | "secondary", additionalHeaders?: Record<string, string>) => ipcInvoke(DATAVERSE_CHANNELS.GET_CSDL_DOCUMENT, connectionTarget, additionalHeaders),
    queryData: (odataQuery: string, connectionTarget?: "primary" | "secondary", additionalHeaders?: Record<string, string>) =>
        ipcInvoke(DATAVERSE_CHANNELS.QUERY_DATA, odataQuery, connectionTarget, additionalHeaders),
    publishCustomizations: (tableLogicalName?: string, connectionTarget?: "primary" | "secondary", additionalHeaders?: Record<string, string>) =>
        ipcInvoke(DATAVERSE_CHANNELS.PUBLISH_CUSTOMIZATIONS, tableLogicalName, connectionTarget, additionalHeaders),
    createMultiple: (entityLogicalName: string, records: Record<string, unknown>[], connectionTarget?: "primary" | "secondary", additionalHeaders?: Record<string, string>) =>
        ipcInvoke(DATAVERSE_CHANNELS.CREATE_MULTIPLE, entityLogicalName, records, connectionTarget, additionalHeaders),
    updateMultiple: (entityLogicalName: string, records: Record<string, unknown>[], connectionTarget?: "primary" | "secondary", additionalHeaders?: Record<string, string>) =>
        ipcInvoke(DATAVERSE_CHANNELS.UPDATE_MULTIPLE, entityLogicalName, records, connectionTarget, additionalHeaders),
    executeBatch: (requests: DataverseBatchRequest[], connectionTarget?: "primary" | "secondary", additionalHeaders?: Record<string, string>) =>
        ipcInvoke(DATAVERSE_CHANNELS.EXECUTE_BATCH, requests, connectionTarget, additionalHeaders),
    executeTransaction: (requests: DataverseBatchRequest[], connectionTarget?: "primary" | "secondary", additionalHeaders?: Record<string, string>) =>
        ipcInvoke(DATAVERSE_CHANNELS.EXECUTE_TRANSACTION, requests, connectionTarget, additionalHeaders),
    getEntitySetName: (entityLogicalName: string) => ipcInvoke(DATAVERSE_CHANNELS.GET_ENTITY_SET_NAME, entityLogicalName),
    associate: (
        primaryEntityName: string,
        primaryEntityId: string,
        relationshipName: string,
        relatedEntityName: string,
        relatedEntityId: string,
        connectionTarget?: "primary" | "secondary",
        additionalHeaders?: Record<string, string>,
    ) => ipcInvoke(DATAVERSE_CHANNELS.ASSOCIATE, primaryEntityName, primaryEntityId, relationshipName, relatedEntityName, relatedEntityId, connectionTarget, additionalHeaders),
    disassociate: (
        primaryEntityName: string,
        primaryEntityId: string,
        relationshipName: string,
        relatedEntityId: string,
        connectionTarget?: "primary" | "secondary",
        additionalHeaders?: Record<string, string>,
    ) => ipcInvoke(DATAVERSE_CHANNELS.DISASSOCIATE, primaryEntityName, primaryEntityId, relationshipName, relatedEntityId, connectionTarget, additionalHeaders),
    deploySolution: (
        base64SolutionContent: string,
        options?: {
            importJobId?: string;
            publishWorkflows?: boolean;
            overwriteUnmanagedCustomizations?: boolean;
            skipProductUpdateDependencies?: boolean;
            convertToManaged?: boolean;
        },
        connectionTarget?: "primary" | "secondary",
        additionalHeaders?: Record<string, string>,
    ) => ipcInvoke(DATAVERSE_CHANNELS.DEPLOY_SOLUTION, base64SolutionContent, options, connectionTarget, additionalHeaders),
    getImportJobStatus: (importJobId: string, connectionTarget?: "primary" | "secondary", additionalHeaders?: Record<string, string>) =>
        ipcInvoke(DATAVERSE_CHANNELS.GET_IMPORT_JOB_STATUS, importJobId, connectionTarget, additionalHeaders),
    // Metadata helper utilities
    buildLabel: (text: string, languageCode?: number) => ipcInvoke(DATAVERSE_CHANNELS.BUILD_LABEL, text, languageCode),
    getAttributeODataType: (attributeType: string) => ipcInvoke(DATAVERSE_CHANNELS.GET_ATTRIBUTE_ODATA_TYPE, attributeType),
    // Entity (Table) metadata operations
    createEntityDefinition: (entityDefinition: Record<string, unknown>, options?: Record<string, unknown>, connectionTarget?: "primary" | "secondary", additionalHeaders?: Record<string, string>) =>
        ipcInvoke(DATAVERSE_CHANNELS.CREATE_ENTITY_DEFINITION, entityDefinition, options, connectionTarget, additionalHeaders),
    updateEntityDefinition: (
        entityIdentifier: string,
        entityDefinition: Record<string, unknown>,
        options?: Record<string, unknown>,
        connectionTarget?: "primary" | "secondary",
        additionalHeaders?: Record<string, string>,
    ) => ipcInvoke(DATAVERSE_CHANNELS.UPDATE_ENTITY_DEFINITION, entityIdentifier, entityDefinition, options, connectionTarget, additionalHeaders),
    deleteEntityDefinition: (entityIdentifier: string, connectionTarget?: "primary" | "secondary", additionalHeaders?: Record<string, string>) =>
        ipcInvoke(DATAVERSE_CHANNELS.DELETE_ENTITY_DEFINITION, entityIdentifier, connectionTarget, additionalHeaders),
    // Attribute (Column) metadata operations
    createAttribute: (
        entityLogicalName: string,
        attributeDefinition: Record<string, unknown>,
        options?: Record<string, unknown>,
        connectionTarget?: "primary" | "secondary",
        additionalHeaders?: Record<string, string>,
    ) => ipcInvoke(DATAVERSE_CHANNELS.CREATE_ATTRIBUTE, entityLogicalName, attributeDefinition, options, connectionTarget, additionalHeaders),
    updateAttribute: (
        entityLogicalName: string,
        attributeIdentifier: string,
        attributeDefinition: Record<string, unknown>,
        options?: Record<string, unknown>,
        connectionTarget?: "primary" | "secondary",
        additionalHeaders?: Record<string, string>,
    ) => ipcInvoke(DATAVERSE_CHANNELS.UPDATE_ATTRIBUTE, entityLogicalName, attributeIdentifier, attributeDefinition, options, connectionTarget, additionalHeaders),
    deleteAttribute: (entityLogicalName: string, attributeIdentifier: string, connectionTarget?: "primary" | "secondary", additionalHeaders?: Record<string, string>) =>
        ipcInvoke(DATAVERSE_CHANNELS.DELETE_ATTRIBUTE, entityLogicalName, attributeIdentifier, connectionTarget, additionalHeaders),
    createPolymorphicLookupAttribute: (
        entityLogicalName: string,
        attributeDefinition: Record<string, unknown>,
        options?: Record<string, unknown>,
        connectionTarget?: "primary" | "secondary",
        additionalHeaders?: Record<string, string>,
    ) => ipcInvoke(DATAVERSE_CHANNELS.CREATE_POLYMORPHIC_LOOKUP_ATTRIBUTE, entityLogicalName, attributeDefinition, options, connectionTarget, additionalHeaders),
    // Relationship metadata operations
    createRelationship: (relationshipDefinition: Record<string, unknown>, options?: Record<string, unknown>, connectionTarget?: "primary" | "secondary", additionalHeaders?: Record<string, string>) =>
        ipcInvoke(DATAVERSE_CHANNELS.CREATE_RELATIONSHIP, relationshipDefinition, options, connectionTarget, additionalHeaders),
    updateRelationship: (
        relationshipIdentifier: string,
        relationshipDefinition: Record<string, unknown>,
        options?: Record<string, unknown>,
        connectionTarget?: "primary" | "secondary",
        additionalHeaders?: Record<string, string>,
    ) => ipcInvoke(DATAVERSE_CHANNELS.UPDATE_RELATIONSHIP, relationshipIdentifier, relationshipDefinition, options, connectionTarget, additionalHeaders),
    deleteRelationship: (relationshipIdentifier: string, connectionTarget?: "primary" | "secondary", additionalHeaders?: Record<string, string>) =>
        ipcInvoke(DATAVERSE_CHANNELS.DELETE_RELATIONSHIP, relationshipIdentifier, connectionTarget, additionalHeaders),
    // Global option set (choice) metadata operations
    createGlobalOptionSet: (optionSetDefinition: Record<string, unknown>, options?: Record<string, unknown>, connectionTarget?: "primary" | "secondary", additionalHeaders?: Record<string, string>) =>
        ipcInvoke(DATAVERSE_CHANNELS.CREATE_GLOBAL_OPTION_SET, optionSetDefinition, options, connectionTarget, additionalHeaders),
    updateGlobalOptionSet: (
        optionSetIdentifier: string,
        optionSetDefinition: Record<string, unknown>,
        options?: Record<string, unknown>,
        connectionTarget?: "primary" | "secondary",
        additionalHeaders?: Record<string, string>,
    ) => ipcInvoke(DATAVERSE_CHANNELS.UPDATE_GLOBAL_OPTION_SET, optionSetIdentifier, optionSetDefinition, options, connectionTarget, additionalHeaders),
    deleteGlobalOptionSet: (optionSetIdentifier: string, connectionTarget?: "primary" | "secondary", additionalHeaders?: Record<string, string>) =>
        ipcInvoke(DATAVERSE_CHANNELS.DELETE_GLOBAL_OPTION_SET, optionSetIdentifier, connectionTarget, additionalHeaders),
    // Option value modification actions
    insertOptionValue: (params: Record<string, unknown>, connectionTarget?: "primary" | "secondary", additionalHeaders?: Record<string, string>) =>
        ipcInvoke(DATAVERSE_CHANNELS.INSERT_OPTION_VALUE, params, connectionTarget, additionalHeaders),
    updateOptionValue: (params: Record<string, unknown>, connectionTarget?: "primary" | "secondary", additionalHeaders?: Record<string, string>) =>
        ipcInvoke(DATAVERSE_CHANNELS.UPDATE_OPTION_VALUE, params, connectionTarget, additionalHeaders),
    deleteOptionValue: (params: Record<string, unknown>, connectionTarget?: "primary" | "secondary", additionalHeaders?: Record<string, string>) =>
        ipcInvoke(DATAVERSE_CHANNELS.DELETE_OPTION_VALUE, params, connectionTarget, additionalHeaders),
    orderOption: (params: Record<string, unknown>, connectionTarget?: "primary" | "secondary", additionalHeaders?: Record<string, string>) =>
        ipcInvoke(DATAVERSE_CHANNELS.ORDER_OPTION, params, connectionTarget, additionalHeaders),
});

contextBridge.exposeInMainWorld("powerplatformAPI", powerPlatformApi);

logInfo("[ToolPreloadBridge] Initialized - toolboxAPI, dataverseAPI, and powerplatformAPI exposed");