@gmickel/gno 0.6.0 → 0.7.0

package/src/llm/policy.ts

@@ -0,0 +1,84 @@
+/**
+ * Download policy resolution.
+ * Determines whether model downloads are allowed based on env/flags.
+ *
+ * @module src/llm/policy
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface DownloadPolicy {
+  /** True if network is disabled (no HF API calls at all) */
+  offline: boolean;
+  /** True if auto-download is allowed (may still be blocked by offline) */
+  allowDownload: boolean;
+}
+
+export interface PolicyFlags {
+  /** --offline CLI flag */
+  offline?: boolean;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Check if env var is set (non-empty and truthy).
+ * Treats "1", "true", "yes" as truthy. Empty string or "0" as falsy.
+ */
+export function envIsSet(
+  env: Record<string, string | undefined>,
+  key: string
+): boolean {
+  const val = env[key];
+  if (val === undefined || val === '') {
+    return false;
+  }
+  const lower = val.toLowerCase();
+  return lower === '1' || lower === 'true' || lower === 'yes';
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Main
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Resolve download policy from environment and CLI flags.
+ *
+ * Precedence (first wins):
+ * 1. --offline flag → offline=true, allowDownload=false
+ * 2. HF_HUB_OFFLINE=1 → offline=true, allowDownload=false
+ * 3. GNO_OFFLINE=1 → offline=true, allowDownload=false
+ * 4. GNO_NO_AUTO_DOWNLOAD=1 → offline=false, allowDownload=false
+ * 5. Default → offline=false, allowDownload=true
+ */
+export function resolveDownloadPolicy(
+  env: Record<string, string | undefined>,
+  flags: PolicyFlags
+): DownloadPolicy {
+  // 1. --offline flag takes highest precedence
+  if (flags.offline) {
+    return { offline: true, allowDownload: false };
+  }
+
+  // 2. HF_HUB_OFFLINE env var (standard HuggingFace offline mode)
+  if (envIsSet(env, 'HF_HUB_OFFLINE')) {
+    return { offline: true, allowDownload: false };
+  }
+
+  // 3. GNO_OFFLINE env var (GNO-specific offline mode)
+  if (envIsSet(env, 'GNO_OFFLINE')) {
+    return { offline: true, allowDownload: false };
+  }
+
+  // 4. GNO_NO_AUTO_DOWNLOAD env var (allow resolve but no download)
+  if (envIsSet(env, 'GNO_NO_AUTO_DOWNLOAD')) {
+    return { offline: false, allowDownload: false };
+  }
+
+  // 5. Default: allow downloads
+  return { offline: false, allowDownload: true };
+}

package/src/mcp/tools/query.ts

@@ -6,7 +6,9 @@
 
 import { join as pathJoin } from 'node:path';
 import { parseUri } from '../../app/constants';
+import { createNonTtyProgressRenderer } from '../../cli/progress';
 import { LlmAdapter } from '../../llm/nodeLlamaCpp/adapter';
+import { resolveDownloadPolicy } from '../../llm/policy';
 import { getActivePreset } from '../../llm/registry';
 import type {
   EmbeddingPort,
@@ -128,6 +130,12 @@ export function handleQuery(
       const preset = getActivePreset(ctx.config);
       const llm = new LlmAdapter(ctx.config);
 
+      // Resolve download policy from env (MCP has no CLI flags)
+      const policy = resolveDownloadPolicy(process.env, {});
+
+      // Non-TTY progress for MCP (periodic lines to stderr, not \r)
+      const downloadProgress = createNonTtyProgressRenderer();
+
       let embedPort: EmbeddingPort | null = null;
       let genPort: GenerationPort | null = null;
       let rerankPort: RerankPort | null = null;
@@ -135,7 +143,10 @@ export function handleQuery(
 
       try {
         // Create embedding port (for vector search) - optional
-        const embedResult = await llm.createEmbeddingPort(preset.embed);
+        const embedResult = await llm.createEmbeddingPort(preset.embed, {
+          policy,
+          onProgress: (progress) => downloadProgress('embed', progress),
+        });
         if (embedResult.ok) {
           embedPort = embedResult.value;
         }
@@ -164,7 +175,10 @@ export function handleQuery(
 
         // Create generation port (for expansion) - optional
         if (!noExpand) {
-          const genResult = await llm.createGenerationPort(preset.gen);
+          const genResult = await llm.createGenerationPort(preset.gen, {
+            policy,
+            onProgress: (progress) => downloadProgress('gen', progress),
+          });
           if (genResult.ok) {
             genPort = genResult.value;
           }
@@ -172,7 +186,10 @@ export function handleQuery(
 
         // Create rerank port - optional
         if (!noRerank) {
-          const rerankResult = await llm.createRerankPort(preset.rerank);
+          const rerankResult = await llm.createRerankPort(preset.rerank, {
+            policy,
+            onProgress: (progress) => downloadProgress('rerank', progress),
+          });
           if (rerankResult.ok) {
             rerankPort = rerankResult.value;
           }

package/src/mcp/tools/vsearch.ts

@@ -6,7 +6,9 @@
 
 import { join as pathJoin } from 'node:path';
 import { parseUri } from '../../app/constants';
+import { createNonTtyProgressRenderer } from '../../cli/progress';
 import { LlmAdapter } from '../../llm/nodeLlamaCpp/adapter';
+import { resolveDownloadPolicy } from '../../llm/policy';
 import { getActivePreset } from '../../llm/registry';
 import { formatQueryForEmbedding } from '../../pipeline/contextual';
 import type { SearchResult, SearchResults } from '../../pipeline/types';
@@ -109,9 +111,18 @@ export function handleVsearch(
       const preset = getActivePreset(ctx.config);
       const modelUri = preset.embed;
 
+      // Resolve download policy from env (MCP has no CLI flags)
+      const policy = resolveDownloadPolicy(process.env, {});
+
+      // Non-TTY progress for MCP (periodic lines to stderr, not \r)
+      const downloadProgress = createNonTtyProgressRenderer();
+
       // Create LLM adapter for embeddings
       const llm = new LlmAdapter(ctx.config);
-      const embedResult = await llm.createEmbeddingPort(modelUri);
+      const embedResult = await llm.createEmbeddingPort(modelUri, {
+        policy,
+        onProgress: (progress) => downloadProgress('embed', progress),
+      });
       if (!embedResult.ok) {
         throw new Error(
           `Failed to load embedding model: ${embedResult.error.message}. ` +

package/src/serve/config-sync.ts

@@ -0,0 +1,139 @@
+/**
+ * Config synchronization utilities for the API server.
+ * Ensures YAML config, DB tables, and in-memory context stay in sync.
+ *
+ * @module src/serve/config-sync
+ */
+
+import { loadConfig, saveConfig } from '../config';
+import type { Config } from '../config/types';
+import type { SqliteAdapter } from '../store/sqlite/adapter';
+import type { ContextHolder } from './routes/api';
+
+export interface ConfigSyncResult {
+  ok: true;
+  config: Config;
+}
+
+export interface ConfigSyncError {
+  ok: false;
+  error: string;
+  /** Error code - can be system codes or mutation-specific codes passed through */
+  code: string;
+}
+
+export type ApplyConfigResult = ConfigSyncResult | ConfigSyncError;
+
+export type MutationResult =
+  | { ok: true; config: Config }
+  | { ok: false; error: string; code: string };
+
+/**
+ * In-memory mutex for serializing config mutations.
+ * Prevents lost updates when multiple requests try to modify config concurrently.
+ */
+let configMutex: Promise<void> = Promise.resolve();
+
+/**
+ * Apply a config mutation atomically with serialization.
+ *
+ * Sequence:
+ * 1. Acquire mutex (serialize with other config mutations)
+ * 2. Load current config from YAML
+ * 3. Apply mutation function (receives fresh config)
+ * 4. Save updated config to YAML (source of truth)
+ * 5. Sync DB tables (collections, contexts)
+ * 6. Update in-memory context holder (both config and current.config)
+ *
+ * If DB sync fails after YAML write, the error is returned but YAML remains
+ * updated (it's the source of truth). Next server startup will re-sync.
+ *
+ * @param ctxHolder - Context holder with config and current ServerContext
+ * @param store - Database adapter for syncing tables
+ * @param mutate - Async mutation function that receives fresh-loaded config
+ * @param configPath - Optional config path override (must match server's config)
+ */
+export async function applyConfigChange(
+  ctxHolder: ContextHolder,
+  store: SqliteAdapter,
+  mutate: (config: Config) => Promise<MutationResult> | MutationResult,
+  configPath?: string
+): Promise<ApplyConfigResult> {
+  // Serialize config mutations to prevent lost updates
+  const previousMutex = configMutex;
+  let resolveMutex: () => void = () => {
+    /* no-op until assigned */
+  };
+  configMutex = new Promise((resolve) => {
+    resolveMutex = resolve;
+  });
+
+  try {
+    await previousMutex;
+
+    // 1. Load current config from YAML
+    const loadResult = await loadConfig(configPath);
+    if (!loadResult.ok) {
+      return {
+        ok: false,
+        error: loadResult.error.message,
+        code: 'LOAD_ERROR',
+      };
+    }
+
+    // 2. Apply mutation to freshly-loaded config
+    const mutationResult = await mutate(loadResult.value);
+    if (!mutationResult.ok) {
+      return {
+        ok: false,
+        error: mutationResult.error,
+        code: mutationResult.code, // Pass through the original error code
+      };
+    }
+    const newConfig = mutationResult.config;
+
+    // 3. Save YAML atomically
+    const saveResult = await saveConfig(newConfig, configPath);
+    if (!saveResult.ok) {
+      return {
+        ok: false,
+        error: saveResult.error.message,
+        code: 'SAVE_ERROR',
+      };
+    }
+
+    // 4. Sync DB tables
+    const syncCollResult = await store.syncCollections(newConfig.collections);
+    if (!syncCollResult.ok) {
+      // YAML is saved, but DB sync failed - log warning
+      console.warn(
+        `Config saved but DB sync failed: ${syncCollResult.error.message}`
+      );
+      return {
+        ok: false,
+        error: `DB sync failed: ${syncCollResult.error.message}`,
+        code: 'SYNC_ERROR',
+      };
+    }
+
+    const syncCtxResult = await store.syncContexts(newConfig.contexts ?? []);
+    if (!syncCtxResult.ok) {
+      console.warn(
+        `Config saved but context sync failed: ${syncCtxResult.error.message}`
+      );
+      return {
+        ok: false,
+        error: `Context sync failed: ${syncCtxResult.error.message}`,
+        code: 'SYNC_ERROR',
+      };
+    }
+
+    // 5. Update both in-memory references
+    ctxHolder.config = newConfig;
+    ctxHolder.current = { ...ctxHolder.current, config: newConfig };
+
+    return { ok: true, config: newConfig };
+  } finally {
+    resolveMutex();
+  }
+}

package/src/serve/context.ts

@@ -6,7 +6,9 @@
  */
 
 import type { Config } from '../config/types';
+import type { CreatePortOptions } from '../llm/nodeLlamaCpp/adapter';
 import { LlmAdapter } from '../llm/nodeLlamaCpp/adapter';
+import { resolveDownloadPolicy } from '../llm/policy';
 import { getActivePreset } from '../llm/registry';
 import type {
   DownloadProgress,
@@ -87,8 +89,27 @@ export async function createServerContext(
     const preset = getActivePreset(config);
     const llm = new LlmAdapter(config);
 
+    // Resolve download policy from env (serve has no CLI flags)
+    const policy = resolveDownloadPolicy(process.env, {});
+
+    // Progress callback updates downloadState for WebUI polling
+    const createPortOptions = (type: ModelType): CreatePortOptions => ({
+      policy,
+      onProgress: (progress) => {
+        downloadState.active = true;
+        downloadState.currentType = type;
+        downloadState.progress = progress;
+        if (progress.percent >= 100) {
+          downloadState.completed.push(type);
+        }
+      },
+    });
+
     // Try to create embedding port
-    const embedResult = await llm.createEmbeddingPort(preset.embed);
+    const embedResult = await llm.createEmbeddingPort(
+      preset.embed,
+      createPortOptions('embed')
+    );
     if (embedResult.ok) {
       embedPort = embedResult.value;
       const initResult = await embedPort.init();
@@ -108,18 +129,30 @@ export async function createServerContext(
     }
 
     // Try to create generation port
-    const genResult = await llm.createGenerationPort(preset.gen);
+    const genResult = await llm.createGenerationPort(
+      preset.gen,
+      createPortOptions('gen')
+    );
     if (genResult.ok) {
       genPort = genResult.value;
       console.log('AI answer generation enabled');
     }
 
     // Try to create rerank port
-    const rerankResult = await llm.createRerankPort(preset.rerank);
+    const rerankResult = await llm.createRerankPort(
+      preset.rerank,
+      createPortOptions('rerank')
+    );
     if (rerankResult.ok) {
       rerankPort = rerankResult.value;
       console.log('Reranking enabled');
     }
+
+    // Reset download state after initialization
+    if (downloadState.active) {
+      downloadState.active = false;
+      downloadState.currentType = null;
+    }
   } catch (e) {
     // Log but don't fail - models are optional
     console.log(

package/src/serve/jobs.ts

@@ -0,0 +1,172 @@
+/**
+ * Background job tracker for API write operations.
+ * Simple in-memory tracking with global mutex (one job at a time).
+ *
+ * @module src/serve/jobs
+ */
+
+import type { SyncResult } from '../ingestion';
+
+// Job expiration: 1 hour
+const JOB_EXPIRATION_MS = 60 * 60 * 1000;
+
+export type JobType = 'add' | 'sync' | 'embed';
+
+export interface JobProgress {
+  current: number;
+  total: number;
+  currentFile?: string;
+}
+
+export interface JobStatus {
+  id: string;
+  type: JobType;
+  status: 'running' | 'completed' | 'failed';
+  createdAt: number;
+  progress?: JobProgress;
+  result?: SyncResult;
+  error?: string;
+}
+
+export interface StartJobSuccess {
+  ok: true;
+  jobId: string;
+}
+
+export interface StartJobError {
+  ok: false;
+  error: string;
+  status: 409;
+}
+
+export type StartJobResult = StartJobSuccess | StartJobError;
+
+// Global state - only one job can run at a time
+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.
+ */
+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) {
+      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();
+
+  // Check if a job is already running
+  if (activeJobId) {
+    return {
+      ok: false,
+      error: `Job ${activeJobId} already running`,
+      status: 409,
+    };
+  }
+
+  const jobId = crypto.randomUUID();
+  activeJobId = jobId;
+
+  const jobStatus: JobStatus = {
+    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) => {
+      const job = jobs.get(jobId);
+      if (job) {
+        job.status = 'completed';
+        job.result = result;
+      }
+    })
+    .catch((e) => {
+      const job = jobs.get(jobId);
+      if (job) {
+        job.status = 'failed';
+        job.error = e instanceof Error ? e.message : String(e);
+      }
+    })
+    .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 {
+  cleanupExpiredJobs();
+  return jobs.get(jobId);
+}
+
+/**
+ * Get the currently active job ID, if any.
+ */
+export function getActiveJobId(): string | null {
+  return activeJobId;
+}
+
+/**
+ * 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;
+  }
+}
+
+/**
+ * Get all jobs (for debugging/monitoring).
+ */
+export function getAllJobs(): JobStatus[] {
+  cleanupExpiredJobs();
+  return Array.from(jobs.values());
+}
+
+/**
+ * Clear all jobs (for testing).
+ */
+export function clearAllJobs(): void {
+  jobs.clear();
+  activeJobId = null;
+}