@northflare/runner 0.0.1

package/src/services/RunnerAPIClient.ts

@@ -0,0 +1,135 @@
+/**
+ * HTTP API client for runner-specific endpoints
+ *
+ * Provides methods to interact with the server's runner API endpoints
+ * including fetching missed messages and other runner operations.
+ */
+
+import { createLogger } from "../utils/logger";
+import { RunnerConfig, RunnerMessage } from "../types";
+
+const logger = createLogger("RunnerAPIClient");
+
+export interface FetchMissedMessagesOptions {
+  since: Date | string;
+  limit?: number;
+}
+
+export class RunnerAPIClient {
+  private baseUrl: string;
+  private token: string;
+  private runnerId: string;
+
+  constructor(config: RunnerConfig) {
+    this.baseUrl = config.orchestratorUrl;
+    this.token = process.env["NORTHFLARE_RUNNER_TOKEN"] || "";
+    this.runnerId = config.runnerId || "";
+  }
+
+  /**
+   * Update the runner ID after registration
+   */
+  setRunnerId(runnerId: string): void {
+    this.runnerId = runnerId;
+  }
+
+  /**
+   * Fetch missed messages since a given timestamp
+   */
+  async fetchMissedMessages(
+    options: FetchMissedMessagesOptions
+  ): Promise<RunnerMessage[]> {
+    const since =
+      options.since instanceof Date
+        ? options.since.toISOString()
+        : options.since;
+    const limit = options.limit || 1000;
+
+    logger.debug(`Fetching missed messages since ${since} (limit: ${limit})`);
+
+    try {
+      const url = `${this.baseUrl}/api/runner/messages/since`;
+      const params = new URLSearchParams({
+        since,
+        limit: limit.toString(),
+      });
+
+      const response = await fetch(`${url}?${params}`, {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${this.token}`,
+          "X-Runner-Id": this.runnerId,
+          "Content-Type": "application/json",
+        },
+      });
+
+      if (!response.ok) {
+        const error = await response.text();
+        throw new Error(
+          `Failed to fetch missed messages: ${response.status} - ${error}`
+        );
+      }
+
+      const data = (await response.json()) as any;
+
+      // Transform the raw database records to our internal RunnerMessage format
+      const messages: RunnerMessage[] = data.messages.map((msg: any) => ({
+        id: msg.id,
+        direction: msg.direction,
+        runnerId: msg.runner || msg.runnerId,
+        taskId: msg.task || msg.taskId || null,
+        workspaceId: msg.workspace || msg.workspaceId || null,
+        conversationId: msg.conversation || msg.conversationId || null,
+        conversationObjectType: msg.conversationObjectType,
+        conversationObjectId: msg.conversationObjectId,
+        payload: msg.payload,
+        expiresAt: msg.expiresAt,
+        createdAt: msg.createdAt,
+      }));
+
+      logger.info(`Fetched ${messages.length} missed messages`);
+      return messages;
+    } catch (error) {
+      logger.error("Failed to fetch missed messages:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Send a message acknowledgment to update the high-water mark
+   */
+  async acknowledgeMessage(messageTimestamp: string): Promise<void> {
+    logger.debug(`Acknowledging message with timestamp: ${messageTimestamp}`);
+
+    try {
+      const response = await fetch(`${this.baseUrl}/api/runner/messages`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.token}`,
+          "X-Runner-Id": this.runnerId,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          method: "message.acknowledge",
+          params: {
+            runnerId: this.runnerId,
+            messageTimestamp,
+          },
+        }),
+      });
+
+      if (!response.ok) {
+        const error = await response.text();
+        throw new Error(
+          `Failed to acknowledge message: ${response.status} - ${error}`
+        );
+      }
+
+      logger.debug("Message acknowledged successfully");
+    } catch (error) {
+      logger.error("Failed to acknowledge message:", error);
+      throw error;
+    }
+  }
+}

package/src/services/SSEClient.ts

