@gmickel/gno 1.17.0 → 1.18.0

package/src/serve/background-runtime.ts

@@ -1,46 +1,20 @@
-// node:path resolve has no Bun equivalent for canonical process-relative paths.
-import { resolve } from "node:path";
+/** Backwards-compatible entrypoint for the shared resident runtime. */
 
 import type { Config } from "../config/types";
 import type { SyncResult } from "../ingestion";
-import type { DocumentEventBus } from "./doc-events";
+import type { SqliteAdapter } from "../store/sqlite/adapter";
 import type { EmbedResult, EmbedScheduler } from "./embed-scheduler";
 import type { ContextHolder } from "./routes/api";
-import type {
-  CollectionWatchCallbacks,
-  CollectionWatchService,
-} from "./watch-service";
+import type { CollectionWatchService } from "./watch-service";
 
-import { getIndexDbPath } from "../app/constants";
-import { INDEX_NAME_REQUIREMENTS, isValidIndexName } from "../app/index-name";
 import {
-  ensureDirectories,
-  formatConfigWarnings,
-  getConfigPaths,
-  isInitialized,
-  loadConfig,
-} from "../config";
-import { defaultSyncService } from "../ingestion";
-import { withContentTypeRules } from "../ingestion";
-import { getActivePreset } from "../llm/registry";
-import { SqliteAdapter } from "../store/sqlite/adapter";
-import {
-  createServerContext,
-  type CreateServerContextOptions,
-  disposeServerContext,
-  type ServerContext,
-} from "./context";
-import { createEmbedScheduler } from "./embed-scheduler";
-import { CollectionWatchService as DefaultCollectionWatchService } from "./watch-service";
+  startResidentRuntime,
+  type ResidentRuntimeDeps,
+  type ResidentRuntimeOptions,
+} from "./resident-runtime";
 
-export interface BackgroundRuntimeOptions {
-  configPath?: string;
-  index?: string;
-  requireCollections?: boolean;
-  offline?: boolean;
-  eventBus?: DocumentEventBus | null;
-  watchCallbacks?: CollectionWatchCallbacks;
-}
+export type BackgroundRuntimeOptions = ResidentRuntimeOptions;
+export type BackgroundRuntimeDeps = ResidentRuntimeDeps;
 
 export interface BackgroundRuntime {
   store: SqliteAdapter;
@@ -48,16 +22,13 @@ export interface BackgroundRuntime {
   actualConfigPath: string;
   ctxHolder: ContextHolder;
   scheduler: EmbedScheduler;
-  eventBus: DocumentEventBus | null;
+  eventBus: import("./doc-events").DocumentEventBus | null;
   watchService: CollectionWatchService;
   syncAll(options?: {
     gitPull?: boolean;
     runUpdateCmd?: boolean;
     triggerEmbed?: boolean;
-  }): Promise<{
-    syncResult: SyncResult;
-    embedResult: EmbedResult | null;
-  }>;
+  }): Promise<{ syncResult: SyncResult; embedResult: EmbedResult | null }>;
   dispose(): Promise<void>;
 }
 
@@ -65,180 +36,9 @@ export type BackgroundRuntimeResult =
   | { success: true; runtime: BackgroundRuntime }
   | { success: false; error: string };
 
