@inf-minds/kernel 0.0.1

package/src/types.ts

@@ -0,0 +1,280 @@
+// ABOUTME: Core types for kernel orchestration
+// ABOUTME: Defines Kernel, KernelSession, and session event types
+
+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';
+
+// Re-export for convenience
+export type { GraphState } from '@inf-minds/jobs';
+
+/**
+ * Session status values.
+ */
+export const SESSION_STATUS = {
+  PENDING: 'pending',
+  RUNNING: 'running',
+  PAUSED: 'paused',
+  COMPLETED: 'completed',
+  FAILED: 'failed',
+  CANCELLED: 'cancelled',
+} as const;
+
+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 }>;
+}