coreInterop.ts

import koffi from 'koffi';
import path from 'path';
import fs from 'fs';
import { fileURLToPath } from 'url';
import { createRequire } from 'module';
import { Configuration } from '../configuration.js';

koffi.struct('RequestBuffer', {
    Command: 'char*',
    CommandLength: 'int32_t',
    Data: 'char*',
    DataLength: 'int32_t',
});

koffi.struct('ResponseBuffer', {
    Data: 'void*',
    DataLength: 'int32_t',
    Error: 'void*',
    ErrorLength: 'int32_t',
});

// Extended request struct for binary data (audio streaming)
koffi.struct('StreamingRequestBuffer', {
    Command: 'char*',
    CommandLength: 'int32_t',
    Data: 'char*',              // JSON params
    DataLength: 'int32_t',
    BinaryData: 'void*',        // raw PCM audio bytes
    BinaryDataLength: 'int32_t',
});

const CallbackType = koffi.proto('int32_t CallbackType(void *data, int32_t length, void *userData)');

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

export class CoreInterop {
    private lib: any;
    private execute_command: any;
    private execute_command_with_callback: any;
    private execute_command_with_binary: any = null;

    private static _getLibraryExtension(): string {
        const platform = process.platform;
        if (platform === 'win32') return '.dll';
        if (platform === 'linux') return '.so';
        if (platform === 'darwin') return '.dylib';
        throw new Error(`Unsupported platform: ${platform}`);
    }

    private static _resolveDefaultCorePath(config: Configuration): string | null {
        const require = createRequire(import.meta.url);
        const platform = process.platform;
        const arch = process.arch;
        // Matches names generated by preinstall.cjs
        const packageName = `@foundry-local-core/${platform}-${arch}`;
        
        // Resolve the package path. 
        const packagePath = require.resolve(`${packageName}/package.json`);
        const packageDir = path.dirname(packagePath);
        const ext = CoreInterop._getLibraryExtension();
        
        const corePath = path.join(packageDir, `Microsoft.AI.Foundry.Local.Core${ext}`);
        if (fs.existsSync(corePath)) {
            config.params['FoundryLocalCorePath'] = corePath;

            // Auto-detect if WinML Bootstrap is needed by checking for Bootstrap DLL in FoundryLocalCorePath
            // Only auto-set if the user hasn't explicitly provided a value
            if (!('Bootstrap' in config.params)) {
                const bootstrapDllPath = path.join(packageDir, 'Microsoft.WindowsAppRuntime.Bootstrap.dll');
                if (fs.existsSync(bootstrapDllPath)) {
                    // WinML Bootstrap DLL found, enable bootstrapping
                    config.params['Bootstrap'] = 'true';
                }
            }
            
            return corePath;
        }

        return null;
    }

    private _toBytes(str: string): Uint8Array {
        return new TextEncoder().encode(str);
    }

    constructor(config: Configuration) {
        const corePath = config.params['FoundryLocalCorePath'] || CoreInterop._resolveDefaultCorePath(config);
        
        if (!corePath) {
            throw new Error("FoundryLocalCorePath not specified in configuration and could not auto-discover binaries. Please run 'npm install' to download native libraries.");
        }

        const coreDir = path.dirname(corePath);
        const ext = CoreInterop._getLibraryExtension();
        
        // On Windows, explicitly load dependencies to work around DLL resolution challenges
        if (process.platform === 'win32') {
            koffi.load(path.join(coreDir, `onnxruntime${ext}`));
            koffi.load(path.join(coreDir, `onnxruntime-genai${ext}`));
            process.env.PATH = `${coreDir};${process.env.PATH}`;
        }
        this.lib = koffi.load(corePath);

        this.execute_command = this.lib.func('void execute_command(RequestBuffer *request, _Inout_ ResponseBuffer *response)');
        this.execute_command_with_callback = this.lib.func('void execute_command_with_callback(RequestBuffer *request, _Inout_ ResponseBuffer *response, CallbackType *callback, void *userData)');
        this.execute_command_with_binary = this.lib.func('void execute_command_with_binary(StreamingRequestBuffer *request, _Inout_ ResponseBuffer *response)');
    }

