@inf-minds/kernel 0.0.1

package/src/session.ts

@@ -0,0 +1,541 @@
+// ABOUTME: KernelSession implementation
+// ABOUTME: Wraps a kernel-session job and manages graph execution
+
+import type { CoordinationMode } from '@inf-minds/coordination-modes';
+import type {
+  JobManager,
+  EventAppender,
+  ArtifactManager,
+  ArtifactRef,
+  Job,
+  GraphState,
+} from '@inf-minds/jobs';
+import type { ArtifactRouter, VisibilityHints } from '@inf-minds/jobs';
+import { JOB_TYPE } from '@inf-minds/jobs';
+
+import type {
+  KernelSession,
+  SessionStatus,
+  SessionEvent,
+  Unsubscribe,
+  MindRegistry,
+} from './types.js';
+import { SESSION_STATUS } from './types.js';
+import {
+  determineNextNodes,
+  updateStateForNodeStart,
+  updateStateForNodeComplete,
+  updateStateForNodeFailure,
+  updateStateForNodeSkipped,
+  markGraphComplete,
+  markGraphFailed,
+} from './graph-executor.js';
+
+/**
+ * Options for creating a KernelSessionImpl.
+ */
+export interface KernelSessionImplOptions {
+  /** The parent kernel-session job */
+  job: Job;
+  /** The coordination mode (may be undefined if restored from job) */
+  mode?: CoordinationMode;
+  /** Mode name for display */
+  modeName: string;
+  /** JobManager for job lifecycle */
+  jobManager: JobManager;
+  /** EventAppender for event streaming */
+  eventAppender: EventAppender;
+  /** ArtifactManager for artifact operations */
+  artifactManager: ArtifactManager;
+  /** ArtifactRouter for routing decisions */
+  artifactRouter?: ArtifactRouter;
+  /** MindRegistry for resolving registered minds */
+  mindRegistry: MindRegistry;
+}
+
+/**
+ * Implementation of KernelSession.
+ *
+ * Manages the lifecycle of a kernel session, including:
+ * - Graph execution state
+ * - Node scheduling
+ * - Artifact routing
+ * - Event emission
+ */
+export class KernelSessionImpl implements KernelSession {
+  private readonly _job: Job;
+  private readonly _mode?: CoordinationMode;
+  private readonly _modeName: string;
+  private readonly _jobManager: JobManager;
+  private readonly _eventAppender: EventAppender;
+  private readonly _artifactManager: ArtifactManager;
+  private readonly _artifactRouter?: ArtifactRouter;
+  private readonly _mindRegistry: MindRegistry;
+  private readonly _subscribers: Set<(event: SessionEvent) => void>;
+  private _currentGraphState: GraphState;
+
+  constructor(options: KernelSessionImplOptions) {
+    this._job = options.job;
+    this._mode = options.mode;
+    this._modeName = options.modeName;
+    this._jobManager = options.jobManager;
+    this._eventAppender = options.eventAppender;
+    this._artifactManager = options.artifactManager;
+    this._artifactRouter = options.artifactRouter;
+    this._mindRegistry = options.mindRegistry;
+    this._subscribers = new Set();
+    this._currentGraphState = (options.job.graphState as GraphState) ?? {
+      nodes: {},
+      activeNodes: [],
+      completedNodes: [],
+      failedNodes: [],
+      skippedNodes: [],
+      startedAt: new Date().toISOString(),
+      status: 'running',
+    };
+  }
+
+  get id(): string {
+    return this._job.id;
+  }
+
+  get mode(): string {
+    return this._modeName;
+  }
+
+  get status(): SessionStatus {
+    // Map job status to session status
+    switch (this._job.status) {
+      case 'pending':
+        return SESSION_STATUS.PENDING;
+      case 'running':
+        return SESSION_STATUS.RUNNING;
+      case 'completed':
+        return SESSION_STATUS.COMPLETED;
+      case 'failed':
+        return SESSION_STATUS.FAILED;
+      case 'cancelled':
+        return SESSION_STATUS.CANCELLED;
+      default:
+        return SESSION_STATUS.PENDING;
+    }
+  }
+
+  get graphState(): GraphState {
+    return this._currentGraphState;
+  }
+
+  get artifactBasePath(): string {
+    return this._job.artifactBasePath ?? `/sessions/${this._job.id}`;
+  }
+
+  get accountId(): string {
+    return this._job.accountId;
+  }
+
+  /**
+   * Get the coordination mode for this session.
+   * May be undefined if the session was restored from a job without the mode.
+   */
+  get coordinationMode(): CoordinationMode | undefined {
+    return this._mode;
+  }
+
+  /**
+   * Get the artifact router for this session.
+   */
+  get artifactRouter(): ArtifactRouter | undefined {
+    return this._artifactRouter;
+  }
+
+  /**
+   * Get the mind registry for resolving mind configs.
+   */
+  get mindRegistryRef(): MindRegistry {
+    return this._mindRegistry;
+  }
+
+  async pause(): Promise<void> {
+    // Pause the session by updating the job
+    // Active nodes will complete but no new nodes will start
+    await this._emitEvent({ type: 'session_paused', timestamp: new Date() });
+    // In a full implementation, this would update the job status
+    // and prevent new node executions
+    throw new Error('pause() not yet implemented');
+  }
+
+  async resume(): Promise<void> {
+    // Resume a paused session
+    await this._emitEvent({ type: 'session_resumed', timestamp: new Date() });
+    // In a full implementation, this would restart graph traversal
+    throw new Error('resume() not yet implemented');
+  }
+
+  async cancel(): Promise<void> {
+    // Cancel the session
+    await this._jobManager.cancel(this._job.id);
+    await this._emitEvent({ type: 'session_cancelled', timestamp: new Date() });
+  }
+
+  subscribe(handler: (event: SessionEvent) => void): Unsubscribe {
+    this._subscribers.add(handler);
+    return () => {
+      this._subscribers.delete(handler);
+    };
+  }
+
+  async getArtifacts(path?: string): Promise<ArtifactRef[]> {
+    // List artifacts for this session
+    const artifacts = await this._artifactManager.listBySession(this._job.id);
+
+    if (path) {
+      // Filter by path prefix
+      return artifacts.filter((a) => a.name.startsWith(path));
+    }
+
+    return artifacts;
+  }
+
+  getNodeOutput(nodeId: string): unknown | null {
+    const nodeState = this.graphState.nodes[nodeId];
+    if (nodeState?.status === 'completed') {
+      return nodeState.output ?? null;
+    }
+    return null;
+  }
+
+  async waitForCompletion(): Promise<unknown> {
+    // Poll for completion
+    // In a real implementation, this would use events or long polling
+    const maxAttempts = 1000;
+    const pollInterval = 100;
+
+    for (let i = 0; i < maxAttempts; i++) {
+      const job = await this._jobManager.get(this._job.id);
+      if (!job) {
+        throw new Error(`Session ${this._job.id} not found`);
+      }
+
+      if (job.status === 'completed') {
+        return job.output;
+      }
+
+      if (job.status === 'failed') {
+        throw new Error(`Session failed: ${job.error ?? 'Unknown error'}`);
+      }
+
+      if (job.status === 'cancelled') {
+        throw new Error('Session was cancelled');
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, pollInterval));
+    }
+
+    throw new Error('Session timed out waiting for completion');
+  }
+
+  /**
+   * Emit a session event to all subscribers.
+   */
+  private async _emitEvent(event: SessionEvent): Promise<void> {
+    // Persist to event stream
+    await this._eventAppender.append({
+      jobId: this._job.id,
+      type: event.type,
+      payload: event,
+    });
+
+    // Notify subscribers
+    for (const handler of this._subscribers) {
+      try {
+        handler(event);
+      } catch (error) {
+        console.error('Error in session event handler:', error);
+      }
+    }
+  }
+
+  /**
+   * Start the session by executing the entry node.
+   */
+  async start(): Promise<void> {
+    if (!this._mode) {
+      throw new Error('Cannot start session without coordination mode');
+    }
+
+    // Emit session started event
+    await this._emitEvent({
+      type: 'session_started',
+      sessionId: this.id,
+      mode: this._modeName,
+      timestamp: new Date(),
+    });
+
+    // Determine first nodes to execute (entry node)
+    const nextNodes = determineNextNodes({
+      mode: this._mode,
+      graphState: this._currentGraphState,
+      completedNodeId: null,
+      completedOutput: null,
+    });
+
+    // Start each node
+    for (const nodeId of nextNodes.nodesToStart) {
+      await this._startNode(nodeId, this._getUserInput());
+    }
+  }
+
+  /**
+   * Handle completion of a node execution.
+   * Called by the coordinator when a mind-execution job completes.
+   */
+  async handleNodeComplete(
+    nodeId: string,
+    output: unknown,
+    artifacts?: Array<{ ref: ArtifactRef; hints: VisibilityHints }>
+  ): Promise<void> {
+    if (!this._mode) {
+      throw new Error('Cannot handle node completion without coordination mode');
+    }
+
+    // Update graph state
+    this._currentGraphState = updateStateForNodeComplete(
+      this._currentGraphState,
+      nodeId,
+      output
+    );
+
+    // Route artifacts if present
+    if (artifacts && this._artifactRouter) {
+      const routingContext = {
+        sessionId: this.id,
+        nodeId,
+        mindId: this._getNodeMindType(nodeId),
+        graphState: this._currentGraphState,
+        accountId: this.accountId,
+      };
+
+      await this._artifactRouter.routeOutputArtifacts(
+        artifacts.map((a) => ({ artifact: a.ref, hints: a.hints })),
+        routingContext
+      );
+    }
+
+    // Emit node completed event
+    await this._emitEvent({
+      type: 'node_completed',
+      nodeId,
+      output,
+      timestamp: new Date(),
+    });
+
+    // Determine next nodes
+    const nextNodes = determineNextNodes({
+      mode: this._mode,
+      graphState: this._currentGraphState,
+      completedNodeId: nodeId,
+      completedOutput: output,
+    });
+
+    // Handle skipped nodes
+    for (const skippedId of nextNodes.skippedNodes) {
+      this._currentGraphState = updateStateForNodeSkipped(
+        this._currentGraphState,
+        skippedId,
+        'Condition not met'
+      );
+
+      await this._emitEvent({
+        type: 'node_skipped',
+        nodeId: skippedId,
+        reason: 'Condition not met',
+        timestamp: new Date(),
+      });
+    }
+
+    // Check if session should complete
+    if (nextNodes.shouldComplete) {
+      await this._completeSession(nextNodes.finalOutput);
+      return;
+    }
+
+    // Start next nodes
+    for (const nextNodeId of nextNodes.nodesToStart) {
+      // Emit graph advanced event
+      await this._emitEvent({
+        type: 'graph_advanced',
+        fromNode: nodeId,
+        toNode: nextNodeId,
+        timestamp: new Date(),
+      });
+
+      await this._startNode(nextNodeId, output);
+    }
+  }
+
+  /**
+   * Handle failure of a node execution.
+   * Called by the coordinator when a mind-execution job fails.
+   */
+  async handleNodeFailure(nodeId: string, error: string): Promise<void> {
+    // Update graph state
+    this._currentGraphState = updateStateForNodeFailure(
+      this._currentGraphState,
+      nodeId,
+      error
+    );
+
+    // Emit node failed event
+    await this._emitEvent({
+      type: 'node_failed',
+      nodeId,
+      error,
+      timestamp: new Date(),
+    });
+
+    // For now, fail the entire session on any node failure
+    // A more sophisticated implementation could support error handling modes
+    await this._failSession(error);
+  }
+
+  /**
+   * Start execution of a specific node.
+   */
+  private async _startNode(nodeId: string, input: unknown): Promise<void> {
+    if (!this._mode) {
+      throw new Error('Cannot start node without coordination mode');
+    }
+
+    const node = this._mode.graph.nodes[nodeId];
+    if (!node) {
+      throw new Error(`Node ${nodeId} not found in graph`);
+    }
+
+    // Resolve mind config
+    const mindConfig = this._resolveMindConfig(node);
+
+    // Get input artifacts if router is available
+    let inputArtifacts: ArtifactRef[] = [];
+    if (this._artifactRouter) {
+      const routingContext = {
+        sessionId: this.id,
+        nodeId,
+        mindId: node.mind.mindType ?? nodeId,
+        graphState: this._currentGraphState,
+        accountId: this.accountId,
+      };
+
+      inputArtifacts = await this._artifactRouter.resolveInputArtifacts(routingContext);
+    }
+
+    // Create child job for mind execution
+    const childJob = await this._jobManager.create({
+      type: JOB_TYPE.MIND_EXECUTION,
+      accountId: this.accountId,
+      parentJobId: this.id,
+      nodeId,
+      input: {
+        nodeId,
+        mindConfig,
+        task: input,
+        artifacts: inputArtifacts,
+        iteration: this._getNodeIteration(nodeId),
+      },
+    });
+
+    // Update graph state
+    this._currentGraphState = updateStateForNodeStart(
+      this._currentGraphState,
+      nodeId,
+      childJob.id
+    );
+
+    // Emit node started event
+    await this._emitEvent({
+      type: 'node_started',
+      nodeId,
+      mindType: node.mind.mindType ?? nodeId,
+      jobId: childJob.id,
+      timestamp: new Date(),
+    });
+  }
+
+  /**
+   * Complete the session with final output.
+   */
+  private async _completeSession(output: unknown): Promise<void> {
+    this._currentGraphState = markGraphComplete(this._currentGraphState);
+
+    await this._jobManager.complete(this.id, output);
+
+    await this._emitEvent({
+      type: 'session_completed',
+      output,
+      timestamp: new Date(),
+    });
+  }
+
+  /**
+   * Fail the session with error.
+   */
+  private async _failSession(error: string): Promise<void> {
+    this._currentGraphState = markGraphFailed(this._currentGraphState);
+
+    await this._jobManager.fail(this.id, error);
+
+    await this._emitEvent({
+      type: 'session_failed',
+      error,
+      timestamp: new Date(),
+    });
+  }
+
+  /**
+   * Get the user input from the job.
+   */
+  private _getUserInput(): unknown {
+    const jobInput = this._job.input as { userInput?: unknown } | undefined;
+    return jobInput?.userInput;
+  }
+
+  /**
+   * Get the mind type for a node.
+   */
+  private _getNodeMindType(nodeId: string): string {
+    if (!this._mode) {
+      return nodeId;
+    }
+    const node = this._mode.graph.nodes[nodeId];
+    return node?.mind.mindType ?? nodeId;
+  }
+
+  /**
+   * Get the current iteration count for a node.
+   */
+  private _getNodeIteration(nodeId: string): number {
+    // Count how many times this node has been started
+    const completedCount = this._currentGraphState.completedNodes.filter(
+      (id) => id === nodeId
+    ).length;
+    return completedCount + 1;
+  }
+
+  /**
+   * Resolve mind config from a node's mind reference.
+   */
+  private _resolveMindConfig(node: { mind: { type: string; mindType?: string; config?: unknown } }): unknown {
+    if (node.mind.type === 'inline') {
+      return node.mind.config;
+    }
+
+    if (node.mind.type === 'registered' && node.mind.mindType) {
+      const config = this._mindRegistry.get(node.mind.mindType);
+      if (!config) {
+        throw new Error(`Mind type '${node.mind.mindType}' not found in registry`);
+      }
+      return config;
+    }
+
+    throw new Error(`Invalid mind reference type: ${node.mind.type}`);
+  }
+}