-type BackgroundRuntimeDeps = {
-  isInitialized?: typeof isInitialized;
-  loadConfig?: typeof loadConfig;
-  getConfigPaths?: typeof getConfigPaths;
-  ensureDirectories?: typeof ensureDirectories;
-  storeFactory?: () => SqliteAdapter;
-  createServerContext?: (
-    store: SqliteAdapter,
-    config: Config,
-    options?: CreateServerContextOptions
-  ) => Promise<ServerContext>;
-  disposeServerContext?: (ctx: ServerContext) => Promise<void>;
-  createEmbedScheduler?: typeof createEmbedScheduler;
-  syncAllService?: typeof defaultSyncService.syncAll;
-  watchServiceFactory?: (options: {
-    collections: Config["collections"];
-    store: SqliteAdapter;
-    scheduler: EmbedScheduler | null;
-    eventBus?: DocumentEventBus | null;
-    callbacks?: CollectionWatchCallbacks;
-    syncOptions?: Parameters<typeof withContentTypeRules>[0];
-  }) => CollectionWatchService;
-};
-
 export async function startBackgroundRuntime(
   options: BackgroundRuntimeOptions = {},
   deps: BackgroundRuntimeDeps = {}
 ): Promise<BackgroundRuntimeResult> {
-  if (options.index !== undefined && !isValidIndexName(options.index)) {
-    return {
-      success: false,
-      error: `Invalid index name: ${INDEX_NAME_REQUIREMENTS}.`,
-    };
-  }
-  const syncAllService = deps.syncAllService
-    ? (...args: Parameters<typeof defaultSyncService.syncAll>) =>
-        deps.syncAllService!(...args)
-    : defaultSyncService.syncAll.bind(defaultSyncService);
-  const initialized = await (deps.isInitialized ?? isInitialized)(
-    options.configPath
-  );
-  if (!initialized) {
-    return { success: false, error: "GNO not initialized. Run: gno init" };
-  }
-
-  const configResult = await (deps.loadConfig ?? loadConfig)(
-    options.configPath
-  );
-  if (!configResult.ok) {
-    return { success: false, error: configResult.error.message };
-  }
-  for (const warning of formatConfigWarnings(configResult.warnings)) {
-    console.warn(warning);
-  }
-  const config = configResult.value;
-
-  if (options.requireCollections && config.collections.length === 0) {
-    return {
-      success: false,
-      error: "No collections configured. Run: gno collection add <path>",
-    };
-  }
-
-  await (deps.ensureDirectories ?? ensureDirectories)();
-
-  const store = deps.storeFactory ? deps.storeFactory() : new SqliteAdapter();
-  const dbPath = getIndexDbPath(options.index);
-  const paths = (deps.getConfigPaths ?? getConfigPaths)();
-  const actualConfigPath = resolve(options.configPath ?? paths.configFile);
-  store.setConfigPath(actualConfigPath);
-
-  const openResult = await store.open(dbPath, config.ftsTokenizer);
-  if (!openResult.ok) {
-    return { success: false, error: openResult.error.message };
-  }
-
-  const syncCollResult = await store.syncCollections(config.collections);
-  if (!syncCollResult.ok) {
-    await store.close();
-    return { success: false, error: syncCollResult.error.message };
-  }
-  const syncCtxResult = await store.syncContexts(config.contexts ?? []);
-  if (!syncCtxResult.ok) {
-    await store.close();
-    return { success: false, error: syncCtxResult.error.message };
-  }
-
-  const ctx = await (deps.createServerContext ?? createServerContext)(
-    store,
-    config,
-    {
-      offline: options.offline ?? false,
-      indexName: options.index,
-    }
-  );
-
-  const ctxHolder: ContextHolder = {
-    current: ctx,
-    config,
-    scheduler: null,
-    eventBus: options.eventBus ?? null,
-    watchService: null,
-  };
-
-  const scheduler = (deps.createEmbedScheduler ?? createEmbedScheduler)({
-    db: store.getRawDb(),
-    getEmbedPort: () => ctxHolder.current.embedPort,
-    getVectorIndex: () => ctxHolder.current.vectorIndex,
-    getModelUri: () => getActivePreset(ctxHolder.config).embed,
-  });
-  ctxHolder.scheduler = scheduler;
-  ctxHolder.current.scheduler = scheduler;
-  ctxHolder.current.eventBus = options.eventBus ?? null;
-
-  const watchService = (
-    deps.watchServiceFactory ??
-    ((watchOptions) => new DefaultCollectionWatchService(watchOptions))
-  )({
-    collections: config.collections,
-    store,
-    scheduler,
-    eventBus: options.eventBus ?? null,
-    callbacks: options.watchCallbacks,
-    syncOptions: withContentTypeRules({}, config),
-  });
-  watchService.start();
-  ctxHolder.watchService = watchService;
-  ctxHolder.current.watchService = watchService;
-
-  let disposed = false;
-
-  return {
-    success: true,
-    runtime: {
-      store,
-      config,
-      actualConfigPath,
-      ctxHolder,
-      scheduler,
-      eventBus: options.eventBus ?? null,
-      watchService,
-      async syncAll(syncOptions = {}) {
-        const syncResult = await syncAllService(
-          config.collections,
-          store,
-          withContentTypeRules(
-            {
-              gitPull: syncOptions.gitPull,
-              runUpdateCmd: syncOptions.runUpdateCmd,
-            },
-            config
-          )
-        );
-
-        let embedResult: EmbedResult | null = null;
-        if (syncOptions.triggerEmbed !== false) {
-          embedResult = await scheduler.triggerNow();
-        }
-
-        return { syncResult, embedResult };
-      },
-      async dispose() {
-        if (disposed) {
-          return;
-        }
-        disposed = true;
-        await Promise.resolve(watchService.dispose());
-        options.eventBus?.close();
-        scheduler.dispose();
-        await (deps.disposeServerContext ?? disposeServerContext)(
-          ctxHolder.current
-        );
-        await store.close();
-      },
-    },
-  };
+  return startResidentRuntime(options, deps);
 }