@@ -0,0 +1,258 @@
+/**
+ * SSE (Server-Sent Events) Client for real-time message streaming
+ * 
+ * Connects to the server's SSE endpoint to receive real-time runner messages
+ * and handles automatic reconnection with exponential backoff.
+ */
+
+import { createLogger } from '../utils/logger';
+import { RunnerConfig } from '../types';
+import { EventSource as NodeEventSource } from 'eventsource';
+
+const logger = createLogger('SSEClient');
+
+export interface SSEEvent {
+  id?: string;
+  type: string;
+  data: any;
+}
+
+export interface SSEClientOptions {
+  url: string;
+  runnerId: string;
+  token: string;
+  onMessage: (event: SSEEvent) => void;
+  onError?: (error: Error) => void;
+  onConnect?: () => void;
+  onDisconnect?: () => void;
+  reconnectInterval?: number;
+  maxReconnectInterval?: number;
+  reconnectMultiplier?: number;
+  maxReconnectAttempts?: number;
+}
+
+export class SSEClient {
+  private eventSource: EventSource | null = null;
+  private reconnectTimer: NodeJS.Timeout | null = null;
+  private reconnectAttempts = 0;
+  private currentReconnectInterval: number;
+  private isConnected = false;
+  private isStopped = false;
+  private lastEventId: string | undefined;
+
+  constructor(private options: SSEClientOptions) {
+    this.currentReconnectInterval = options.reconnectInterval || 1000;
+  }
+
+  /**
+   * Connect to the SSE endpoint
+   */
+  async connect(since?: string): Promise<void> {
+    if (this.eventSource) {
+      logger.warn('SSE client already connected');
+      return;
+    }
+
+    this.isStopped = false;
+
+    try {
+      // Build URL with query parameters
+      const url = new URL(this.options.url);
+      // Include token as query param as a fallback in case proxies strip headers
+      url.searchParams.set('token', this.options.token);
+      if (since) {
+        url.searchParams.set('since', since);
+      }
+
+      // Sanitize token from logs
+      const sanitized = new URL(url.toString());
+      if (sanitized.searchParams.has('token')) {
+        sanitized.searchParams.set('token', '[redacted]');
+      }
+      logger.info(`Connecting to SSE endpoint: ${sanitized.toString()}`);
+      logger.debug(`SSE auth header set: ${this.options.token ? 'yes' : 'no'}`);
+
+      // Create EventSource with authorization header (Node polyfill supports headers)
+      this.eventSource = new (NodeEventSource as any)(url.toString(), {
+        headers: {
+          'Authorization': `Bearer ${this.options.token}`,
+        },
+        withCredentials: false,
+      });
+
+      // Set up event listeners
+      this.eventSource!.onopen = () => {
+        logger.info('SSE connection established');
+        this.isConnected = true;
+        this.reconnectAttempts = 0;
+        this.currentReconnectInterval = this.options.reconnectInterval || 1000;
+        
+        if (this.options.onConnect) {
+          this.options.onConnect();
+        }
+      };
+
+      this.eventSource!.onmessage = (event: MessageEvent) => {
+        try {
+          const parsed = JSON.parse(event.data);
+          const envelope = parsed && typeof parsed === 'object' ? parsed : { data: parsed };
+          const inner = (envelope && 'data' in envelope) ? (envelope as any).data : parsed;
+          const sseEvent: SSEEvent = {
+            id: (envelope as any).id || (event as any).lastEventId,
+            type: (envelope as any).type || (event as any).type || 'message',
+            data: inner,
+          };
+
+          // Update last event ID for reconnection
+          if (sseEvent.id) {
+            this.lastEventId = sseEvent.id;
+          }
+
+          this.options.onMessage(sseEvent);
+        } catch (error) {
+          logger.error('Failed to parse SSE message:', error);
+        }
+      };
+
+      this.eventSource!.onerror = (error: Event) => {
+        logger.error('SSE connection error:', error);
+        this.isConnected = false;
+
+        if (this.options.onError) {
+          this.options.onError(new Error('SSE connection error'));
+        }
+
+        // Close the connection and attempt reconnection
+        this.disconnect();
+        
+        if (!this.isStopped) {
+          this.scheduleReconnect();
+        }
+      };
+
+      // Listen for specific event types
+      this.eventSource!.addEventListener('runner.message', ((event: MessageEvent) => {
+        try {
+          const parsed = JSON.parse(event.data);
+          const envelope = parsed && typeof parsed === 'object' ? parsed : { data: parsed };
+          const inner = (envelope && 'data' in envelope) ? (envelope as any).data : parsed;
+          const sseEvent: SSEEvent = {
+            id: (envelope as any).id || (event as any).lastEventId,
+            type: 'runner.message',
+            data: inner,
+          };
+
+          // Update last event ID
+          if (sseEvent.id) {
+            this.lastEventId = sseEvent.id;
+          }
+
+          this.options.onMessage(sseEvent);
+        } catch (error) {
+          logger.error('Failed to parse runner.message event:', error);
+        }
+      }) as any);
+
+      // Listen for connection established event
+      this.eventSource!.addEventListener('connection.established', ((event: MessageEvent) => {
+        logger.debug('Received connection.established event:', event.data);
+      }) as any);
+
+      // Listen for error events
+      this.eventSource!.addEventListener('error', ((event: MessageEvent) => {
+        logger.error('Received error event from server:', event.data);
+      }) as any);
+
+      // Listen for shutdown events
+      this.eventSource!.addEventListener('shutdown', ((event: MessageEvent) => {
+        logger.warn('Server is shutting down:', event.data);
+        this.stop();
+      }) as any);
+
+    } catch (error) {
+      logger.error('Failed to connect to SSE endpoint:', error);
+      
+      if (this.options.onError) {
+        this.options.onError(error instanceof Error ? error : new Error(String(error)));
+      }
+
+      // Schedule reconnection
+      if (!this.isStopped) {
+        this.scheduleReconnect();
+      }
+    }
+  }
+
+  /**
+   * Disconnect from the SSE endpoint
+   */
+  disconnect(): void {
+    if (this.eventSource) {
+      this.eventSource.close();
+      this.eventSource = null;
+      this.isConnected = false;
+
+      if (this.options.onDisconnect) {
+        this.options.onDisconnect();
+      }
+    }
+
+    // Clear reconnection timer
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+
+  /**
+   * Stop the client and prevent reconnection
+   */
+  stop(): void {
+    logger.info('Stopping SSE client');
+    this.isStopped = true;
+    this.disconnect();
+  }
+
+  /**
+   * Schedule a reconnection attempt
+   */
+  private scheduleReconnect(): void {
+    const maxAttempts = this.options.maxReconnectAttempts || Infinity;
+    
+    if (this.reconnectAttempts >= maxAttempts) {
+      logger.error(`Max reconnection attempts (${maxAttempts}) reached. Giving up.`);
+      return;
+    }
+
+    this.reconnectAttempts++;
+    
+    logger.info(`Scheduling reconnection attempt ${this.reconnectAttempts} in ${this.currentReconnectInterval}ms`);
+
+    this.reconnectTimer = setTimeout(() => {
+      this.connect(this.lastEventId);
+    }, this.currentReconnectInterval);
+
+    // Exponential backoff
+    const multiplier = this.options.reconnectMultiplier || 2;
+    const maxInterval = this.options.maxReconnectInterval || 60000;
+    
+    this.currentReconnectInterval = Math.min(
+      this.currentReconnectInterval * multiplier,
+      maxInterval
+    );
+  }
+
+  /**
+   * Check if the client is currently connected
+   */
+  isConnectedToServer(): boolean {
+    return this.isConnected;
+  }
+
+  /**
+   * Get the last received event ID
+   */
+  getLastEventId(): string | undefined {
+    return this.lastEventId;
+  }
+}

package/src/types/claude.ts

@@ -0,0 +1,55 @@
+/**
+ * Types related to Claude SDK integration
+ */
+
+import { Conversation } from "@botanicastudios/claude-code-sdk-ts";
+
+// Repository information passed in conversation config
+export interface RepositoryInfo {
+  url: string;
+  branch: string;
+  commit?: string;
+  type?: "github" | "local"; // Repository type
+  localPath?: string; // For local repositories
+}
+
+// Extended conversation config with repository info
+export interface ConversationConfig {
+  systemPrompt?: string;
+  accessToken?: string;
+  accessKey?: string; // TODO remove
+  workspaceId?: string;
+  githubToken?: string;
+  anthropicApiKey?: string; // API key provided via runner message
+  mcpServers?: Record<string, any>;
+  repository?: RepositoryInfo; // Repository details from orchestrator
+  sessionId?: string; // For resume operations
+  runnerRepoPath?: string; // Path to local runner repo for local workspaces
+}
+
+// Internal conversation tracking
+export interface ConversationContext {
+  conversationId: string; // Primary key - our conversation.id from the database
+  agentSessionId: string; // SDK session ID (from SDK's onSessionId callback)
+  conversationObjectType: "Task" | "TaskPlan";
+  conversationObjectId: string;
+  taskId?: string; // Optional for non-task conversations
+  workspaceId?: string;
+  status: "starting" | "active" | "stopping" | "stopped" | "error";
+  config: ConversationConfig;
+  startedAt: Date;
+  lastActivityAt: Date;
+  conversation?: Conversation; // Claude SDK conversation instance (stateful)
+
+  // Additional conversation details from database
+  model: string;
+  globalInstructions: string;
+  workspaceInstructions: string;
+  permissionsMode: string;
+}
+
+// Message type for initial messages
+export interface Message {
+  content: string;
+  role?: "user" | "assistant";
+}

package/src/types/computer-name.d.ts

@@ -0,0 +1,4 @@
+declare module 'computer-name' {
+  function computerName(): Promise<string>;
+  export = computerName;
+}

package/src/types/index.ts

@@ -0,0 +1,63 @@
+/**
+ * Main type definitions for the runner app
+ */
+
+export * from "./messages";
+export * from "./claude";
+export * from "./runner-interface";
+
+// Retry strategy types
+export type RetryStrategy = "none" | "interval" | "exponential";
+
+// RunnerRepo type for local runner repos
+export interface RunnerRepo {
+  uuid?: string; // UUID for identifying the repo across runner restarts
+  name: string;
+  path: string;
+}
+
+// Runner configuration (in-memory)
+export interface RunnerConfig {
+  runnerId?: string; // Stable external ID from server (for namespacing state/config)
+  orchestratorUrl: string; // From process.env.NORTHFLARE_ORCHESTRATOR_URL
+  dataDir: string;
+  workspaceDir?: string; // Directory for workspace/repository operations
+  heartbeatInterval: number;
+  retryStrategy: RetryStrategy; // Strategy for registration retries
+  retryIntervalSecs: number; // For interval strategy
+  retryDurationSecs: number; // Max duration for exponential strategy
+  runnerRepos?: RunnerRepo[]; // In-memory: repos for this specific runner session
+  // Authentication via environment variable or --token CLI option
+  // process.env.NORTHFLARE_RUNNER_TOKEN
+  // This token is generated by the server and must be provided
+  // either as an environment variable or via the --token CLI flag
+}
+
+// Config file format (on-disk)
+export interface RunnerConfigFile {
+  orchestratorUrl?: string;
+  dataDir?: string;
+  workspaceDir?: string;
+  heartbeatInterval?: number;
+  retryStrategy?: RetryStrategy;
+  retryIntervalSecs?: number;
+  retryDurationSecs?: number;
+  runnerRepos?: Record<string, RunnerRepo[]>; // On-disk: namespaced by runnerId (stable external ID)
+}
+
+// Repository management types
+export interface WorkspaceRepository {
+  workspaceId: string;
+  repoUrl: string;
+  branch: string;
+  localPath: string;
+  lastAccessed: Date;
+}
+
+// Environment configuration
+export interface EnvironmentConfig {
+  NORTHFLARE_RUNNER_TOKEN: string;
+  NORTHFLARE_WORKSPACE_DIR: string;
+  NORTHFLARE_ORCHESTRATOR_URL: string;
+  DEBUG?: string;
+}

package/src/types/messages.ts

@@ -0,0 +1,39 @@
+/**
+ * JSONRPC message types for communication between runner and orchestrator
+ */
+
+export interface JsonRpcMessage {
+  jsonrpc: "2.0";
+  id?: string | number;
+  method?: string;
+  params?: any;
+  result?: any;
+  error?: JsonRpcError;
+}
+
+export interface JsonRpcError {
+  code: number;
+  message: string;
+  data?: any;
+}
+
+// Messages received from orchestrator via SSE
+export interface RunnerMessage {
+  id: string;
+  direction: "to_runner" | "to_orchestrator";
+  runnerId: string;
+  taskId: string | null; // Task ID from orchestrator for correlation (optional)
+  workspaceId: string | null; // Workspace ID for workspace-scoped messages
+  conversationObjectType?: "Task" | "TaskPlan";
+  conversationObjectId?: string;
+  conversationId?: string; // Conversation ID for direct conversation management
+  payload: JsonRpcMessage;
+  createdAt: string;
+  expiresAt: string;
+}
+
+// Method handler type
+export type MethodHandler = (
+  params: any,
+  message: RunnerMessage
+) => Promise<void>;

package/src/types/runner-interface.ts

@@ -0,0 +1,34 @@
+/**
+ * Interface for RunnerApp to ensure compatibility between different implementations
+ */
+
+import { RunnerConfig, ConversationContext, JsonRpcMessage } from './index';
+import { ClaudeManager } from '../components/claude-sdk-manager';
+import { EnhancedRepositoryManager } from '../components/enhanced-repository-manager';
+
+export interface IRunnerApp {
+  // Core methods
+  notify(method: string, params: any): Promise<void>;
+  sendToOrchestrator(message: JsonRpcMessage): Promise<any>;
+  
+  // Conversation management
+  getConversationContext(conversationId: string): ConversationContext | undefined;
+  
+  // Configuration and state
+  get config_(): RunnerConfig;
+  get activeConversations_(): Map<string, ConversationContext>;
+  get claudeManager_(): ClaudeManager;
+  get repositoryManager_(): EnhancedRepositoryManager;
+  
+  // Runner state
+  getRunnerId(): string | undefined;
+  getRunnerUid(): string | null;
+  getLastProcessedAt(): Date | null;
+  getIsActiveRunner(): boolean;
+  setIsActiveRunner(active: boolean): void;
+  setLastProcessedAt(timestamp: Date | null): void;
+  getPreHandoffConversations(): Set<string>;
+  
+  // Optional methods for SSE implementation
+  updateLastProcessedAt?(timestamp: Date | null): Promise<void>;
+}