Runtime Libraries

/**
 * Main runtime host for kernel communication
 */
class KernelHost {
  /**
   * Start the kernel host process
   * @returns Promise that resolves when host is ready
   */
  run(): Promise<void>;

  /**
   * Stop the kernel host and cleanup resources
   * @returns Promise that resolves when cleanup is complete
   */
  close(): Promise<void>;
}

/**
 * IO provider interface for jsii API exchanges
 */
interface IInputOutput {
  /**
   * Read input from the communication channel
   * @returns Input message or exit signal
   */
  read(): Input | Exit;

  /**
   * Write output to the communication channel
   * @param output Output message to write
   */
  write(output: Output): void;
}

/**
 * Standard implementation using synchronous stdio
 */
class InputOutput implements IInputOutput {
  /**
   * Create new InputOutput instance
   * @param stdio Optional custom stdio implementation
   */
  constructor(stdio?: SyncStdio);

  read(): Input | Exit;
  write(output: Output): void;
}

/**
 * Synchronous stdio operations
 */
class SyncStdio {
  /**
   * Read line from stdin synchronously
   */
  readLine(): string | null;

  /**
   * Write line to stdout
   */
  writeLine(line: string): void;

  /**
   * Write line to stderr
   */
  writeErrorLine(line: string): void;
}

/**
 * Main jsii kernel for loading and executing assemblies
 */
class Kernel {
  /**
   * Create new kernel instance
   * @param callbackHandler Handler for callback requests
   */
  constructor(callbackHandler?: (callback: api.Callback) => any);

  /**
   * Load a jsii assembly into the kernel
   * @param request Assembly load request
   * @returns Load response with assembly information
   */
  load(request: api.LoadRequest): api.LoadResponse;

  /**
   * Create an instance of a jsii class
   * @param request Object creation request
   * @returns Object reference for the created instance
   */
  create(request: api.CreateRequest): api.CreateResponse;

  /**
   * Delete an object reference
   * @param request Object deletion request
   * @returns Deletion confirmation
   */
  del(request: api.DelRequest): api.DelResponse;

  /**
   * Get property value from an object
   * @param request Property access request
   * @returns Property value
   */
  get(request: api.GetRequest): api.GetResponse;

  /**
   * Get static property value from a class
   * @param request Static property access request  
   * @returns Property value
   */
  sget(request: api.StaticGetRequest): api.GetResponse;

  /**
   * Set property value on an object
   * @param request Property assignment request
   * @returns Assignment confirmation
   */
  set(request: api.SetRequest): api.SetResponse;

  /**
   * Set static property value on a class
   * @param request Static property assignment request
   * @returns Assignment confirmation  
   */
  sset(request: api.StaticSetRequest): api.SetResponse;

  /**
   * Invoke method on an object
   * @param request Method invocation request
   * @returns Method result
   */
  invoke(request: api.InvokeRequest): api.GetResponse;

  /**
   * Invoke static method on a class
   * @param request Static method invocation request
   * @returns Method result
   */
  sinvoke(request: api.StaticInvokeRequest): api.GetResponse;

  /**
   * Execute arbitrary script in the kernel
   * @param request Script execution request
   * @returns Script result
   */
  invokeBinScript(request: api.InvokeScriptRequest): api.InvokeScriptResponse;

  /**
   * Get available bin script commands
   * @param request Script command request
   * @returns Available commands
   */
  getBinScriptCommand(request: api.GetScriptCommandRequest): api.GetScriptCommandResponse;
}

namespace api {
  /**
   * Request to load an assembly into the kernel
   */
  interface LoadRequest {
    /** Assembly name */
    name: string;
    /** Assembly version */
    version: string;
    /** Optional tarball path for assembly */
    tarball?: string;
  }

  /**
   * Response from assembly loading
   */
  interface LoadResponse {
    /** Loaded assembly name */
    assembly: string;
    /** Assembly types */
    types: number;
  }

