@inf-minds/kernel 0.0.1

package/src/graph-executor.ts

@@ -0,0 +1,315 @@
+// ABOUTME: Graph executor for coordination mode execution
+// ABOUTME: Handles node scheduling, edge traversal, and state management
+
+import type { CoordinationMode } from '@inf-minds/coordination-modes';
+import type { GraphState, GraphNodeState } from '@inf-minds/jobs';
+import { evaluateCondition, type ConditionContext } from './condition-evaluator.js';
+
+/**
+ * Result of determining the next nodes to execute.
+ */
+export interface NextNodesResult {
+  /** Node IDs to start executing */
+  nodesToStart: string[];
+  /** Node IDs that were skipped (condition not met) */
+  skippedNodes: string[];
+  /** Whether the session should complete */
+  shouldComplete: boolean;
+  /** Final output if session should complete */
+  finalOutput?: unknown;
+}
+
+/**
+ * Options for determining next nodes.
+ */
+export interface DetermineNextNodesOptions {
+  /** The coordination mode */
+  mode: CoordinationMode;
+  /** Current graph state */
+  graphState: GraphState;
+  /** Node that just completed (or null if starting) */
+  completedNodeId: string | null;
+  /** Output from the completed node */
+  completedOutput: unknown;
+}
+
+/**
+ * Determine which nodes should be executed next after a node completes.
+ *
+ * This function:
+ * 1. Finds outgoing edges from the completed node
+ * 2. Evaluates edge conditions
+ * 3. Handles loop logic (exit conditions and max iterations)
+ * 4. Checks if session should complete
+ */
+export function determineNextNodes(options: DetermineNextNodesOptions): NextNodesResult {
+  const { mode, graphState, completedNodeId, completedOutput } = options;
+  const nodesToStart: string[] = [];
+  const skippedNodes: string[] = [];
+
+  // If no completed node, we're starting - go to entry node
+  if (!completedNodeId) {
+    return {
+      nodesToStart: [mode.graph.entryNode],
+      skippedNodes: [],
+      shouldComplete: false,
+    };
+  }
+
+  // Get the completed node definition
+  const completedNode = mode.graph.nodes[completedNodeId];
+  if (!completedNode) {
+    return {
+      nodesToStart: [],
+      skippedNodes: [],
+      shouldComplete: true,
+      finalOutput: { error: `Node ${completedNodeId} not found in graph` },
+    };
+  }
+
+  // Check if this is an exit node
+  const isExitNode = mode.graph.exitNodes.includes(completedNodeId);
+
+  // Count iterations for loop handling
+  const currentIteration = graphState.nodes[completedNodeId]?.jobId
+    ? countIterations(graphState, completedNodeId)
+    : 0;
+
+  // Build condition context (reused for edge and exit conditions)
+  const context: ConditionContext = {
+    output: completedOutput,
+    graphState: {
+      completedNodes: graphState.completedNodes,
+      activeNodes: graphState.activeNodes,
+      nodeOutputs: extractNodeOutputs(graphState),
+    },
+    iteration: currentIteration,
+  };
+
+  // Find outgoing edges
+  const outgoingEdges = mode.graph.edges.filter((e) => e.from === completedNodeId);
+
+  // Evaluate conditions for each outgoing edge FIRST
+  for (const edge of outgoingEdges) {
+    if (edge.condition) {
+      const evalResult = evaluateCondition(edge.condition, context);
+
+      if (evalResult.result) {
+        nodesToStart.push(edge.to);
+      } else {
+        skippedNodes.push(edge.to);
+      }
+    } else {
+      // No condition - always traverse
+      nodesToStart.push(edge.to);
+    }
+  }
+
+  // If we have nodes to traverse, go to them (regardless of exit condition)
+  if (nodesToStart.length > 0) {
+    return {
+      nodesToStart,
+      skippedNodes,
+      shouldComplete: false,
+    };
+  }
+
+  // No edges to traverse - check exit condition for potential looping
+  if (completedNode.exitCondition) {
+    const exitResult = evaluateCondition(completedNode.exitCondition, context);
+
+    // If exit condition is NOT met and under max iterations, loop back
+    if (!exitResult.result) {
+      const maxIterations = completedNode.maxIterations ?? Infinity;
+      if (currentIteration < maxIterations) {
+        // Loop: re-execute this node
+        return {
+          nodesToStart: [completedNodeId],
+          skippedNodes,
+          shouldComplete: false,
+        };
+      }
+    }
+    // Exit condition met or max iterations reached - session should complete
+  }
+
+  // No edges taken and either:
+  // - No exit condition (so we just complete)
+  // - Exit condition is met
+  // - Max iterations reached
+  if (isExitNode || outgoingEdges.length === 0) {
+    return {
+      nodesToStart: [],
+      skippedNodes,
+      shouldComplete: true,
+      finalOutput: completedOutput,
+    };
+  }
+
+  // Dead end but not an exit node - this is a graph issue
+  return {
+    nodesToStart: [],
+    skippedNodes,
+    shouldComplete: true,
+    finalOutput: { error: `Node ${completedNodeId} has no traversable edges and is not an exit node` },
+  };
+}
+
+/**
+ * Count how many times a node has been executed in this session.
+ */
+function countIterations(graphState: GraphState, nodeId: string): number {
+  // In the current model, we track iterations through job count
+  // For now, count how many times the node appears in completedNodes
+  // A more robust implementation would track this in the node state
+  return graphState.completedNodes.filter((id) => id === nodeId).length + 1;
+}
+
+/**
+ * Extract node outputs from graph state.
+ */
+function extractNodeOutputs(graphState: GraphState): Record<string, unknown> {
+  const outputs: Record<string, unknown> = {};
+  for (const [nodeId, nodeState] of Object.entries(graphState.nodes)) {
+    if (nodeState.output !== undefined) {
+      outputs[nodeId] = nodeState.output;
+    }
+  }
+  return outputs;
+}
+
+/**
+ * Update graph state when a node starts.
+ */
+export function updateStateForNodeStart(
+  graphState: GraphState,
+  nodeId: string,
+  jobId: string
+): GraphState {
+  const nodeState: GraphNodeState = graphState.nodes[nodeId] ?? {
+    nodeId,
+    status: 'pending',
+  };
+
+  return {
+    ...graphState,
+    nodes: {
+      ...graphState.nodes,
+      [nodeId]: {
+        ...nodeState,
+        status: 'active',
+        jobId,
+        startedAt: new Date().toISOString(),
+      },
+    },
+    activeNodes: [...graphState.activeNodes.filter((id) => id !== nodeId), nodeId],
+  };
+}
+
+/**
+ * Update graph state when a node completes.
+ */
+export function updateStateForNodeComplete(
+  graphState: GraphState,
+  nodeId: string,
+  output: unknown
+): GraphState {
+  const nodeState = graphState.nodes[nodeId];
+  if (!nodeState) {
+    return graphState;
+  }
+
+  return {
+    ...graphState,
+    nodes: {
+      ...graphState.nodes,
+      [nodeId]: {
+        ...nodeState,
+        status: 'completed',
+        output,
+        completedAt: new Date().toISOString(),
+      },
+    },
+    activeNodes: graphState.activeNodes.filter((id) => id !== nodeId),
+    completedNodes: [...graphState.completedNodes, nodeId],
+  };
+}
+
+/**
+ * Update graph state when a node fails.
+ */
+export function updateStateForNodeFailure(
+  graphState: GraphState,
+  nodeId: string,
+  error: string
+): GraphState {
+  const nodeState = graphState.nodes[nodeId];
+  if (!nodeState) {
+    return graphState;
+  }
+
+  return {
+    ...graphState,
+    nodes: {
+      ...graphState.nodes,
+      [nodeId]: {
+        ...nodeState,
+        status: 'failed',
+        error,
+        completedAt: new Date().toISOString(),
+      },
+    },
+    activeNodes: graphState.activeNodes.filter((id) => id !== nodeId),
+    failedNodes: [...graphState.failedNodes, nodeId],
+  };
+}
+
+/**
+ * Update graph state when a node is skipped.
+ */
+export function updateStateForNodeSkipped(
+  graphState: GraphState,
+  nodeId: string,
+  reason: string
+): GraphState {
+  const nodeState: GraphNodeState = graphState.nodes[nodeId] ?? {
+    nodeId,
+    status: 'pending',
+  };
+
+  return {
+    ...graphState,
+    nodes: {
+      ...graphState.nodes,
+      [nodeId]: {
+        ...nodeState,
+        status: 'skipped',
+        error: reason,
+        completedAt: new Date().toISOString(),
+      },
+    },
+    skippedNodes: [...graphState.skippedNodes, nodeId],
+  };
+}
+
+/**
+ * Mark graph state as completed.
+ */
+export function markGraphComplete(graphState: GraphState): GraphState {
+  return {
+    ...graphState,
+    status: 'completed',
+    completedAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Mark graph state as failed.
+ */
+export function markGraphFailed(graphState: GraphState): GraphState {
+  return {
+    ...graphState,
+    status: 'failed',
+    completedAt: new Date().toISOString(),
+  };
+}

package/src/index.ts

@@ -0,0 +1,50 @@
+// ABOUTME: Kernel package entry point
+// ABOUTME: Exports kernel session orchestration and graph execution
+
+// Type exports
+export type {
+  SessionStatus,
+  Unsubscribe,
+  SessionFilter,
+  CreateSessionOptions,
+  SessionEvent,
+  KernelSession,
+  Kernel,
+  KernelOptions,
+  MindRegistry,
+  ModeRegistry,
+  StartNodeOptions,
+  NodeCompletionOptions,
+  GraphState,
+} from './types.js';
+
+// Constant exports
+export { SESSION_STATUS } from './types.js';
+
+// Registry exports
+export { createMindRegistry, createModeRegistry } from './registries/index.js';
+
+// Kernel factory
+export { createKernel } from './kernel.js';
+
+// Condition evaluator
+export {
+  evaluateCondition,
+  isValidConditionExpression,
+  COMMON_CONDITIONS,
+  type ConditionContext,
+  type EvaluationResult,
+} from './condition-evaluator.js';
+
+// Graph executor utilities
+export {
+  determineNextNodes,
+  updateStateForNodeStart,
+  updateStateForNodeComplete,
+  updateStateForNodeFailure,
+  updateStateForNodeSkipped,
+  markGraphComplete,
+  markGraphFailed,
+  type NextNodesResult,
+  type DetermineNextNodesOptions,
+} from './graph-executor.js';

package/src/kernel.ts

@@ -0,0 +1,242 @@
+// ABOUTME: Kernel factory for creating kernel instances
+// ABOUTME: The kernel manages sessions, minds, and coordination modes
+
+import { validateGraph, type CoordinationMode } from '@inf-minds/coordination-modes';
+import type { MindConfig } from '@inf-minds/mindkit';
+import { JOB_TYPE, type Job } from '@inf-minds/jobs';
+
+import type {
+  Kernel,
+  KernelOptions,
+  KernelSession,
+  CreateSessionOptions,
+  SessionFilter,
+  GraphState,
+} from './types.js';
+import { createMindRegistry, createModeRegistry } from './registries/index.js';
+import { KernelSessionImpl } from './session.js';
+
+/**
+ * Create a new kernel instance.
+ *
+ * The kernel is the central orchestrator for multi-mind coordination.
+ * It manages:
+ * - Mind configurations (registered by name)
+ * - Coordination modes (execution graphs)
+ * - Sessions (executing instances of modes)
+ *
+ * @param options - Kernel configuration options
+ * @returns A new Kernel instance
+ *
+ * @example
+ * ```ts
+ * const kernel = createKernel({
+ *   jobManager,
+ *   eventAppender,
+ *   artifactManager,
+ * });
+ *
+ * // Register minds
+ * kernel.registerMind('researcher', {
+ *   model: 'claude-sonnet-4-20250514',
+ *   systemPrompt: 'You are a research assistant...',
+ * });
+ *
+ * // Register modes
+ * kernel.registerMode(createPipelineMode({
+ *   steps: [
+ *     { id: 'research', mind: { type: 'registered', mindType: 'researcher' } },
+ *     { id: 'analyze', mind: { type: 'registered', mindType: 'analyzer' } },
+ *   ],
+ * }));
+ *
+ * // Create and run a session
+ * const session = await kernel.createSession({
+ *   mode: 'pipeline',
+ *   input: { topic: 'quantum computing' },
+ *   accountId: 'acc-123',
+ * });
+ * ```
+ */
+export function createKernel(options: KernelOptions): Kernel {
+  const { jobManager, eventAppender, artifactManager, defaultArtifactRouter } = options;
+
+  // Create registries
+  const mindRegistry = createMindRegistry();
+  const modeRegistry = createModeRegistry();
+
+  /**
+   * Resolve a mode from either a name or inline definition.
+   */
+  function resolveMode(modeRef: string | CoordinationMode): CoordinationMode {
+    if (typeof modeRef === 'string') {
+      const mode = modeRegistry.get(modeRef);
+      if (!mode) {
+        throw new Error(`Mode '${modeRef}' not found in registry`);
+      }
+      return mode;
+    }
+    return modeRef;
+  }
+
+  /**
+   * Create initial graph state for a new session.
+   */
+  function createInitialGraphState(mode: CoordinationMode): GraphState {
+    const nodes: Record<string, { nodeId: string; status: 'pending' }> = {};
+
+    for (const nodeId of Object.keys(mode.graph.nodes)) {
+      nodes[nodeId] = {
+        nodeId,
+        status: 'pending',
+      };
+    }
+
+    return {
+      nodes,
+      activeNodes: [],
+      completedNodes: [],
+      failedNodes: [],
+      skippedNodes: [],
+      startedAt: new Date().toISOString(),
+      status: 'running',
+    };
+  }
+
+  /**
+   * Wrap a job as a KernelSession.
+   */
+  async function wrapJobAsSession(job: Job): Promise<KernelSession> {
+    // Parse the job input to get mode name
+    const jobInput = job.input as { mode?: string; userInput?: unknown } | undefined;
+    const modeName = jobInput?.mode ?? 'unknown';
+
+    // Get the mode definition if available
+    const mode = modeRegistry.get(modeName);
+
+    return new KernelSessionImpl({
+      job,
+      mode,
+      modeName,
+      jobManager,
+      eventAppender,
+      artifactManager,
+      artifactRouter: defaultArtifactRouter,
+      mindRegistry,
+    });
+  }
+
+  return {
+    async createSession(sessionOptions: CreateSessionOptions): Promise<KernelSession> {
+      // Resolve the coordination mode
+      const mode = resolveMode(sessionOptions.mode);
+
+      // Validate the graph
+      const validation = validateGraph(mode.graph);
+      if (!validation.valid) {
+        throw new Error(`Invalid graph: ${validation.errors.join(', ')}`);
+      }
+
+      // Warn about issues (but don't fail)
+      if (validation.warnings.length > 0) {
+        console.warn(`Graph warnings: ${validation.warnings.join(', ')}`);
+      }
+
+      // Create initial graph state
+      const graphState = createInitialGraphState(mode);
+
+      // Generate artifact base path for this session
+      const sessionId = crypto.randomUUID();
+      const artifactBasePath = `/sessions/${sessionId}`;
+
+      // Create the parent job
+      const job = await jobManager.create({
+        type: JOB_TYPE.KERNEL_SESSION,
+        accountId: sessionOptions.accountId,
+        input: {
+          mode: mode.name,
+          userInput: sessionOptions.input,
+          metadata: sessionOptions.metadata,
+        },
+        graphState,
+        artifactBasePath,
+      });
+
+      // Create and return the session wrapper
+      const artifactRouter = sessionOptions.artifactRouter ?? defaultArtifactRouter;
+
+      return new KernelSessionImpl({
+        job,
+        mode,
+        modeName: mode.name,
+        jobManager,
+        eventAppender,
+        artifactManager,
+        artifactRouter,
+        mindRegistry,
+      });
+    },
+
+    async getSession(sessionId: string): Promise<KernelSession | null> {
+      const job = await jobManager.get(sessionId);
+
+      if (!job) {
+        return null;
+      }
+
+      // Verify it's a kernel-session job
+      if (job.type !== JOB_TYPE.KERNEL_SESSION) {
+        return null;
+      }
+
+      return wrapJobAsSession(job);
+    },
+
+    async listSessions(filter?: SessionFilter): Promise<KernelSession[]> {
+      // Use job manager to list kernel-session jobs
+      const result = await jobManager.list({
+        accountId: filter?.accountId ?? '', // Required by job manager
+        type: JOB_TYPE.KERNEL_SESSION,
+        status: filter?.status as Parameters<typeof jobManager.list>[0]['status'],
+        limit: filter?.limit,
+        offset: filter?.offset,
+      });
+
+      // Filter by mode if specified
+      let jobs = result.jobs;
+      if (filter?.mode) {
+        jobs = jobs.filter((job) => {
+          const input = job.input as { mode?: string } | undefined;
+          return input?.mode === filter.mode;
+        });
+      }
+
+      // Wrap jobs as sessions
+      return Promise.all(jobs.map(wrapJobAsSession));
+    },
+
+    registerMind(name: string, config: MindConfig): void {
+      mindRegistry.register(name, config);
+    },
+
+    getMind(name: string): MindConfig | undefined {
+      return mindRegistry.get(name);
+    },
+
+    registerMode(mode: CoordinationMode): void {
+      modeRegistry.register(mode);
+    },
+
+    getMode(name: string): CoordinationMode | undefined {
+      return modeRegistry.get(name);
+    },
+
+    listMindTypes(): string[] {
+      return mindRegistry.list();
+    },
+
+    listModeNames(): string[] {
+      return modeRegistry.list();
+    },
+  };
+}

package/src/registries/index.ts

@@ -0,0 +1,5 @@
+// ABOUTME: Registry exports
+// ABOUTME: Exports mind and mode registry factories
+
+export { createMindRegistry } from './mind-registry.js';
+export { createModeRegistry } from './mode-registry.js';

package/src/registries/mind-registry.ts

@@ -0,0 +1,38 @@
+// ABOUTME: Mind registry for storing named mind configurations
+// ABOUTME: Allows registering and retrieving mind configs by name
+
+import type { MindConfig } from '@inf-minds/mindkit';
+import type { MindRegistry } from '../types.js';
+
+/**
+ * Create a new mind registry.
+ *
+ * The registry stores named mind configurations that can be referenced
+ * in coordination mode graph nodes.
+ *
+ * @returns A new MindRegistry instance
+ */
+export function createMindRegistry(): MindRegistry {
+  const minds = new Map<string, MindConfig>();
+
+  return {
+    register(name: string, config: MindConfig): void {
+      if (minds.has(name)) {
+        throw new Error(`Mind '${name}' is already registered`);
+      }
+      minds.set(name, config);
+    },
+
+    get(name: string): MindConfig | undefined {
+      return minds.get(name);
+    },
+
+    has(name: string): boolean {
+      return minds.has(name);
+    },
+
+    list(): string[] {
+      return Array.from(minds.keys());
+    },
+  };
+}

package/src/registries/mode-registry.ts

@@ -0,0 +1,38 @@
+// ABOUTME: Mode registry for storing named coordination modes
+// ABOUTME: Allows registering and retrieving modes by name
+
+import type { CoordinationMode } from '@inf-minds/coordination-modes';
+import type { ModeRegistry } from '../types.js';
+
+/**
+ * Create a new mode registry.
+ *
+ * The registry stores coordination modes that can be used when
+ * creating kernel sessions.
+ *
+ * @returns A new ModeRegistry instance
+ */
+export function createModeRegistry(): ModeRegistry {
+  const modes = new Map<string, CoordinationMode>();
+
+  return {
+    register(mode: CoordinationMode): void {
+      if (modes.has(mode.name)) {
+        throw new Error(`Mode '${mode.name}' is already registered`);
+      }
+      modes.set(mode.name, mode);
+    },
+
+    get(name: string): CoordinationMode | undefined {
+      return modes.get(name);
+    },
+
+    has(name: string): boolean {
+      return modes.has(name);
+    },
+
+    list(): string[] {
+      return Array.from(modes.keys());
+    },
+  };
+}