@sesamespace/hivemind 0.2.0 → 0.3.0

package/packages/runtime/src/fleet/worker-protocol.ts

@@ -0,0 +1,158 @@
+/**
+ * Shared types for Primary <-> Worker communication protocol.
+ *
+ * Communication is HTTP-based:
+ *   - Primary calls Worker endpoints to assign contexts, check health
+ *   - Worker calls Primary endpoints to register, report status
+ */
+
+// --- Worker Identity & Registration ---
+
+export interface WorkerInfo {
+  id: string;
+  url: string;
+  capabilities: WorkerCapabilities;
+  assigned_contexts: string[];
+  registered_at: string;
+  last_heartbeat: string;
+}
+
+export interface WorkerCapabilities {
+  max_contexts: number;
+  has_ollama: boolean;
+  has_memory_daemon: boolean;
+  available_models: string[];
+}
+
+export interface WorkerRegistrationRequest {
+  url: string;
+  capabilities: WorkerCapabilities;
+}
+
+export interface WorkerRegistrationResponse {
+  worker_id: string;
+  registered_at: string;
+}
+
+// --- Health Checks ---
+
+export type WorkerHealthStatus = "healthy" | "degraded" | "unreachable";
+
+export interface WorkerHealthResponse {
+  worker_id: string;
+  status: WorkerHealthStatus;
+  uptime_seconds: number;
+  assigned_contexts: string[];
+  active_context: string | null;
+  memory_daemon_ok: boolean;
+  ollama_ok: boolean;
+}
+
+// --- Context Assignment ---
+
+export interface ContextAssignment {
+  context_name: string;
+  context_description: string;
+  assigned_at: string;
+}
+
+export interface ContextAssignRequest {
+  context_name: string;
+  context_description: string;
+}
+
+export interface ContextAssignResponse {
+  context_name: string;
+  accepted: boolean;
+  reason?: string;
+}
+
+// --- Worker Status Reporting ---
+
+export type WorkerActivity = "idle" | "working" | "error";
+
+export interface WorkerStatus {
+  worker_id: string;
+  activity: WorkerActivity;
+  current_context: string | null;
+  current_task: string | null;
+  error?: string;
+  reported_at: string;
+}
+
+export interface WorkerStatusReport {
+  activity: WorkerActivity;
+  current_context: string | null;
+  current_task: string | null;
+  error?: string;
+}
+
+// --- Memory Sync ---
+
+/** L3 knowledge entries synced from Worker to Primary. */
+export interface SyncPullRequest {
+  worker_id: string;
+  context_name: string;
+  entries: SyncL3Entry[];
+}
+
+/** An L3 entry with a last-modified timestamp for conflict resolution. */
+export interface SyncL3Entry {
+  id: string;
+  source_episode_id: string;
+  context_name: string;
+  content: string;
+  promoted_at: string;
+  access_count: number;
+  connection_density: number;
+  updated_at: string;
+}
+
+export interface SyncPullResponse {
+  accepted: number;
+  rejected: number;
+}
+
+/** Global context updates pushed from Primary to Worker. */
+export interface SyncPushRequest {
+  entries: SyncL3Entry[];
+  episodes: SyncL2Episode[];
+}
+
+/** L2 episodes synced as append-only (no conflict resolution needed). */
+export interface SyncL2Episode {
+  id: string;
+  timestamp: string;
+  context_name: string;
+  role: string;
+  content: string;
+}
+
+export interface SyncPushResponse {
+  l3_accepted: number;
+  l2_appended: number;
+}
+
+// --- Protocol Constants ---
+
+export const WORKER_API_PREFIX = "/workers";
+
+/** Primary-side routes (Worker calls these) */
+export const PRIMARY_ROUTES = {
+  register: `${WORKER_API_PREFIX}/register`,
+  status: (workerId: string) => `${WORKER_API_PREFIX}/${encodeURIComponent(workerId)}/status`,
+  syncPull: `${WORKER_API_PREFIX}/sync/pull`,
+} as const;
+
+/** Worker-side routes (Primary calls these) */
+export const WORKER_ROUTES = {
+  health: "/health",
+  assign: "/assign",
+  unassign: (contextName: string) => `/assign/${encodeURIComponent(contextName)}`,
+  status: "/status",
+  syncPush: "/sync/push",
+} as const;
+
+export const DEFAULT_HEALTH_INTERVAL_MS = 30_000;
+export const HEALTH_TIMEOUT_MS = 5_000;
+export const DEFAULT_SYNC_INTERVAL_MS = 60_000;

