@inf-minds/kernel 0.0.1

package/dist/types.d.ts

@@ -0,0 +1,288 @@
+import type { CoordinationMode } from '@inf-minds/coordination-modes';
+import type { MindConfig, MindEvent } from '@inf-minds/mindkit';
+import type { JobManager, EventAppender, ArtifactManager, GraphState, ArtifactRef } from '@inf-minds/jobs';
+import type { ArtifactRouter } from '@inf-minds/jobs';
+export type { GraphState } from '@inf-minds/jobs';
+/**
+ * Session status values.
+ */
+export declare const SESSION_STATUS: {
+    readonly PENDING: "pending";
+    readonly RUNNING: "running";
+    readonly PAUSED: "paused";
+    readonly COMPLETED: "completed";
+    readonly FAILED: "failed";
+    readonly CANCELLED: "cancelled";
+};
+export type SessionStatus = (typeof SESSION_STATUS)[keyof typeof SESSION_STATUS];
+/**
+ * Unsubscribe function returned by subscribe methods.
+ */
+export type Unsubscribe = () => void;
+/**
+ * Filter options for listing sessions.
+ */
+export interface SessionFilter {
+    /** Filter by account ID */
+    accountId?: string;
+    /** Filter by mode name */
+    mode?: string;
+    /** Filter by status */
+    status?: SessionStatus;
+    /** Maximum number of sessions to return */
+    limit?: number;
+    /** Number of sessions to skip */
+    offset?: number;
+}
+/**
+ * Options for creating a new kernel session.
+ */
+export interface CreateSessionOptions {
+    /** Coordination mode (name of registered mode or inline definition) */
+    mode: string | CoordinationMode;
+    /** Initial input data for the session */
+    input: unknown;
+    /** Account ID this session belongs to */
+    accountId: string;
+    /** Custom artifact router (uses default if not provided) */
+    artifactRouter?: ArtifactRouter;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Events emitted during kernel session execution.
+ */
+export type SessionEvent = {
+    type: 'session_started';
+    sessionId: string;
+    mode: string;
+    timestamp: Date;
+} | {
+    type: 'node_started';
+    nodeId: string;
+    mindType: string;
+    jobId: string;
+    timestamp: Date;
+} | {
+    type: 'node_progress';
+    nodeId: string;
+    event: MindEvent;
+    timestamp: Date;
+} | {
+    type: 'node_completed';
+    nodeId: string;
+    output: unknown;
+    timestamp: Date;
+} | {
+    type: 'node_failed';
+    nodeId: string;
+    error: string;
+    timestamp: Date;
+} | {
+    type: 'node_skipped';
+    nodeId: string;
+    reason: string;
+    timestamp: Date;
+} | {
+    type: 'artifact_routed';
+    from: string;
+    to: string;
+    artifact: ArtifactRef;
+    timestamp: Date;
+} | {
+    type: 'graph_advanced';
+    fromNode: string;
+    toNode: string;
+    timestamp: Date;
+} | {
+    type: 'session_paused';
+    timestamp: Date;
+} | {
+    type: 'session_resumed';
+    timestamp: Date;
+} | {
+    type: 'session_completed';
+    output: unknown;
+    timestamp: Date;
+} | {
+    type: 'session_failed';
+    error: string;
+    timestamp: Date;
+} | {
+    type: 'session_cancelled';
+    timestamp: Date;
+};
+/**
+ * Kernel session representing an execution of a coordination mode.
+ */
+export interface KernelSession {
+    /** Unique session ID (same as parent job ID) */
+    readonly id: string;
+    /** Name of the coordination mode being executed */
+    readonly mode: string;
+    /** Current session status */
+    readonly status: SessionStatus;
+    /** Current graph execution state */
+    readonly graphState: GraphState;
+    /** Base path for session artifacts */
+    readonly artifactBasePath: string;
+    /** Account ID this session belongs to */
+    readonly accountId: string;
+    /**
+     * Pause session execution.
+     * Active nodes will complete but no new nodes will start.
+     */
+    pause(): Promise<void>;
+    /**
+     * Resume a paused session.
+     */
+    resume(): Promise<void>;
+    /**
+     * Cancel session execution.
+     * Active nodes will be cancelled if possible.
+     */
+    cancel(): Promise<void>;
+    /**
+     * Subscribe to session events.
+     * @param handler - Event handler function
+     * @returns Unsubscribe function
+     */
+    subscribe(handler: (event: SessionEvent) => void): Unsubscribe;
+    /**
+     * Get artifacts for this session.
+     * @param path - Optional path prefix to filter by
+     * @returns List of artifact references
+     */
+    getArtifacts(path?: string): Promise<ArtifactRef[]>;
+    /**
+     * Get the output of a completed node.
+     * @param nodeId - Node ID to get output for
+     * @returns Node output or null if not completed
+     */
+    getNodeOutput(nodeId: string): unknown | null;
+    /**
+     * Wait for session to complete.
+     * @returns Final session output
+     * @throws If session fails or is cancelled
+     */
+    waitForCompletion(): Promise<unknown>;
+}
+/**
+ * Kernel interface for creating and managing sessions.
+ */
+export interface Kernel {
+    /**
+     * Create a new session with the given coordination mode.
+     * @param options - Session creation options
+     * @returns The created session (not yet started)
+     */
+    createSession(options: CreateSessionOptions): Promise<KernelSession>;
+    /**
+     * Get an existing session by ID.
+     * @param sessionId - Session ID to retrieve
+     * @returns Session or null if not found
+     */
+    getSession(sessionId: string): Promise<KernelSession | null>;
+    /**
+     * List sessions with optional filtering.
+     * @param filter - Optional filter options
+     * @returns List of sessions
+     */
+    listSessions(filter?: SessionFilter): Promise<KernelSession[]>;
+    /**
+     * Register a named mind configuration.
+     * @param name - Mind type name (e.g., 'researcher', 'coordinator')
+     * @param config - Mind configuration
+     */
+    registerMind(name: string, config: MindConfig): void;
+    /**
+     * Get a registered mind configuration.
+     * @param name - Mind type name
+     * @returns Mind configuration or undefined
+     */
+    getMind(name: string): MindConfig | undefined;
+    /**
+     * Register a named coordination mode.
+     * @param mode - Coordination mode definition
+     */
+    registerMode(mode: CoordinationMode): void;
+    /**
+     * Get a registered coordination mode.
+     * @param name - Mode name
+     * @returns Coordination mode or undefined
+     */
+    getMode(name: string): CoordinationMode | undefined;
+    /**
+     * List all registered mind type names.
+     */
+    listMindTypes(): string[];
+    /**
+     * List all registered mode names.
+     */
+    listModeNames(): string[];
+}
+/**
+ * Options for creating a kernel instance.
+ */
+export interface KernelOptions {
+    /** JobManager instance for job lifecycle */
+    jobManager: JobManager;
+    /** EventAppender instance for event streaming */
+    eventAppender: EventAppender;
+    /** ArtifactManager instance for artifact operations */
+    artifactManager: ArtifactManager;
+    /** Default artifact router (optional, uses DefaultArtifactRouter if not provided) */
+    defaultArtifactRouter?: ArtifactRouter;
+}
+/**
+ * Mind registry for registered mind configurations.
+ */
+export interface MindRegistry {
+    /** Register a mind configuration */
+    register(name: string, config: MindConfig): void;
+    /** Get a registered mind configuration */
+    get(name: string): MindConfig | undefined;
+    /** Check if a mind is registered */
+    has(name: string): boolean;
+    /** List all registered mind names */
+    list(): string[];
+}
+/**
+ * Mode registry for registered coordination modes.
+ */
+export interface ModeRegistry {
+    /** Register a coordination mode */
+    register(mode: CoordinationMode): void;
+    /** Get a registered mode by name */
+    get(name: string): CoordinationMode | undefined;
+    /** Check if a mode is registered */
+    has(name: string): boolean;
+    /** List all registered mode names */
+    list(): string[];
+}
+/**
+ * Options for starting a node execution.
+ */
+export interface StartNodeOptions {
+    /** Node ID to start */
+    nodeId: string;
+    /** Input data for the node */
+    input: unknown;
+    /** Iteration number (for loops) */
+    iteration?: number;
+}
+/**
+ * Options for handling node completion.
+ */
+export interface NodeCompletionOptions {
+    /** Node ID that completed */
+    nodeId: string;
+    /** Output from the node */
+    output: unknown;
+    /** Artifacts created by the node */
+    artifacts?: Array<{
+        ref: ArtifactRef;
+        hints: unknown;
+    }>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,14 @@
+// ABOUTME: Core types for kernel orchestration
+// ABOUTME: Defines Kernel, KernelSession, and session event types
+/**
+ * Session status values.
+ */
+export const SESSION_STATUS = {
+    PENDING: 'pending',
+    RUNNING: 'running',
+    PAUSED: 'paused',
+    COMPLETED: 'completed',
+    FAILED: 'failed',
+    CANCELLED: 'cancelled',
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C,kEAAkE;AAmBlE;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;IAClB,MAAM,EAAE,QAAQ;IAChB,SAAS,EAAE,WAAW;IACtB,MAAM,EAAE,QAAQ;IAChB,SAAS,EAAE,WAAW;CACd,CAAC"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@inf-minds/kernel",
+  "version": "0.0.1",
+  "description": "Kernel orchestration for multi-mind coordination",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "echo 'No linter configured yet'"
+  },
+  "dependencies": {
+    "@inf-minds/coordination-modes": "workspace:*",
+    "@inf-minds/mindkit": "workspace:*",
+    "@inf-minds/jobs": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^2.0.0"
+  }
+}

package/src/condition-evaluator.ts

@@ -0,0 +1,168 @@
+// ABOUTME: Safe condition evaluation for graph edges and node exit conditions
+// ABOUTME: Uses sandboxed function execution for expression evaluation
+
+/**
+ * Context object passed to condition expressions.
+ */
+export interface ConditionContext {
+  /** Output from the source node */
+  output: unknown;
+  /** Current graph state */
+  graphState?: {
+    completedNodes: string[];
+    activeNodes: string[];
+    nodeOutputs?: Record<string, unknown>;
+  };
+  /** Current iteration count (for loops) */
+  iteration?: number;
+}
+
+/**
+ * Result of condition evaluation.
+ */
+export interface EvaluationResult {
+  /** Whether the condition evaluated to true */
+  result: boolean;
+  /** Error message if evaluation failed */
+  error?: string;
+}
+
+/**
+ * Evaluate a condition expression against a context.
+ *
+ * The condition is a JavaScript expression that has access to:
+ * - `output` - The output from the source node
+ * - `graphState` - Current graph execution state
+ * - `iteration` - Current iteration count (for loops)
+ *
+ * Examples:
+ * - `output.done === true`
+ * - `output.tasks.length > 0`
+ * - `iteration < 5`
+ * - `output.allTasksComplete`
+ * - `graphState.completedNodes.includes('research')`
+ *
+ * @param expression - JavaScript expression to evaluate
+ * @param context - Context object with output, graphState, iteration
+ * @returns Evaluation result with boolean result or error
+ */
+export function evaluateCondition(
+  expression: string,
+  context: ConditionContext
+): EvaluationResult {
+  try {
+    // Validate expression for safety
+    const validationError = validateExpression(expression);
+    if (validationError) {
+      return { result: false, error: validationError };
+    }
+
+    // Create sandboxed function
+    const fn = new Function(
+      'output',
+      'graphState',
+      'iteration',
+      `"use strict"; return (${expression});`
+    );
+
+    // Execute with context
+    const result = fn(
+      context.output,
+      context.graphState ?? { completedNodes: [], activeNodes: [] },
+      context.iteration ?? 0
+    );
+
+    // Coerce to boolean
+    return { result: Boolean(result) };
+  } catch (error) {
+    return {
+      result: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+/**
+ * Validate a condition expression for safety.
+ * Returns an error message if the expression is unsafe, undefined otherwise.
+ */
+function validateExpression(expression: string): string | undefined {
+  // Block potentially dangerous constructs
+  const blockedPatterns = [
+    /\beval\b/,
+    /\bFunction\b/,
+    /\bsetTimeout\b/,
+    /\bsetInterval\b/,
+    /\bsetImmediate\b/,
+    /\brequire\b/,
+    /\bimport\b/,
+    /\bprocess\b/,
+    /\bglobal\b/,
+    /\bglobalThis\b/,
+    /\bwindow\b/,
+    /\bdocument\b/,
+    /\bfetch\b/,
+    /\bXMLHttpRequest\b/,
+    /\bWebSocket\b/,
+    /\b__proto__\b/,
+    /\bconstructor\b/,
+    /\bprototype\b/,
+    /\bObject\.assign\b/,
+    /\bObject\.defineProperty\b/,
+    /\bReflect\b/,
+    /\bProxy\b/,
+  ];
+
+  for (const pattern of blockedPatterns) {
+    if (pattern.test(expression)) {
+      return `Expression contains blocked construct: ${pattern.source}`;
+    }
+  }
+
+  // Block assignment operators (but allow == and ===)
+  if (/[^=!<>]=[^=]/.test(expression) && !/=>/.test(expression)) {
+    return 'Expression contains assignment operator';
+  }
+
+  // Block function definitions
+  if (/\bfunction\b/.test(expression)) {
+    return 'Expression contains function definition';
+  }
+
+  return undefined;
+}
+
+/**
+ * Check if a string looks like a valid condition expression.
+ * This is a quick heuristic check, not a full validation.
+ */
+export function isValidConditionExpression(expression: string): boolean {
+  // Must be non-empty
+  if (!expression || expression.trim().length === 0) {
+    return false;
+  }
+
+  // Validate
+  const error = validateExpression(expression);
+  return error === undefined;
+}
+
+/**
+ * Common condition expressions for reference.
+ */
+export const COMMON_CONDITIONS = {
+  /** Node output indicates completion */
+  OUTPUT_DONE: 'output.done === true',
+  /** Node output indicates all tasks complete */
+  ALL_TASKS_COMPLETE: 'output.allTasksComplete',
+  /** Node has a delegated task */
+  HAS_DELEGATED_TASK: 'output.delegatedTask',
+  /** Output has items to process */
+  HAS_ITEMS: 'output.items && output.items.length > 0',
+  /** Iteration count under limit */
+  UNDER_MAX_ITERATIONS: 'iteration < 10',
+  /** Output indicates success */
+  SUCCESS: 'output.success === true',
+  /** Output indicates failure */
+  FAILURE: 'output.success === false',
+} as const;