  /**
   * Request to create object instance
   */
  interface CreateRequest {
    /** Fully qualified class name */
    fqn: string;
    /** Constructor arguments */
    args?: any[];
    /** Method/property overrides */
    overrides?: Override[];
    /** Interface implementations */
    interfaces?: string[];
  }

  /**
   * Response with object reference
   */
  type CreateResponse = ObjRef;

  /**
   * Request to delete object
   */
  interface DelRequest {
    /** Object reference to delete */
    objref: ObjRef;
  }

  /**
   * Delete confirmation response
   */
  interface DelResponse {
    /** Success confirmation */
    deleted: boolean;
  }

  /**
   * Request to get property value
   */
  interface GetRequest {
    /** Object reference */
    objref: ObjRef;
    /** Property name */
    property: string;
  }

  /**
   * Request to get static property
   */
  interface StaticGetRequest {
    /** Fully qualified class name */
    fqn: string;
    /** Static property name */
    property: string;
  }

  /**
   * Property value response
   */
  interface GetResponse {
    /** Property value */
    value?: any;
  }

  /**
   * Request to set property value
   */
  interface SetRequest {
    /** Object reference */
    objref: ObjRef;
    /** Property name */
    property: string;
    /** New property value */
    value?: any;
  }

  /**
   * Request to set static property
   */
  interface StaticSetRequest {
    /** Fully qualified class name */
    fqn: string;
    /** Static property name */
    property: string;
    /** New property value */
    value?: any;
  }

  /**
   * Set property confirmation response
   */
  interface SetResponse {}

  /**
   * Request to invoke method
   */
  interface InvokeRequest {
    /** Object reference */
    objref: ObjRef;
    /** Method name */
    method: string;
    /** Method arguments */
    args?: any[];
  }

  /**
   * Request to invoke static method
   */
  interface StaticInvokeRequest {
    /** Fully qualified class name */
    fqn: string;
    /** Static method name */  
    method: string;
    /** Method arguments */
    args?: any[];
  }

  /**
   * Hello message from kernel
   */
  interface HelloResponse {
    /** Kernel hello message */
    hello: string;
  }

  /**
   * Script execution request
   */
  interface InvokeScriptRequest {
    /** Script command */
    command: string;
    /** Script arguments */
    args: string[];
  }

  /**
   * Script execution response
   */
  interface InvokeScriptResponse {
    /** Exit code */
    exit?: number;
    /** Script output */
    stdout?: string;
    /** Script errors */
    stderr?: string;
  }

  /**
   * Get script command request
   */
  interface GetScriptCommandRequest {
    /** Command name */
    command: string;
  }

  /**
   * Script command information response  
   */
  interface GetScriptCommandResponse {
    /** Command executable path */
    command?: string;
  }
}

/**
 * Token constants for object serialization
 */
const TOKEN_REF = "$jsii.byref";
const TOKEN_INTERFACES = "$jsii.interfaces";
const TOKEN_DATE = "$jsii.date";
const TOKEN_ENUM = "$jsii.enum";
const TOKEN_MAP = "$jsii.map";
const TOKEN_STRUCT = "$jsii.struct";

/**
 * Object reference with serialization token
 */
interface ObjRef {
  /** Reference token */
  [TOKEN_REF]: string;
  /** Implemented interfaces */
  [TOKEN_INTERFACES]?: string[];
}

/**
 * Serialized date object for cross-language transfer
 */
interface WireDate {
  /** Date token */
  [TOKEN_DATE]: string;
}

/**
 * Serialized enum value
 */
interface WireEnum {
  /** Enum token */
  [TOKEN_ENUM]: string;
}

/**
 * Serialized map object
 */
interface WireMap {
  /** Map token */
  [TOKEN_MAP]: { [key: string]: any };
}

/**
 * Serialized struct (data-only interface)
 */
interface WireStruct {
  /** Struct token */  
  [TOKEN_STRUCT]: string;
  /** Struct data */
  [key: string]: any;
}