package/packages/runtime/src/fleet/worker-server.ts

@@ -0,0 +1,246 @@
+/**
+ * Worker-side HTTP server that exposes endpoints for the Primary to call.
+ *
+ * Uses Node's built-in http module — no external framework needed for these few routes.
+ *
+ * Endpoints:
+ *   GET  /health                     — Health check
+ *   POST /assign                     — Accept a context assignment
+ *   DELETE /assign/:contextName      — Release a context
+ *   GET  /status                     — Current activity status
+ */
+
+import { createServer, type Server, type IncomingMessage, type ServerResponse } from "http";
+import type {
+  WorkerHealthResponse,
+  WorkerStatusReport,
+  ContextAssignRequest,
+  ContextAssignResponse,
+  ContextAssignment,
+  SyncPushRequest,
+  SyncPushResponse,
+} from "./worker-protocol.js";
+
+export interface WorkerServerOptions {
+  workerId: string;
+  port: number;
+  maxContexts?: number;
+  memoryDaemonUrl?: string;
+  ollamaUrl?: string;
+}
+
+export class WorkerServer {
+  private server: Server | null = null;
+  private workerId: string;
+  private port: number;
+  private startTime: number;
+  private assignedContexts: Map<string, ContextAssignment> = new Map();
+  private activeContext: string | null = null;
+  private currentTask: string | null = null;
+  private maxContexts: number;
+  private memoryDaemonUrl: string | null;
+  private ollamaUrl: string | null;
+  private onAssignCallback: ((contextName: string, description: string) => void) | null = null;
+  private onSyncPushCallback: ((req: SyncPushRequest) => Promise<SyncPushResponse>) | null = null;
+
+  constructor(opts: WorkerServerOptions) {
+    this.workerId = opts.workerId;
+    this.port = opts.port;
+    this.startTime = Date.now();
+    this.maxContexts = opts.maxContexts ?? 4;
+    this.memoryDaemonUrl = opts.memoryDaemonUrl ?? null;
+    this.ollamaUrl = opts.ollamaUrl ?? null;
+  }
+
+  /** Start listening. */
+  async start(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.server = createServer((req, res) => this.handleRequest(req, res));
+
+      this.server.on("error", reject);
+      this.server.listen(this.port, () => resolve());
+    });
+  }
+
+  /** Stop the server. */
+  async stop(): Promise<void> {
+    return new Promise((resolve) => {
+      if (!this.server) {
+        resolve();
+        return;
+      }
+      this.server.close(() => resolve());
+    });
+  }
+
+  getPort(): number {
+    return this.port;
+  }
+
+  getAssignedContexts(): string[] {
+    return Array.from(this.assignedContexts.keys());
+  }
+
+  setActiveContext(name: string | null): void {
+    this.activeContext = name;
+  }
+
+  setCurrentTask(taskId: string | null): void {
+    this.currentTask = taskId;
+  }
+
+  /** Register a callback for when a new context is assigned. */
+  onContextAssigned(cb: (contextName: string, description: string) => void): void {
+    this.onAssignCallback = cb;
+  }
+
+  /** Register a handler for incoming sync push requests from Primary. */
+  onSyncPush(cb: (req: SyncPushRequest) => Promise<SyncPushResponse>): void {
+    this.onSyncPushCallback = cb;
+  }
+
+  // --- Request Router ---
+
+  private async handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const url = new URL(req.url ?? "/", `http://localhost:${this.port}`);
+    const path = url.pathname;
+    const method = req.method ?? "GET";
+
+    try {
+      if (method === "GET" && path === "/health") {
+        return this.handleHealth(res);
+      }
+
+      if (method === "POST" && path === "/assign") {
+        const body = await readBody(req);
+        return this.handleAssign(body, res);
+      }
+
+      // DELETE /assign/:contextName
+      if (method === "DELETE" && path.startsWith("/assign/")) {
+        const contextName = decodeURIComponent(path.slice("/assign/".length));
+        return this.handleUnassign(contextName, res);
+      }
+
+      if (method === "GET" && path === "/status") {
+        return this.handleStatus(res);
+      }
+
+      if (method === "POST" && path === "/sync/push") {
+        const body = await readBody(req);
+        return this.handleSyncPush(body, res);
+      }
+
+      sendJson(res, 404, { error: "Not found" });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      sendJson(res, 500, { error: msg });
+    }
+  }
+
+  // --- Handlers ---
+
+  private handleHealth(res: ServerResponse): void {
+    const uptimeMs = Date.now() - this.startTime;
+
+    const body: WorkerHealthResponse = {
+      worker_id: this.workerId,
+      status: "healthy",
+      uptime_seconds: Math.floor(uptimeMs / 1000),
+      assigned_contexts: Array.from(this.assignedContexts.keys()),
+      active_context: this.activeContext,
+      memory_daemon_ok: this.memoryDaemonUrl !== null,
+      ollama_ok: this.ollamaUrl !== null,
+    };
+
+    sendJson(res, 200, body);
+  }
+
+  private handleAssign(raw: string, res: ServerResponse): void {
+    const req = JSON.parse(raw) as ContextAssignRequest;
+
+    if (this.assignedContexts.size >= this.maxContexts) {
+      const body: ContextAssignResponse = {
+        context_name: req.context_name,
+        accepted: false,
+        reason: "Worker at max context capacity",
+      };
+      sendJson(res, 200, body);
+      return;
+    }
+
+    const assignment: ContextAssignment = {
+      context_name: req.context_name,
+      context_description: req.context_description,
+      assigned_at: new Date().toISOString(),
+    };
+
+    this.assignedContexts.set(req.context_name, assignment);
+
+    // Notify the worker runtime about the new context
+    if (this.onAssignCallback) {
+      this.onAssignCallback(req.context_name, req.context_description);
+    }
+
+    const body: ContextAssignResponse = {
+      context_name: req.context_name,
+      accepted: true,
+    };
+    sendJson(res, 200, body);
+  }
+
+  private handleUnassign(contextName: string, res: ServerResponse): void {
+    const existed = this.assignedContexts.delete(contextName);
+
+    if (this.activeContext === contextName) {
+      this.activeContext = null;
+      this.currentTask = null;
+    }
+
+    sendJson(res, existed ? 200 : 404, {
+      context_name: contextName,
+      removed: existed,
+    });
+  }
+
+  private handleStatus(res: ServerResponse): void {
+    const report: WorkerStatusReport = {
+      activity: this.currentTask ? "working" : "idle",
+      current_context: this.activeContext,
+      current_task: this.currentTask,
+    };
+
+    sendJson(res, 200, report);
+  }
+
+  private async handleSyncPush(raw: string, res: ServerResponse): Promise<void> {
+    if (!this.onSyncPushCallback) {
+      sendJson(res, 501, { error: "Sync push handler not registered" });
+      return;
+    }
+
+    const req = JSON.parse(raw) as SyncPushRequest;
+    const result = await this.onSyncPushCallback(req);
+    sendJson(res, 200, result);
+  }
+}
+
+// --- Helpers ---
+
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (chunk: Buffer) => chunks.push(chunk));
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+    req.on("error", reject);
+  });
+}
+
+function sendJson(res: ServerResponse, status: number, body: unknown): void {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, {
+    "Content-Type": "application/json",
+    "Content-Length": Buffer.byteLength(payload),
+  });
+  res.end(payload);
+}

