@papicandela/mcx-core 0.1.0

package/src/sandbox/interface.ts

@@ -0,0 +1,40 @@
+import type { ExecutionContext, SandboxConfig, SandboxResult } from "../types.js";
+
+/**
+ * Interface for sandbox implementations
+ *
+ * Sandboxes provide isolated code execution environments
+ * with configurable resource limits and adapter injection.
+ */
+export interface ISandbox {
+  /**
+   * Execute code in the sandbox
+   *
+   * @param code - JavaScript code to execute
+   * @param context - Execution context with adapters and variables
+   * @returns Result containing the value, logs, and execution metadata
+   */
+  execute<T = unknown>(code: string, context: ExecutionContext): Promise<SandboxResult<T>>;
+
+  /**
+   * Get the current sandbox configuration
+   */
+  getConfig(): SandboxConfig;
+
+  /**
+   * Update sandbox configuration
+   *
+   * @param config - New configuration options to merge
+   */
+  configure(config: Partial<SandboxConfig>): void;
+
+  /**
+   * Dispose of sandbox resources
+   */
+  dispose(): void;
+}
+
+/**
+ * Factory function type for creating sandbox instances
+ */
+export type SandboxFactory = (config?: SandboxConfig) => ISandbox;

package/src/skill.ts

@@ -0,0 +1,180 @@
+import type { SandboxConfig, Skill, SkillConfig } from "./types.js";
+
+/**
+ * Default sandbox configuration for skills.
+ */
+const DEFAULT_SANDBOX_CONFIG: Required<SandboxConfig> = {
+  timeout: 5000,
+  memoryLimit: 128,
+  allowAsync: true,
+  globals: {},
+};
+
+/**
+ * Define a skill with configuration.
+ *
+ * Skills are executable code snippets that run in a sandboxed environment
+ * with access to registered adapters.
+ *
+ * @example
+ * ```ts
+ * const mySkill = defineSkill({
+ *   name: 'process-data',
+ *   description: 'Processes data using file and http adapters',
+ *   adapters: ['file', 'http'],
+ *   code: `
+ *     const data = await adapters.file.read('input.json');
+ *     const result = await adapters.http.post('/api/process', { body: data });
+ *     return result;
+ *   `,
+ *   sandbox: {
+ *     timeout: 10000,
+ *   },
+ * });
+ * ```
+ */
+export function defineSkill(config: SkillConfig): Skill {
+  if (!config.name) {
+    throw new Error("Skill name is required");
+  }
+
+  const hasCode = config.code && config.code.trim() !== "";
+  const hasRun = typeof config.run === "function";
+
+  if (!hasCode && !hasRun) {
+    throw new Error("Skill must have either 'code' (string) or 'run' (function)");
+  }
+
+  return {
+    name: config.name,
+    description: config.description,
+    version: config.version ?? "1.0.0",
+    adapters: config.adapters ?? [],
+    code: config.code,
+    run: config.run,
+    sandboxConfig: {
+      ...DEFAULT_SANDBOX_CONFIG,
+      ...config.sandbox,
+    },
+  };
+}
+
+/**
+ * Define multiple skills at once.
+ *
+ * @example
+ * ```ts
+ * const skills = defineSkills([
+ *   { name: 'skill1', code: '...' },
+ *   { name: 'skill2', code: '...' },
+ * ]);
+ * ```
+ */
+export function defineSkills(configs: SkillConfig[]): Skill[] {
+  return configs.map(defineSkill);
+}
+
+/**
+ * Create a skill builder for fluent skill definition.
+ *
+ * @example
+ * ```ts
+ * const skill = skillBuilder('my-skill')
+ *   .description('Does something useful')
+ *   .requires('file', 'http')
+ *   .timeout(10000)
+ *   .code(`
+ *     // skill code here
+ *   `)
+ *   .build();
+ * ```
+ */
+export function skillBuilder(name: string): SkillBuilder {
+  return new SkillBuilder(name);
+}
+
+/**
+ * Fluent builder for skill configuration.
+ */
+class SkillBuilder {
+  private config: SkillConfig;
+
+  constructor(name: string) {
+    this.config = {
+      name,
+      code: "",
+    };
+  }
+
+  /**
+   * Set the skill description.
+   */
+  description(description: string): this {
+    this.config.description = description;
+    return this;
+  }
+
+  /**
+   * Set the skill version.
+   */
+  version(version: string): this {
+    this.config.version = version;
+    return this;
+  }
+
+  /**
+   * Specify required adapters.
+   */
+  requires(...adapters: string[]): this {
+    this.config.adapters = adapters;
+    return this;
+  }
+
+  /**
+   * Set the execution timeout in milliseconds.
+   */
+  timeout(ms: number): this {
+    this.config.sandbox = {
+      ...this.config.sandbox,
+      timeout: ms,
+    };
+    return this;
+  }
+
+  /**
+   * Set the memory limit in MB.
+   */
+  memoryLimit(mb: number): this {
+    this.config.sandbox = {
+      ...this.config.sandbox,
+      memoryLimit: mb,
+    };
+    return this;
+  }
+
+  /**
+   * Set the skill code.
+   */
+  code(code: string): this {
+    this.config.code = code;
+    return this;
+  }
+
+  /**
+   * Set custom sandbox configuration.
+   */
+  sandbox(config: SandboxConfig): this {
+    this.config.sandbox = {
+      ...this.config.sandbox,
+      ...config,
+    };
+    return this;
+  }
+
+  /**
+   * Build the skill.
+   */
+  build(): Skill {
+    return defineSkill(this.config);
+  }
+}