    public executeCommand(command: string, params?: any): string {
        const cmdBuf = koffi.alloc('char', command.length + 1);
        koffi.encode(cmdBuf, 'char', command, command.length + 1);

        const dataStr = params ? JSON.stringify(params) : '';
        const dataBytes = this._toBytes(dataStr);
        const dataBuf = koffi.alloc('char', dataBytes.length + 1);
        koffi.encode(dataBuf, 'char', dataStr, dataBytes.length + 1);

        const req = { 
            Command: koffi.address(cmdBuf), 
            CommandLength: command.length, 
            Data: koffi.address(dataBuf), 
            DataLength: dataBytes.length 
        };
        const res = { Data: 0, DataLength: 0, Error: 0, ErrorLength: 0 };
        
        this.execute_command(req, res);
        
        try {
            if (res.Error) {
                const errorMsg = koffi.decode(res.Error, 'char', res.ErrorLength);
                throw new Error(`Command '${command}' failed: ${errorMsg}`);
            }
            
            return res.Data ? koffi.decode(res.Data, 'char', res.DataLength) : "";
        } finally {
            // Free the heap-allocated response strings using koffi.free()
            // Docs: https://koffi.dev/pointers/#disposable-types
            if (res.Data) koffi.free(res.Data);
            if (res.Error) koffi.free(res.Error);
        }
    }

    /**
     * Execute a native command with binary data (e.g., audio PCM bytes).
     * Uses the execute_command_with_binary native entry point which accepts
     * both JSON params and raw binary data via StreamingRequestBuffer.
     */
    public executeCommandWithBinary(command: string, params: any, binaryData: Uint8Array): string {
        const cmdBuf = koffi.alloc('char', command.length + 1);
        koffi.encode(cmdBuf, 'char', command, command.length + 1);

        const dataStr = params ? JSON.stringify(params) : '';
        const dataBytes = this._toBytes(dataStr);
        const dataBuf = koffi.alloc('char', dataBytes.length + 1);
        koffi.encode(dataBuf, 'char', dataStr, dataBytes.length + 1);

        // For binary data, use a Node.js Buffer which allocates stable external memory
        // that won't be moved by V8's garbage collector during the FFI call.
        const binLength = binaryData.length;
        const binBuf = Buffer.from(binaryData);
        
        // Use koffi.as to pass Buffer directly as a typed pointer
        const binTypedPtr = koffi.as(binBuf, 'void *');

        const req = {
            Command: koffi.address(cmdBuf),
            CommandLength: command.length,
            Data: koffi.address(dataBuf),
            DataLength: dataBytes.length,
            BinaryData: binTypedPtr,
            BinaryDataLength: binLength
        };
        const res = { Data: 0, DataLength: 0, Error: 0, ErrorLength: 0 };

        this.execute_command_with_binary(req, res);

        try {
            if (res.Error) {
                const errorMsg = koffi.decode(res.Error, 'char', res.ErrorLength);
                throw new Error(`Command '${command}' failed: ${errorMsg}`);
            }

            return res.Data ? koffi.decode(res.Data, 'char', res.DataLength) : "";
        } finally {
            if (res.Data) koffi.free(res.Data);
            if (res.Error) koffi.free(res.Error);
        }
    }

    public executeCommandStreaming(command: string, params: any, callback: (chunk: string) => void): Promise<string> {
        const cmdBuf = koffi.alloc('char', command.length + 1);
        koffi.encode(cmdBuf, 'char', command, command.length + 1);

        const dataStr = params ? JSON.stringify(params) : '';
        const dataBytes = this._toBytes(dataStr);
        const dataBuf = koffi.alloc('char', dataBytes.length + 1);
        koffi.encode(dataBuf, 'char', dataStr, dataBytes.length + 1);

        const cb = koffi.register((data: any, length: number, userData: any) => {
            const chunk = koffi.decode(data, 'char', length);
            callback(chunk);
            return 0; // 0 = continue, 1 = cancel
        }, koffi.pointer(CallbackType));

        return new Promise<string>((resolve, reject) => {
            const req = { 
                Command: koffi.address(cmdBuf), 
                CommandLength: command.length, 
                Data: koffi.address(dataBuf), 
                DataLength: dataBytes.length 
            };
            const res = { Data: 0, DataLength: 0, Error: 0, ErrorLength: 0 };
            
            this.execute_command_with_callback.async(req, res, cb, null, (err: any) => {
                koffi.unregister(cb);
                koffi.free(cmdBuf);
                koffi.free(dataBuf);

                if (err) {
                    reject(err);
                    return;
                }
                
                try {
                    if (res.Error) {
                        const errorMsg = koffi.decode(res.Error, 'char', res.ErrorLength);
                        reject(new Error(`Command '${command}' failed: ${errorMsg}`));
                    } else {
                        const responseData = res.Data ? koffi.decode(res.Data, 'char', res.DataLength) : '';
                        resolve(responseData);
                    }
                } finally {
                    // Free the heap-allocated response strings using koffi.free()
                    if (res.Data) koffi.free(res.Data);
                    if (res.Error) koffi.free(res.Error);
                }
            });
        });
    }

}