package/packages/runtime/src/index.ts

@@ -0,0 +1,57 @@
+export { Agent } from "./agent.js";
+export { MemoryClient } from "./memory-client.js";
+export { LLMClient } from "./llm-client.js";
+export { ContextManager } from "./context.js";
+export { TaskEngine } from "./task-engine.js";
+export { loadConfig } from "./config.js";
+export { buildSystemPrompt, buildMessages } from "./prompt.js";
+export { SesameClient } from "./sesame.js";
+export { startPipeline } from "./pipeline.js";
+
+export type { HivemindConfig, AgentConfig, LLMConfig, MemoryConfig, SesameConfig, WorkerModeConfig } from "./config.js";
+export type { ChatMessage, ChatResponse } from "./llm-client.js";
+export type {
+  Episode,
+  ScoredEpisode,
+  EpisodeInput,
+  ContextInfo,
+  CrossContextResult,
+  PromotionResult,
+  L3Entry,
+  TaskRecord,
+  TaskInput,
+} from "./memory-client.js";
+export type { AgentResponse } from "./agent.js";
+export type { SesameMessage } from "./sesame.js";
+export type { ContextMetadata, ContextSwitchResult } from "./context.js";
+export type { TaskCommand, TaskStatus } from "./task-engine.js";
+
+// Fleet (Phase 3)
+export { PrimaryClient } from "./fleet/primary-client.js";
+export { WorkerServer } from "./fleet/worker-server.js";
+export { WorkerRuntime, startWorker } from "./worker.js";
+export { FleetManager } from "./fleet/fleet-manager.js";
+export { WorkerMemorySync, PrimaryMemorySync } from "./fleet/memory-sync.js";
+export type { FleetDashboard, WorkerSummary, MigrationResult } from "./fleet/fleet-manager.js";
+export type { WorkerServerOptions } from "./fleet/worker-server.js";
+export type { WorkerSyncOptions, PrimarySyncOptions } from "./fleet/memory-sync.js";
+export type {
+  WorkerInfo,
+  WorkerCapabilities,
+  WorkerRegistrationRequest,
+  WorkerRegistrationResponse,
+  WorkerHealthResponse,
+  WorkerHealthStatus,
+  WorkerStatus,
+  WorkerStatusReport,
+  WorkerActivity,
+  ContextAssignment,
+  ContextAssignRequest,
+  ContextAssignResponse,
+  SyncPullRequest,
+  SyncPullResponse,
+  SyncPushRequest,
+  SyncPushResponse,
+  SyncL3Entry,
+  SyncL2Episode,
+} from "./fleet/worker-protocol.js";