/**
 * Method or property override definition
 */
type Override = MethodOverride | PropertyOverride;

/**
 * Method override specification  
 */
interface MethodOverride {
  /** Method name to override */
  method: string;
  /** Callback cookie for identification */
  cookie?: string;
}

/**
 * Property override specification
 */
interface PropertyOverride {
  /** Property name to override */
  property: string;
  /** Callback cookie for identification */
  cookie?: string;
}

/**
 * Callback request structure for overrides
 */
interface Callback {
  /** Callback identifier */
  cbid: string;
  /** Callback cookie */
  cookie?: string;
  /** Callback result */
  result?: any;
  /** Callback error */
  err?: string;
}

/**
 * Types of jsii errors
 */
enum JsiiErrorType {
  /** Internal jsii fault */
  JSII_FAULT = "@jsii/kernel.Fault", 
  /** Runtime execution error */
  RUNTIME_ERROR = "@jsii/kernel.RuntimeError"
}

/**
 * Base interface for jsii errors
 */
interface JsiiError {
  /** Error type discriminator */
  name: JsiiErrorType;
  /** Error message */
  message: string;
  /** Error stack trace */
  stack?: string;
}

/**
 * Fault error for kernel issues
 */
class JsiiFault extends Error implements JsiiError {
  readonly name = JsiiErrorType.JSII_FAULT;

  /**
   * Create new jsii fault
   * @param message Error message
   */
  constructor(message: string);
}

/**
 * Runtime error for execution issues
 */
class RuntimeError extends Error implements JsiiError {
  readonly name = JsiiErrorType.RUNTIME_ERROR;

  /**
   * Create new runtime error
   * @param message Error message  
   */
  constructor(message: string);
}

/**
 * Type guard for object references
 */
function isObjRef(value: any): value is ObjRef;

/**
 * Type guard for wire date objects
 */
function isWireDate(value: any): value is WireDate;

/**
 * Type guard for wire enum objects
 */
function isWireEnum(value: any): value is WireEnum;

/**
 * Type guard for wire map objects  
 */
function isWireMap(value: any): value is WireMap;

/**
 * Type guard for wire struct objects
 */
function isWireStruct(value: any): value is WireStruct;

/**
 * Type guard for method overrides
 */
function isMethodOverride(override: Override): override is MethodOverride;

/**
 * Type guard for property overrides  
 */
function isPropertyOverride(override: Override): override is PropertyOverride;

/**
 * Input message types for kernel communication
 */
type Input = 
  | api.LoadRequest
  | api.CreateRequest
  | api.DelRequest
  | api.GetRequest
  | api.StaticGetRequest
  | api.SetRequest
  | api.StaticSetRequest
  | api.InvokeRequest
  | api.StaticInvokeRequest
  | api.InvokeScriptRequest
  | api.GetScriptCommandRequest;

/**
 * Output message types from kernel
 */
type Output =
  | api.HelloResponse
  | api.LoadResponse
  | api.CreateResponse
  | api.DelResponse
  | api.GetResponse
  | api.SetResponse
  | api.InvokeScriptResponse
  | api.GetScriptCommandResponse;

/**
 * Exit signal type
 */
interface Exit {
  /** Exit code */
  exit: number;
}

// Setting up a kernel host
import { KernelHost, InputOutput } from '@jsii/runtime';

const host = new KernelHost();
const io = new InputOutput();

// Start the host
await host.run();

// Load an assembly
import { Kernel, api } from '@jsii/kernel';

const kernel = new Kernel();
const loadResponse = kernel.load({
  name: 'my-jsii-lib',
  version: '1.0.0'
});

// Create an object instance  
const objRef = kernel.create({
  fqn: 'my-jsii-lib.MyClass',
  args: ['constructor-arg']
});

// Call a method
const result = kernel.invoke({
  objref: objRef,
  method: 'myMethod',
  args: ['arg1', 'arg2']
});

// Clean up
kernel.del({ objref: objRef });
await host.close();