@gmickel/gno 2.12.1 → 2.13.0

package/src/core/job-manager.ts

@@ -1,10 +1,13 @@
-import type { SyncResult } from "../ingestion";
+// node:async_hooks: Bun has no separate async-context snapshot API.
+import { AsyncLocalStorage } from "node:async_hooks";
 /**
  * Background job manager for MCP write operations.
  *
  * @module src/core/job-manager
  */
 
+import type { SyncResult } from "../ingestion";
+
 import {
   assertInferenceActive,
   withOwnedInferenceScope,
@@ -12,14 +15,17 @@ import {
 } from "../llm/inference-scope";
 import { MCP_ERRORS } from "./errors";
 import { acquireWriteLock, type WriteLockHandle } from "./file-lock";
+import { MAX_REINDEX_PATHS } from "./reindex-paths";
 
 const JOB_EXPIRATION_MS = 60 * 60 * 1000;
 const JOB_MAX_RECENT = 100;
 const DEFAULT_LOCK_TIMEOUT_MS = 5000;
+/** Distinct reindex requests that may wait behind the running job. */
+export const MAX_PENDING_REINDEX_JOBS = 64;
 
 export type JobType = "add" | "sync" | "embed" | "index";
 
-export type JobStatus = "running" | "completed" | "failed";
+export type JobStatus = "queued" | "running" | "completed" | "failed";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Discriminated union for job results
@@ -51,9 +57,55 @@ export interface JobRecord {
   typedResult?: JobResult;
   error?: string;
   progress?: { current: number; total: number; currentFile?: string };
+  /** Reindex jobs: the collection (null = all) and merged paths (null = whole). */
+  scope?: { collection: string | null; paths: string[] | null };
   serverInstanceId: string;
 }
 
+export interface ReindexOptions {
+  gitPull: boolean;
+  runUpdateCmd: boolean;
+}
+
+/** What one reindex pass covers; `paths` null means the whole collection. */
+export interface ReindexScope {
+  collection: string | null;
+  paths: string[] | null;
+  options: ReindexOptions;
+}
+
+/**
+ * A reindex request. `run` must honour the scope it is given: when requests
+ * merge, the pass runs the latest request's `run` over the merged scope.
+ */
+export interface ReindexRequest {
+  type: "sync" | "index";
+  collection: string | null;
+  paths: string[] | null;
+  options: ReindexOptions;
+  run: (scope: ReindexScope, signal: AbortSignal) => Promise<JobResult>;
+}
+
+export interface ReindexAccepted {
+  jobId: string;
+  status: "running" | "queued";
+}
+
+interface PendingReindex {
+  job: JobRecord;
+  type: ReindexRequest["type"];
+  collection: string | null;
+  paths: Set<string> | null;
+  /** null while only path requests joined: options come from a whole request. */
+  options: ReindexOptions | null;
+  run: ReindexRequest["run"];
+}
+
+const NO_REINDEX_OPTIONS: ReindexOptions = {
+  gitPull: false,
+  runUpdateCmd: false,
+};
+
 export interface JobManagerOptions {
   lockPath: string;
   serverInstanceId: string;
@@ -63,10 +115,12 @@ export interface JobManagerOptions {
   lockTimeoutMs?: number;
 }
 
+export type JobErrorCode = "LOCKED" | "JOB_CONFLICT" | "QUEUE_FULL";
+
 export class JobError extends Error {
-  code: "LOCKED" | "JOB_CONFLICT";
+  code: JobErrorCode;
 
-  constructor(code: "LOCKED" | "JOB_CONFLICT", message: string) {
+  constructor(code: JobErrorCode, message: string) {
     super(message);
     this.code = code;
     this.name = "JobError";
@@ -86,6 +140,10 @@ export class JobManager {
   #authorizationEpoch = "egress-epoch-uninitialized";
   #accepting = true;
   #releaseJobLocks = new Map<string, () => Promise<void>>();
+  /** Pending reindex jobs in arrival order. */
+  #pending: PendingReindex[] = [];
+  /** Context captured at construction; queued jobs start here, not in the previous job's. */
+  #rootContext = AsyncLocalStorage.snapshot();
 
   constructor(options: JobManagerOptions) {
     this.#lockPath = options.lockPath;
@@ -164,6 +222,89 @@ export class JobManager {
     return this.#startTypedJobWithLock(type, fn, lock);
   }
 
+  /**
+   * Start a reindex now when nothing else is running or waiting; otherwise
+   * queue it. A request joins a waiting job for the same type and collection
+   * when that cannot change what the job is allowed to do: a path request
+   * joins any of them, and a whole-collection request joins a path-only job
+   * (setting its options) or a whole job with the same options. Joined
+   * requests share one job id, so any number of them cause at most one more
+   * pass. Throws `LOCKED` when another process holds the write lease at an
+   * immediate start, and `QUEUE_FULL` at the pending bound.
+   */
+  async submitReindex(request: ReindexRequest): Promise<ReindexAccepted> {
+    assertInferenceActive();
+    this.#assertAccepting();
+    this.#cleanupExpiredJobs();
+
+    // Only join work accepted under the current egress policy: a stale entry
+    // fails at admission and must not swallow a freshly authorized request.
+    const pending = this.#pending.find(
+      (entry) =>
+        joins(entry, request) &&
+        this.#jobAuthorizationEpochs.get(entry.job.id) ===
+          this.#authorizationEpoch
+    );
+    if (pending) {
+      if (request.paths === null) {
+        pending.paths = null;
+        pending.options = request.options;
+      } else if (pending.paths) {
+        for (const path of request.paths) pending.paths.add(path);
+        // Too many files for one path pass: rescan the collection instead,
+        // with no git pull or update command, which no path request asked for.
+        if (pending.paths.size > MAX_REINDEX_PATHS) {
+          pending.paths = null;
+          pending.options = { gitPull: false, runUpdateCmd: false };
+        }
+      }
+      pending.run = request.run;
+      pending.job.scope = scopeRecord(pending.collection, pending.paths);
+      return { jobId: pending.job.id, status: "queued" };
+    }
+
+    if (!this.#activeJobId && this.#pending.length === 0) {
+      const job = this.#newJob(request.type, "running");
+      job.scope = scopeRecord(request.collection, request.paths);
+      this.#activeJobId = job.id;
+      const lock = await acquireWriteLock(this.#lockPath, this.#lockTimeoutMs);
+      if (!lock || !this.#accepting) {
+        await lock?.release();
+        this.#jobs.delete(job.id);
+        this.#jobAuthorizationEpochs.delete(job.id);
+        this.#activeJobId = null;
+        this.#track(this.#drainPending());
+        this.#assertAccepting();
+        throw new JobError("LOCKED", MCP_ERRORS.LOCKED.message);
+      }
+      const scope: ReindexScope = {
+        collection: request.collection,
+        paths: request.paths,
+        options: request.options,
+      };
+      this.#launchTyped(job, (signal) => request.run(scope, signal), lock);
+      return { jobId: job.id, status: "running" };
+    }
+
+    if (this.#pending.length >= MAX_PENDING_REINDEX_JOBS) {
+      throw new JobError(
+        "QUEUE_FULL",
+        `${MCP_ERRORS.QUEUE_FULL.message} (${MAX_PENDING_REINDEX_JOBS} waiting)`
+      );
+    }
+    const job = this.#newJob(request.type, "queued");
+    job.scope = scopeRecord(request.collection, request.paths);
+    this.#pending.push({
+      job,
+      type: request.type,
+      collection: request.collection,
+      paths: request.paths ? new Set(request.paths) : null,
+      options: request.paths ? null : request.options,
+      run: request.run,
+    });
+    return { jobId: job.id, status: "queued" };
+  }
+
   getJob(jobId: string): JobRecord | undefined {
     this.#cleanupExpiredJobs();
     return this.#jobs.get(jobId);
@@ -184,7 +325,7 @@ export class JobManager {
     let invalidated = 0;
     for (const job of this.#jobs.values()) {
       if (
-        job.status === "running" &&
+        (job.status === "running" || job.status === "queued") &&
         this.#jobAuthorizationEpochs.get(job.id) !== epoch
       ) {
         invalidated += 1;
@@ -202,6 +343,7 @@ export class JobManager {
   }
 
   clear(): void {
+    this.#pending = [];
     this.#jobs.clear();
     this.#jobAuthorizationEpochs.clear();
     this.#activeJobId = null;
@@ -212,11 +354,11 @@ export class JobManager {
 
     const jobs = Array.from(this.#jobs.values());
     const active = jobs
-      .filter((job) => job.status === "running")
+      .filter((job) => isUnfinished(job))
       .sort((a, b) => a.startedAt - b.startedAt);
 
     const recent = jobs
-      .filter((job) => job.status !== "running")
+      .filter((job) => !isUnfinished(job))
       .sort((a, b) => (b.completedAt ?? 0) - (a.completedAt ?? 0))
       .slice(0, limit);
 
@@ -238,6 +380,9 @@ export class JobManager {
 
   stop(): void {
     this.#accepting = false;
+    for (const { job } of this.#pending)
+      failJob(job, "Resident runtime is shutting down");
+    this.#pending = [];
   }
 
   cancel(): void {
@@ -287,20 +432,12 @@ export class JobManager {
     lock: { release: () => Promise<void> }
   ): Promise<void> {
     try {
-      const release = await this.#toolMutex.acquire();
-      try {
-        this.#assertAuthorizationEpoch(job);
-        assertInferenceActive();
-        const result = await fn(this.#jobControllers.get(job.id)!.signal);
-        assertInferenceActive();
-        job.status = "completed";
-        job.result = result;
-      } catch (e) {
-        job.status = "failed";
-        job.error = e instanceof Error ? e.message : String(e);
-      } finally {
-        release();
-      }
+      await this.#admit(job);
+      assertInferenceActive();
+      const result = await fn(this.#jobControllers.get(job.id)!.signal);
+      assertInferenceActive();
+      job.status = "completed";
+      job.result = result;
     } catch (e) {
       job.status = "failed";
       job.error = e instanceof Error ? e.message : String(e);
@@ -311,6 +448,7 @@ export class JobManager {
       this.#activeJobId = null;
       await lock.release().catch(() => undefined);
       this.#cleanupExpiredJobs();
+      await this.#drainPending();
     }
   }
 
@@ -348,28 +486,71 @@ export class JobManager {
     fn: (signal: AbortSignal) => Promise<JobResult>,
     lock: WriteLockHandle
   ): string {
-    const jobId = crypto.randomUUID();
-    const ownedLock = this.#ownLock(jobId, lock);
+    const job = this.#newJob(type, "running");
+    this.#launchTyped(job, fn, lock);
+    return job.id;
+  }
+
+  /** Record a job and the authorization epoch it was accepted under. */
+  #newJob(type: JobType, status: "queued" | "running"): JobRecord {
     const job: JobRecord = {
-      id: jobId,
+      id: crypto.randomUUID(),
       type,
-      status: "running",
+      status,
       startedAt: Date.now(),
       serverInstanceId: this.#serverInstanceId,
     };
+    this.#jobs.set(job.id, job);
+    this.#jobAuthorizationEpochs.set(job.id, this.#authorizationEpoch);
+    return job;
+  }
 
-    this.#jobControllers.set(jobId, new AbortController());
-    this.#jobs.set(jobId, job);
-    this.#jobAuthorizationEpochs.set(jobId, this.#authorizationEpoch);
-    this.#activeJobId = jobId;
+  #launchTyped(
+    job: JobRecord,
+    fn: (signal: AbortSignal) => Promise<JobResult>,
+    lock: WriteLockHandle
+  ): void {
+    const ownedLock = this.#ownLock(job.id, lock);
+    const controller = new AbortController();
+    job.status = "running";
+    job.startedAt = Date.now();
+    this.#jobControllers.set(job.id, controller);
+    this.#activeJobId = job.id;
 
     const jobPromise = withOwnedInferenceScope(
-      { signal: this.#jobControllers.get(jobId)!.signal },
+      { signal: controller.signal },
       () => withBackgroundInference(() => this.#runTypedJob(job, fn, ownedLock))
     );
     this.#track(jobPromise);
+  }
 
-    return jobId;
+  /** Start waiting reindex jobs, in arrival order, while nothing is running. */
+  async #drainPending(): Promise<void> {
+    while (!this.#activeJobId) {
+      const entry = this.#pending.shift();
+      if (!entry) return;
+      this.#activeJobId = entry.job.id;
+      const lock = await acquireWriteLock(this.#lockPath, this.#lockTimeoutMs);
+      if (!lock || !this.#accepting) {
+        await lock?.release();
+        this.#activeJobId = null;
+        failJob(
+          entry.job,
+          this.#accepting
+            ? `${MCP_ERRORS.LOCKED.code}: ${MCP_ERRORS.LOCKED.message}`
+            : "Resident runtime is shutting down"
+        );
+        continue;
+      }
+      const scope: ReindexScope = {
+        collection: entry.collection,
+        paths: entry.paths ? [...entry.paths].sort() : null,
+        options: entry.options ?? NO_REINDEX_OPTIONS,
+      };
+      this.#rootContext(() =>
+        this.#launchTyped(entry.job, (signal) => entry.run(scope, signal), lock)
+      );
+    }
   }
 
   async #runTypedJob(
@@ -378,20 +559,13 @@ export class JobManager {
     lock: { release: () => Promise<void> }
   ): Promise<void> {
     try {
-      const release = await this.#toolMutex.acquire();
-      try {
-        this.#assertAuthorizationEpoch(job);
-        assertInferenceActive();
-        const result = await fn(this.#jobControllers.get(job.id)!.signal);
-        assertInferenceActive();
-        job.status = "completed";
-        job.typedResult = result;
-      } catch (e) {
-        job.status = "failed";
-        job.error = e instanceof Error ? e.message : String(e);
-      } finally {
-        release();
-      }
+      await this.#admit(job);
+      assertInferenceActive();
+      const result = await fn(this.#jobControllers.get(job.id)!.signal);
+      assertInferenceActive();
+      job.status = "completed";
+      job.typedResult = result;
+      if (result.kind === "sync") job.result = result.value;
     } catch (e) {
       job.status = "failed";
       job.error = e instanceof Error ? e.message : String(e);
@@ -402,12 +576,13 @@ export class JobManager {
       this.#activeJobId = null;
       await lock.release().catch(() => undefined);
       this.#cleanupExpiredJobs();
+      await this.#drainPending();
     }
   }
 
   #cleanupExpiredJobs(now: number = Date.now()): void {
     for (const [id, job] of this.#jobs) {
-      if (job.status === "running") {
+      if (isUnfinished(job)) {
         continue;
       }
       const completedAt = job.completedAt ?? job.startedAt;
@@ -418,7 +593,7 @@ export class JobManager {
     }
 
     const completed = Array.from(this.#jobs.values())
-      .filter((job) => job.status !== "running")
+      .filter((job) => !isUnfinished(job))
       .sort((a, b) => (a.completedAt ?? 0) - (b.completedAt ?? 0));
 
     if (completed.length <= JOB_MAX_RECENT) {
@@ -435,6 +610,20 @@ export class JobManager {
     }
   }
 
+  /**
+   * Wait for the tool call in progress, then re-check authorization. The
+   * mutex is released before the job's work runs, so reads are not held
+   * behind a long sync or embed; writers stay serialized by the write lease.
+   */
+  async #admit(job: JobRecord): Promise<void> {
+    const release = await this.#toolMutex.acquire();
+    try {
+      this.#assertAuthorizationEpoch(job);
+    } finally {
+      release();
+    }
+  }
+
   #assertAuthorizationEpoch(job: JobRecord): void {
     if (this.#jobAuthorizationEpochs.get(job.id) === this.#authorizationEpoch) {
       return;
@@ -444,3 +633,31 @@ export class JobManager {
     );
   }
 }
+
+function joins(entry: PendingReindex, request: ReindexRequest): boolean {
+  if (entry.type !== request.type || entry.collection !== request.collection)
+    return false;
+  if (request.paths !== null) return true;
+  if (entry.options === null) return true;
+  return (
+    entry.paths === null &&
+    entry.options.gitPull === request.options.gitPull &&
+    entry.options.runUpdateCmd === request.options.runUpdateCmd
+  );
+}
+
+function scopeRecord(
+  collection: string | null,
+  paths: Iterable<string> | null
+): NonNullable<JobRecord["scope"]> {
+  return { collection, paths: paths ? [...paths].sort() : null };
+}
+
+const isUnfinished = (job: JobRecord): boolean =>
+  job.status === "running" || job.status === "queued";
+
+function failJob(job: JobRecord, error: string): void {
+  job.status = "failed";
+  job.error = error;
+  job.completedAt = Date.now();
+}

package/src/core/reindex-paths.ts

@@ -0,0 +1,167 @@
+/**
+ * Validate caller-supplied paths for a path-level reindex.
+ *
+ * @module src/core/reindex-paths
+ */
+
+// node:fs/promises realpath, lstat/stat (symlinks, directories) and node:path
+// have no Bun equivalent.
+import { lstat, readlink, realpath, stat } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+
+import type { Collection } from "../config/types";
+
+import { collectionToWalkConfig } from "../ingestion/types";
+import { matchesWalkPath } from "../ingestion/walker";
+import { MCP_ERRORS } from "./errors";
+
+const escapes = (rel: string): boolean =>
+  rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel);
+
+const toPosix = (rel: string): string => rel.split(sep).join("/");
+
+const missing = (error: unknown): boolean =>
+  error !== null &&
+  typeof error === "object" &&
+  "code" in error &&
+  (error.code === "ENOENT" || error.code === "ENOTDIR");
+
+const MAX_SYMLINK_HOPS = 32;
+
+/**
+ * Most paths one request may list, and most a queued job keeps after merging.
+ * Past it, reindexing the whole collection is the better call.
+ */
+export const MAX_REINDEX_PATHS = 256;
+
+/**
+ * Realpath of `path`, or of its nearest existing ancestor below `root`. A
+ * dangling symlink on the way resolves to where it points, so a missing file
+ * cannot leave the root through a link whose target does not exist.
+ */
+async function nearestRealpath(
+  path: string,
+  root: string,
+  hops = 0
+): Promise<string | null> {
+  let current = path;
+  for (;;) {
+    try {
+      return await realpath(current);
+    } catch (error) {
+      if (!missing(error)) throw error;
+    }
+    const isLink = await lstat(current).then(
+      (stats) => stats.isSymbolicLink(),
+      () => false
+    );
+    if (isLink) {
+      const target = resolve(dirname(current), await readlink(current));
+      if (hops >= MAX_SYMLINK_HOPS) return target;
+      return (await nearestRealpath(target, root, hops + 1)) ?? target;
+    }
+    const parent = dirname(current);
+    if (parent === current || relative(root, parent) === "") return null;
+    current = parent;
+  }
+}
+
+/**
+ * Resolve paths (relative to the collection root, or absolute inside it) to
+ * deduplicated collection-relative POSIX paths. A path that no longer exists
+ * is kept so the sync can mark it inactive. Throws `INVALID_INPUT: ...` for an
+ * empty list or more than `MAX_REINDEX_PATHS` paths, and `INVALID_PATH: ...`
+ * for a directory or a path outside the root, including one that leaves it
+ * through a symlink.
+ */
+export async function resolveReindexPaths(
+  collection: Collection,
+  paths: readonly unknown[]
+): Promise<string[]> {
+  if (paths.length === 0) {
+    throw new Error(
+      `${MCP_ERRORS.INVALID_INPUT.code}: paths must list at least one path`
+    );
+  }
+  if (paths.length > MAX_REINDEX_PATHS) {
+    throw new Error(
+      `${MCP_ERRORS.INVALID_INPUT.code}: paths lists ${paths.length} paths (at most ${MAX_REINDEX_PATHS}); reindex the whole collection instead`
+    );
+  }
+  const root = resolve(collection.path);
+  let realRoot: string;
+  try {
+    realRoot = await realpath(root);
+  } catch {
+    realRoot = root;
+  }
+  const resolved = new Set<string>();
+  for (const path of paths) {
+    if (typeof path !== "string" || path.trim() === "") {
+      throw new Error(
+        `${MCP_ERRORS.INVALID_INPUT.code}: paths must be non-empty strings`
+      );
+    }
+    const absolute = resolve(root, path);
+    const rel = relative(root, absolute);
+    if (escapes(rel)) {
+      throw new Error(
+        `${MCP_ERRORS.INVALID_PATH.code}: ${path} is outside collection ${collection.name}`
+      );
+    }
+    // A missing file is checked through its nearest existing folder, so a
+    // deletion path cannot leave the root through a symlinked parent.
+    const real = await nearestRealpath(absolute, root);
+    if (
+      real !== null &&
+      escapes(relative(realRoot, real)) &&
+      real !== realRoot
+    ) {
+      throw new Error(
+        `${MCP_ERRORS.INVALID_PATH.code}: ${path} resolves outside collection ${collection.name}`
+      );
+    }
+    const isDirectory = await stat(absolute).then(
+      (stats) => stats.isDirectory(),
+      () => false
+    );
+    if (isDirectory) {
+      throw new Error(
+        `${MCP_ERRORS.INVALID_PATH.code}: ${path} is a directory; list the files in it, or reindex the whole collection`
+      );
+    }
+    // A listed path obeys the collection's own pattern, include and exclude
+    // rules: an excluded file must not become searchable by naming it.
+    if (!matchesWalkPath(toPosix(rel), collectionToWalkConfig(collection, 0))) {
+      throw new Error(
+        `${MCP_ERRORS.INVALID_PATH.code}: ${path} is not part of collection ${collection.name} (its pattern, include or exclude rules leave it out)`
+      );
+    }
+    resolved.add(toPosix(rel));
+  }
+  return [...resolved];
+}
+
+/**
+ * Resolve an optional path list for a reindex request. Paths need a single
+ * collection and apply to a plain sync: git pull and update commands act on
+ * the whole collection, so they cannot be combined with paths.
+ */
+export async function resolveReindexScope(
+  collection: Collection | null,
+  paths: readonly unknown[] | undefined,
+  options: { gitPull?: boolean; runUpdateCmd?: boolean } = {}
+): Promise<string[] | null> {
+  if (paths === undefined) return null;
+  if (!collection) {
+    throw new Error(
+      `${MCP_ERRORS.INVALID_INPUT.code}: paths require a collection`
+    );
+  }
+  if (options.gitPull || options.runUpdateCmd) {
+    throw new Error(
+      `${MCP_ERRORS.INVALID_INPUT.code}: paths cannot be combined with gitPull or an update command`
+    );
+  }
+  return resolveReindexPaths(collection, paths);
+}

package/src/core/retrieval-trace-request.ts

@@ -117,6 +117,7 @@ export const retrievalTraceFilters = (
       limit: options.limit,
       minScore: options.minScore,
       collection: options.collection,
+      collections: options.collections,
       lang: options.lang,
       full: options.full,
       lineNumbers: options.lineNumbers,