package/packages/runtime/src/llm-client.ts

@@ -0,0 +1,65 @@
+import type { LLMConfig } from "./config.js";
+
+export interface ChatMessage {
+  role: "system" | "user" | "assistant";
+  content: string;
+}
+
+export interface ChatResponse {
+  content: string;
+  model: string;
+  usage?: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+  };
+}
+
+export class LLMClient {
+  private baseUrl: string;
+  private model: string;
+  private maxTokens: number;
+  private temperature: number;
+  private apiKey: string;
+
+  constructor(config: LLMConfig) {
+    this.baseUrl = config.base_url;
+    this.model = config.model;
+    this.maxTokens = config.max_tokens;
+    this.temperature = config.temperature;
+    this.apiKey = config.api_key ?? "";
+  }
+
+  async chat(messages: ChatMessage[]): Promise<ChatResponse> {
+    const resp = await fetch(`${this.baseUrl}/chat/completions`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...(this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}),
+      },
+      body: JSON.stringify({
+        model: this.model,
+        messages,
+        max_tokens: this.maxTokens,
+        temperature: this.temperature,
+      }),
+    });
+
+    if (!resp.ok) {
+      const body = await resp.text();
+      throw new Error(`LLM request failed: ${resp.status} ${body}`);
+    }
+
+    const data = (await resp.json()) as {
+      choices: Array<{ message: { content: string } }>;
+      model: string;
+      usage?: { prompt_tokens: number; completion_tokens: number; total_tokens: number };
+    };
+
+    return {
+      content: data.choices[0].message.content,
+      model: data.model,
+      usage: data.usage,
+    };
+  }
+}