package/src/types.ts

@@ -0,0 +1,146 @@
+import type { z } from "zod";
+
+/**
+ * Configuration for an adapter method parameter
+ */
+export interface AdapterMethodParameter {
+  name: string;
+  type: "string" | "number" | "boolean" | "object" | "array";
+  description?: string;
+  required?: boolean;
+  default?: unknown;
+}
+
+/**
+ * Configuration for an adapter method
+ */
+export interface AdapterMethodConfig {
+  name: string;
+  description?: string;
+  parameters?: AdapterMethodParameter[];
+  handler: (...args: unknown[]) => unknown | Promise<unknown>;
+}
+
+/**
+ * A method exposed by an adapter
+ */
+export interface AdapterMethod {
+  name: string;
+  description?: string;
+  parameters: AdapterMethodParameter[];
+  execute: (...args: unknown[]) => unknown | Promise<unknown>;
+}
+
+/**
+ * Configuration for defining an adapter
+ */
+export interface AdapterConfig<TSchema extends z.ZodTypeAny = z.ZodTypeAny> {
+  name: string;
+  description?: string;
+  version?: string;
+  configSchema?: TSchema;
+  methods: AdapterMethodConfig[];
+}
+
+/**
+ * A registered adapter instance
+ */
+export interface Adapter {
+  name: string;
+  description?: string;
+  version: string;
+  methods: Map<string, AdapterMethod>;
+  config?: unknown;
+}
+
+/**
+ * Configuration for the sandbox execution environment
+ */
+export interface SandboxConfig {
+  /** Timeout in milliseconds (default: 5000) */
+  timeout?: number;
+  /** Memory limit in MB (default: 128) */
+  memoryLimit?: number;
+  /** Whether to allow async/await (default: true) */
+  allowAsync?: boolean;
+  /** Custom global variables to inject */
+  globals?: Record<string, unknown>;
+}
+
+/**
+ * Result from sandbox code execution
+ */
+export interface SandboxResult<T = unknown> {
+  success: boolean;
+  value?: T;
+  error?: {
+    name: string;
+    message: string;
+    stack?: string;
+  };
+  logs: string[];
+  executionTime: number;
+}
+
+/**
+ * Skill run function signature
+ */
+export type SkillRunFunction = (ctx: Record<string, unknown>) => Promise<unknown> | unknown;
+
+/**
+ * Configuration for defining a skill
+ */
+export interface SkillConfig {
+  name: string;
+  description?: string;
+  version?: string;
+  /** Required adapters for this skill */
+  adapters?: string[];
+  /** The skill code to execute (sandbox mode) */
+  code?: string;
+  /** Direct run function (native mode) */
+  run?: SkillRunFunction;
+  /** Sandbox configuration overrides */
+  sandbox?: SandboxConfig;
+}
+
+/**
+ * A registered skill instance
+ */
+export interface Skill {
+  name: string;
+  description?: string;
+  version: string;
+  adapters: string[];
+  /** Code string for sandbox execution */
+  code?: string;
+  /** Direct run function for native execution */
+  run?: SkillRunFunction;
+  sandboxConfig: SandboxConfig;
+}
+
+/**
+ * Main MCX framework configuration
+ */
+export interface MCXConfig {
+  /** Adapters to load */
+  adapters?: Adapter[];
+  /** Skills to register */
+  skills?: Skill[];
+  /** Default sandbox configuration */
+  sandbox?: SandboxConfig;
+  /** Path to adapters directory */
+  adaptersDir?: string;
+  /** Path to skills directory */
+  skillsDir?: string;
+}
+
+/**
+ * Context passed to sandbox execution
+ */
+export interface ExecutionContext {
+  /** Registered adapters accessible in sandbox */
+  adapters: Record<string, Record<string, (...args: unknown[]) => unknown | Promise<unknown>>>;
+  /** Custom variables */
+  variables?: Record<string, unknown>;
+}

package/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "types": ["@types/bun"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}