package/src/serve/embed-scheduler.ts

@@ -7,6 +7,7 @@
 
 import type { Database } from "bun:sqlite";
 
+import type { ModelLease } from "../llm/nodeLlamaCpp/lifecycle";
 import type { EmbeddingPort } from "../llm/types";
 import type { VectorIndexPort } from "../store/vector";
 
@@ -46,6 +47,9 @@ export interface EmbedSchedulerDeps {
   getVectorIndex: () => VectorIndexPort | null;
   /** Getter for current model URI (survives preset changes) */
   getModelUri: () => string;
+  acquireModelLease?: () => ModelLease;
+  onEmbedded?: (result: EmbedResult) => void;
+  embedBacklogFn?: typeof embedBacklog;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -63,7 +67,7 @@ export interface EmbedScheduler {
   getState(): EmbedSchedulerState;
 
   /** Cleanup on server shutdown */
-  dispose(): void;
+  dispose(): Promise<void>;
 }
 
 /**
@@ -71,7 +75,15 @@ export interface EmbedScheduler {
  * Uses getters to resolve dependencies at execution time (survives context reloads).
  */
 export function createEmbedScheduler(deps: EmbedSchedulerDeps): EmbedScheduler {
-  const { db, getEmbedPort, getVectorIndex, getModelUri } = deps;
+  const {
+    db,
+    getEmbedPort,
+    getVectorIndex,
+    getModelUri,
+    acquireModelLease,
+    onEmbedded,
+    embedBacklogFn = embedBacklog,
+  } = deps;
 
   // State
   let pendingCount = 0; // Track pending triggers (not actual docIds - we embed full backlog)
@@ -81,6 +93,7 @@ export function createEmbedScheduler(deps: EmbedSchedulerDeps): EmbedScheduler {
   let firstPendingAt: number | null = null;
   let nextRunAt: number | null = null; // Accurate timer due time
   let disposed = false;
+  let currentRun: Promise<EmbedResult | null> | null = null;
   let lastRunAt: number | null = null;
   let lastResult: EmbedResult | null = null;
 
@@ -103,20 +116,25 @@ export function createEmbedScheduler(deps: EmbedSchedulerDeps): EmbedScheduler {
       return { embedded: 0, errors: 0 };
     }
 
-    const result = await embedBacklog({
-      statsPort: stats,
-      embedPort,
-      vectorIndex,
-      modelUri,
-      batchSize: BATCH_SIZE,
-    });
-
-    if (!result.ok) {
-      console.error("[embed-scheduler] Embed failed:", result.error.message);
-      return { embedded: 0, errors: 0 };
+    const lease = acquireModelLease?.();
+    try {
+      const result = await embedBacklogFn({
+        statsPort: stats,
+        embedPort,
+        vectorIndex,
+        modelUri,
+        batchSize: BATCH_SIZE,
+      });
+
+      if (!result.ok) {
+        console.error("[embed-scheduler] Embed failed:", result.error.message);
+        return { embedded: 0, errors: 0 };
+      }
+      if (result.value.embedded > 0) onEmbedded?.(result.value);
+      return result.value;
+    } finally {
+      lease?.release();
     }
-
-    return result.value;
   }
 
   /**
@@ -166,41 +184,53 @@ export function createEmbedScheduler(deps: EmbedSchedulerDeps): EmbedScheduler {
   /**
    * Execute the embed run with concurrency guard.
    */
-  async function executeRun(): Promise<EmbedResult | null> {
+  function executeRun(): Promise<EmbedResult | null> {
     if (disposed || running) {
       needsRerun = true;
-      return null;
+      return Promise.resolve(null);
     }
 
-    running = true;
-    timer = null;
-    nextRunAt = null;
-
-    // Clear pending state at START so new notifications accumulate
-    pendingCount = 0;
-    firstPendingAt = null;
+    const operation = (async (): Promise<EmbedResult | null> => {
+      running = true;
+      timer = null;
+      nextRunAt = null;
 
-    let result: EmbedResult;
-    try {
-      result = await runEmbed();
-      lastRunAt = Date.now();
-      lastResult = result;
-    } finally {
-      running = false;
-    }
+      // Clear pending state at START so new notifications accumulate
+      pendingCount = 0;
+      firstPendingAt = null;
+
+      let result: EmbedResult;
+      try {
+        result = await runEmbed();
+        lastRunAt = Date.now();
+        lastResult = result;
+      } finally {
+        running = false;
+      }
 
-    // Check if we need to rerun (notifications arrived while running)
-    // Must be AFTER running=false so scheduleRun() actually schedules
-    if ((needsRerun || pendingCount > 0) && !disposed) {
-      needsRerun = false;
-      // Set firstPendingAt if we have pending work
-      if (pendingCount > 0 && firstPendingAt === null) {
-        firstPendingAt = Date.now();
+      // Check if we need to rerun (notifications arrived while running)
+      // Must be AFTER running=false so scheduleRun() actually schedules
+      if ((needsRerun || pendingCount > 0) && !disposed) {
+        needsRerun = false;
+        // Set firstPendingAt if we have pending work
+        if (pendingCount > 0 && firstPendingAt === null) {
+          firstPendingAt = Date.now();
+        }
+        scheduleRun();
       }
-      scheduleRun();
-    }
 
-    return result;
+      return result;
+    })();
+    currentRun = operation;
+    void operation.then(
+      () => {
+        if (currentRun === operation) currentRun = null;
+      },
+      () => {
+        if (currentRun === operation) currentRun = null;
+      }
+    );
+    return operation;
   }
 
   return {
@@ -263,13 +293,14 @@ export function createEmbedScheduler(deps: EmbedSchedulerDeps): EmbedScheduler {
       return state;
     },
 
-    dispose(): void {
+    async dispose(): Promise<void> {
       disposed = true;
       if (timer) {
         clearTimeout(timer);
         timer = null;
         nextRunAt = null;
       }
+      await currentRun;
     },
   };
 }

package/src/serve/index.ts

@@ -11,3 +11,12 @@ export {
   type BackgroundRuntimeResult,
   startBackgroundRuntime,
 } from "./background-runtime";
+export {
+  type ResidentGeneration,
+  type ResidentMode,
+  type ResidentRequestHandle,
+  type ResidentRuntime,
+  type ResidentRuntimeOptions,
+  type ResidentRuntimeResult,
+  startResidentRuntime,
+} from "./resident-runtime";

package/src/serve/jobs.ts

@@ -1,13 +1,8 @@
-/**
- * Background job tracker for API write operations.
- * Simple in-memory tracking with global mutex (one job at a time).
- *
- * @module src/serve/jobs
- */
+/** REST-compatible facade over the resident JobManager. */
 
+import type { JobManager, JobRecord } from "../core/job-manager";
 import type { SyncResult } from "../ingestion";
 
-// Job expiration: 1 hour
 const JOB_EXPIRATION_MS = 60 * 60 * 1000;
 
 export type JobType = "add" | "sync" | "embed";
@@ -42,44 +37,60 @@ export interface StartJobError {
 
 export type StartJobResult = StartJobSuccess | StartJobError;
 
-// Global state - only one job can run at a time
+// Standalone fallback retained for unit fixtures that do not construct a resident.
 let activeJobId: string | null = null;
 const jobs = new Map<string, JobStatus>();
 
-/**
- * Clean up expired jobs to prevent memory leaks.
- * Called on every job access.
- * Only expires completed/failed jobs - running jobs are never expired.
- */
+const fromResidentRecord = (record: JobRecord): JobStatus => ({
+  id: record.id,
+  type: record.type as JobType,
+  status: record.status,
+  createdAt: record.startedAt,
+  progress: record.progress,
+  result: record.result,
+  error: record.error,
+});
+
 function cleanupExpiredJobs(now = Date.now()): void {
   for (const [id, job] of jobs) {
-    // Never expire running jobs - only completed/failed
-    if (job.status === "running") {
-      continue;
-    }
-    if (now - job.createdAt > JOB_EXPIRATION_MS) {
+    if (job.status !== "running" && now - job.createdAt > JOB_EXPIRATION_MS) {
       jobs.delete(id);
     }
   }
 }
 
-/**
- * Start a background job.
- * Returns immediately with jobId; caller polls /api/jobs/:id for status.
- * Use updateJobProgress() to update progress during execution.
- *
- * @param type - Job type identifier
- * @param fn - Async function to run in background
- * @returns Job ID on success, or 409 error if job already running
- */
 export function startJob(
   type: JobType,
   fn: () => Promise<SyncResult>
-): StartJobResult {
-  // Cleanup expired jobs first
-  cleanupExpiredJobs();
+): StartJobResult;
+export function startJob(
+  type: JobType,
+  fn: () => Promise<SyncResult>,
+  manager: JobManager
+): Promise<StartJobResult>;
+export function startJob(
+  type: JobType,
+  fn: () => Promise<SyncResult>,
+  manager: JobManager | undefined
+): StartJobResult | Promise<StartJobResult>;
+export function startJob(
+  type: JobType,
+  fn: () => Promise<SyncResult>,
+  manager?: JobManager
+): StartJobResult | Promise<StartJobResult> {
+  if (manager) {
+    return manager.startJob(type, fn).then(
+      (jobId) => ({ ok: true, jobId }),
+      (error: unknown) => ({
+        ok: false,
+        error: error instanceof Error ? error.message : String(error),
+        status: 409,
+        activeJobId: manager.getActiveJob()?.id ?? "",
+      })
+    );
+  }
 
-  // Check if a job is already running
+  cleanupExpiredJobs();
   if (activeJobId) {
     return {
       ok: false,
@@ -88,21 +99,14 @@ export function startJob(
       activeJobId,
     };
   }
-
   const jobId = crypto.randomUUID();
   activeJobId = jobId;
-
-  const jobStatus: JobStatus = {
+  jobs.set(jobId, {
     id: jobId,
     type,
     status: "running",
     createdAt: Date.now(),
-  };
-  jobs.set(jobId, jobStatus);
-
-  // Run in background (don't await)
-  // Wrap with Promise.resolve().then() to catch sync throws from fn()
-  // Without this, a sync throw would leave activeJobId set forever (deadlock)
+  });
   Promise.resolve()
     .then(fn)
     .then((result) => {
@@ -112,73 +116,67 @@ export function startJob(
         job.result = result;
       }
     })
-    .catch((e) => {
+    .catch((error: unknown) => {
       const job = jobs.get(jobId);
       if (job) {
         job.status = "failed";
-        job.error = e instanceof Error ? e.message : String(e);
+        job.error = error instanceof Error ? error.message : String(error);
       }
     })
     .finally(() => {
       activeJobId = null;
     });
-
   return { ok: true, jobId };
 }
 
-/**
- * Get current status of a job.
- *
- * @param jobId - Job ID from startJob
- * @returns Job status or undefined if not found
- */
-export function getJobStatus(jobId: string): JobStatus | undefined {
+export function getJobStatus(
+  jobId: string,
+  manager?: JobManager
+): JobStatus | undefined {
+  if (manager) {
+    const record = manager.getJob(jobId);
+    return record ? fromResidentRecord(record) : undefined;
+  }
   cleanupExpiredJobs();
   return jobs.get(jobId);
 }
 
-/**
- * Get the currently active job ID, if any.
- */
-export function getActiveJobId(): string | null {
-  return activeJobId;
+export function getActiveJobId(manager?: JobManager): string | null {
+  return manager?.getActiveJob()?.id ?? activeJobId;
 }
 
-/**
- * Get the currently active job status, if any.
- */
-export function getActiveJob(): JobStatus | null {
-  if (!activeJobId) {
-    return null;
+export function getActiveJob(manager?: JobManager): JobStatus | null {
+  if (manager) {
+    const record = manager.getActiveJob();
+    return record ? fromResidentRecord(record) : null;
   }
-  return jobs.get(activeJobId) ?? null;
+  return activeJobId ? (jobs.get(activeJobId) ?? null) : null;
 }
 
-/**
- * Update job progress (called from within job execution).
- *
- * @param jobId - Job ID to update
- * @param progress - Current progress info
- */
-export function updateJobProgress(jobId: string, progress: JobProgress): void {
-  const job = jobs.get(jobId);
-  if (job) {
-    job.progress = progress;
+export function updateJobProgress(
+  jobId: string,
+  progress: JobProgress,
+  manager?: JobManager
+): void {
+  if (manager) {
+    manager.updateJobProgress(jobId, progress);
+    return;
   }
+  const job = jobs.get(jobId);
+  if (job) job.progress = progress;
 }
 
-/**
- * Get all jobs (for debugging/monitoring).
- */
-export function getAllJobs(): JobStatus[] {
+export function getAllJobs(manager?: JobManager): JobStatus[] {
+  if (manager) {
+    const listed = manager.listJobs(100);
+    return [...listed.active, ...listed.recent].map(fromResidentRecord);
+  }
   cleanupExpiredJobs();
   return Array.from(jobs.values());
 }
 
-/**
- * Clear all jobs (for testing).
- */
-export function clearAllJobs(): void {
+export function clearAllJobs(manager?: JobManager): void {
+  if (manager) manager.clear();
   jobs.clear();
   activeJobId = null;
 }