pi-harness-runtime 1.1.410 → 1.1.411

package/packages/skills/src/loader.ts

@@ -23,7 +23,7 @@ import { parseSkillFile, scanSkillDirectory } from "./parser.js";
 // Loaded dynamically so skills work without Qdrant configured.
 // At runtime, packages/ is resolved from the monorepo root or node_modules.
 
-interface QdrantSkillPoint {
+export interface QdrantSkillPoint {
   id: number;
   name: string;
   description: string;
@@ -43,13 +43,62 @@ interface QdrantClientLike {
 
 interface QdrantEmbedderLike {
   createEmbedding(text: string, apiKey?: string): Promise<{ embedding: number[]; tokens: number }>;
+  /** One request for many texts. Absent in an older package build. */
+  createEmbeddingsBatch?: (texts: string[], apiKey?: string) => Promise<{ embeddings: number[][]; tokens: number }>;
 }
 
+/**
+ * A point of the vector index: the vector and the payload of one skill.
+ */
+export interface SkillVectorPoint {
+  id: number;
+  vector: number[];
+  payload: QdrantSkillPoint;
+}
+
+/**
+ * The vector index of a registry.
+ *
+ * The index is an interface so a caller can supply its own implementation
+ * (a test uses a counting double) and so the registry never has to know
+ * whether the index lives in Qdrant.
+ */
+export interface SkillVectorIndexer {
+  /** One vector per text, in the order of the texts. */
+  embed(texts: string[]): Promise<number[][]>;
+  /** Store the points of the given skills. */
+  upsert(points: SkillVectorPoint[]): Promise<void>;
+}
+
+/**
+ * The options of a skill registry.
+ */
+export interface SkillRegistryOptions {
+  /**
+   * The vector index.
+   *
+   * `undefined` (the default) indexes into the configured Qdrant cluster.
+   * `null` disables the vector index entirely. An object is used as the index.
+   */
+  indexer?: SkillVectorIndexer | null;
+  /**
+   * How many skills one indexing request carries. A larger batch costs fewer
+   * requests but holds more of them in memory.
+   */
+  batchSize?: number;
+}
+
+/**
+ * The default number of skills one indexing request carries.
+ */
+const DEFAULT_INDEX_BATCH_SIZE = 32;
+
 /** Resolve the Qdrant skill module path (monorepo sibling or npm package) */
 async function resolveQdrantModules(): Promise<{
   createQdrantClient: (cfg: unknown) => { upsert(c: string, o: unknown): Promise<void>; query(c: string, o: unknown): Promise<unknown>; };
   createCollection: (client: unknown, name: string, dims: number) => Promise<void>;
   createEmbedding: (text: string, apiKey?: string) => Promise<{ embedding: number[]; tokens: number }>;
+  createEmbeddingsBatch?: (texts: string[], apiKey?: string) => Promise<{ embeddings: number[][]; tokens: number }>;
 } | null> {
   // Try the monorepo sibling first (the compiled package, so the module
   // comes from the same build the app ships).
@@ -60,6 +109,7 @@ async function resolveQdrantModules(): Promise<{
         createQdrantClient: unknown;
         createCollection: unknown;
         createEmbedding: unknown;
+        createEmbeddingsBatch?: unknown;
       };
       return mod as Awaited<ReturnType<typeof resolveQdrantModules>>;
     } catch {
@@ -71,11 +121,21 @@ async function resolveQdrantModules(): Promise<{
     // The specifier is a variable on purpose: the package is optional and
     // must not be resolved by the type checker.
     const specifier = "@pi-harness/qdrant-skills";
-    const mod = (await import(/* @vite-ignore */ specifier)) as { createQdrantClient: unknown; createCollection: unknown; createEmbedding: unknown };
+    const mod = (await import(/* @vite-ignore */ specifier)) as {
+      createQdrantClient: unknown;
+      createCollection: unknown;
+      createEmbedding: unknown;
+      createEmbeddingsBatch?: unknown;
+    };
     return {
       createQdrantClient: (cfg: unknown) => (mod.createQdrantClient as Function)(cfg) as { upsert(c: string, o: unknown): Promise<void>; query(c: string, o: unknown): Promise<unknown> },
       createCollection: mod.createCollection as (client: unknown, name: string, dims: number) => Promise<void>,
       createEmbedding: mod.createEmbedding as (text: string, apiKey?: string) => Promise<{ embedding: number[]; tokens: number }>,
+      // Absent in an older package build: the registry falls back to one
+      // request per text, still with a bounded concurrency.
+      createEmbeddingsBatch: typeof mod.createEmbeddingsBatch === "function"
+        ? (mod.createEmbeddingsBatch as (texts: string[], apiKey?: string) => Promise<{ embeddings: number[][]; tokens: number }>)
+        : undefined,
     };
   } catch {
     return null;
@@ -128,6 +188,16 @@ export class SkillRegistry {
   private index: SkillIndex = { entries: [], loadedAt: 0 };
   private loading: Map<string, Promise<Skill>> = new Map();
 
+  // The vector index. `undefined` means "use Qdrant", `null` means "no index".
+  private _indexer: SkillVectorIndexer | null | undefined;
+  private _batchSize: number;
+  // The skills that still have to be indexed, in registration order.
+  private _indexQueue: Array<{ skill: Skill; point: QdrantSkillPoint; hash: number }> = [];
+  private _indexFlushRunning = false;
+  private _indexFlushScheduled = false;
+  // The content hash of the version of a skill that was queued or indexed.
+  private _indexedHashes: Map<string, number> = new Map();
+
   // Qdrant state (lazily initialized on first register if configured)
   private _qdrant: {
     client: QdrantClientLike;
@@ -137,6 +207,12 @@ export class SkillRegistry {
   } | null = null;
   private _qdrantInitPromise: Promise<void> | null = null;
   private _qdrantInitFailed = false;
+  private _qdrantIndexer: SkillVectorIndexer | null = null;
+
+  constructor(options: SkillRegistryOptions = {}) {
+    this._indexer = options.indexer;
+    this._batchSize = options.batchSize ?? DEFAULT_INDEX_BATCH_SIZE;
+  }
 
   /**
    * Check if Qdrant initialization has failed (useful for diagnostics).
@@ -145,6 +221,13 @@ export class SkillRegistry {
     return this._qdrantInitFailed;
   }
 
+  /**
+   * Whether skills are still queued for the vector index.
+   */
+  isIndexing(): boolean {
+    return this._indexFlushRunning || this._indexQueue.length > 0;
+  }
+
   /**
    * Initialize Qdrant client if configured.
    * Uses a shared init promise to prevent race conditions when multiple
@@ -181,7 +264,10 @@ export class SkillRegistry {
       await mods.createCollection(client, config.collection, 1536);
       this._qdrant = {
         client,
-        embedder: { createEmbedding: mods.createEmbedding },
+        embedder: {
+          createEmbedding: mods.createEmbedding,
+          createEmbeddingsBatch: mods.createEmbeddingsBatch,
+        },
         collection: config.collection,
         ready: true,
       };
@@ -191,28 +277,141 @@ export class SkillRegistry {
     }
   }
 
-  /**
-   * Index a single skill into Qdrant (non-blocking).
-   */
-  private async _indexSkillToQdrant(skill: Skill): Promise<void> {
-    if (!this._qdrant?.ready) return;
-
-    const point: QdrantSkillPoint = {
+  /** The point of a skill in the vector index. */
+  private _toQdrantPoint(skill: Skill): QdrantSkillPoint {
+    return {
       id: this._hashId(skill.id),
       name: skill.id,
       description: skill.frontmatter.description,
       body: skill.body.slice(0, 2000),
       text: [skill.id, skill.frontmatter.name, skill.frontmatter.description, skill.body.slice(0, 1500)].join(" "),
     };
+  }
 
-    try {
-      const { embedding } = await this._qdrant.embedder.createEmbedding(point.text);
-      await this._qdrant.client.upsert(this._qdrant.collection, {
-        wait: false,
-        points: [{ id: point.id, vector: embedding, payload: point }],
-      });
-    } catch {
-      // Silently skip — embeddings are optional
+  /**
+   * The indexer of the registry: the injected one, or the Qdrant cluster.
+   */
+  private _getIndexer(): SkillVectorIndexer | null {
+    if (this._indexer !== undefined) return this._indexer;
+    if (!this._qdrantIndexer) {
+      this._qdrantIndexer = this._createQdrantIndexer();
+    }
+    return this._qdrantIndexer;
+  }
+
+  /**
+   * The Qdrant cluster as an indexer.
+   *
+   * The batch call of the embeddings endpoint carries many texts in one
+   * request. One request per skill exhausted the sockets of the process when
+   * a registry held hundreds of skills, and every other request of the
+   * program then starved.
+   */
+  private _createQdrantIndexer(): SkillVectorIndexer | null {
+    const qdrant = this._qdrant;
+    if (!qdrant?.ready) return null;
+
+    return {
+      embed: async (texts: string[]): Promise<number[][]> => {
+        if (texts.length === 0) return [];
+        const batch = qdrant.embedder.createEmbeddingsBatch;
+        if (batch) {
+          const result = await batch(texts);
+          return result.embeddings;
+        }
+        // An older build without the batch call: one request per text, but
+        // the caller keeps the concurrency bounded all the same.
+        const embeddings: number[][] = [];
+        for (const text of texts) {
+          const { embedding } = await qdrant.embedder.createEmbedding(text);
+          embeddings.push(embedding);
+        }
+        return embeddings;
+      },
+      upsert: async (points: SkillVectorPoint[]): Promise<void> => {
+        await qdrant.client.upsert(qdrant.collection, { wait: false, points });
+      },
+    };
+  }
+
+  /**
+   * Queue a skill for the vector index.
+   *
+   * A skill whose text did not change is not queued again: the registry is
+   * filled on every scan, and re-embedding the same skill would pay for the
+   * same vector over and over.
+   */
+  private _scheduleIndex(skill: Skill): void {
+    const point = this._toQdrantPoint(skill);
+    const hash = this._hashId(point.text);
+    if (this._indexedHashes.get(skill.id) === hash) return;
+
+    this._indexedHashes.set(skill.id, hash);
+    this._indexQueue.push({ skill, point, hash });
+    this._scheduleIndexFlush();
+  }
+
+  /**
+   * Start the index flush, a microtask from now.
+   *
+   * A scan registers every skill in one go. Waiting for the microtask lets
+   * that burst share one request instead of starting one request per skill.
+   */
+  private _scheduleIndexFlush(): void {
+    if (this._indexFlushScheduled) return;
+    this._indexFlushScheduled = true;
+    queueMicrotask(() => {
+      this._indexFlushScheduled = false;
+      this._runIndexFlush();
+    });
+  }
+
+  /**
+   * Index the queued skills, one batch at a time.
+   *
+   * Only one batch is in flight, so the number of open connections stays
+   * bound no matter how many skills the registry holds.
+   */
+  private _runIndexFlush(): void {
+    if (this._indexFlushRunning) return;
+    this._indexFlushRunning = true;
+
+    void this._flushIndexQueue().finally(() => {
+      this._indexFlushRunning = false;
+      // Skills may have arrived while the flush was running.
+      if (this._indexQueue.length > 0) this._scheduleIndexFlush();
+    });
+  }
+
+  private async _flushIndexQueue(): Promise<void> {
+    if (this._indexer === undefined) await this._ensureQdrant();
+    const indexer = this._getIndexer();
+    if (!indexer) {
+      // No vector index: the skills stay usable without vectors.
+      this._indexQueue = [];
+      return;
+    }
+
+    while (this._indexQueue.length > 0) {
+      const batch = this._indexQueue.splice(0, this._batchSize);
+      try {
+        const vectors = await indexer.embed(batch.map((item) => item.point.text));
+        const points: SkillVectorPoint[] = [];
+        batch.forEach((item, position) => {
+          const vector = vectors[position];
+          if (!vector || vector.length === 0) return;
+          points.push({ id: item.point.id, vector, payload: item.point });
+        });
+        if (points.length > 0) await indexer.upsert(points);
+      } catch {
+        // The vector index is optional. A failed batch may be retried by a
+        // later registration of the same skills.
+        for (const item of batch) {
+          if (this._indexedHashes.get(item.skill.id) === item.hash) {
+            this._indexedHashes.delete(item.skill.id);
+          }
+        }
+      }
     }
   }
 
@@ -231,8 +430,8 @@ export class SkillRegistry {
   register(skill: Skill): void {
     this.skills.set(skill.id, skill);
     this.updateIndex(skill);
-    // Trigger async Qdrant indexing without blocking registration
-    this._ensureQdrant().then(() => this._indexSkillToQdrant(skill)).catch(() => {});
+    // Queue the skill for the vector index without blocking registration.
+    this._scheduleIndex(skill);
   }
 
   /**
@@ -413,13 +612,30 @@ export class SkillRegistry {
    * Useful after Qdrant becomes available or collection is rebuilt.
    */
   async syncAllToQdrant(onProgress?: (index: number, total: number) => void): Promise<void> {
-    await this._ensureQdrant();
-    if (!this._qdrant?.ready) return;
+    if (this._indexer === undefined) await this._ensureQdrant();
+    const indexer = this._getIndexer();
+    if (!indexer) return;
 
     const skills = this.list();
-    for (let i = 0; i < skills.length; i++) {
-      await this._indexSkillToQdrant(skills[i]);
-      onProgress?.(i + 1, skills.length);
+    const total = skills.length;
+    let done = 0;
+    for (let i = 0; i < total; i += this._batchSize) {
+      const batch = skills.slice(i, i + this._batchSize);
+      const points = batch.map((skill) => this._toQdrantPoint(skill));
+      try {
+        const vectors = await indexer.embed(points.map((point) => point.text));
+        const payload: SkillVectorPoint[] = [];
+        points.forEach((point, position) => {
+          const vector = vectors[position];
+          if (!vector || vector.length === 0) return;
+          payload.push({ id: point.id, vector, payload: point });
+        });
+        if (payload.length > 0) await indexer.upsert(payload);
+      } catch {
+        // The vector index is optional — a failed batch does not stop the sync.
+      }
+      done += batch.length;
+      onProgress?.(done, total);
     }
   }
 
@@ -576,8 +792,8 @@ export class SkillRegistry {
 /**
  * Create a new skill registry
  */
-export function createSkillRegistry(): SkillRegistry {
-  return new SkillRegistry();
+export function createSkillRegistry(options: SkillRegistryOptions = {}): SkillRegistry {
+  return new SkillRegistry(options);
 }
 
 /**

package/packages/skills/test/init-skills.test.ts

@@ -1,118 +1,114 @@
 /**
- * Skills Initialization E2E Test
- * 
- * Tests the initSkills function to ensure:
- * 1. initSkills() with no args uses default directories
- * 2. initSkills({ locations }) with explicit locations works
- * 3. initSkills({ locations: undefined }) falls back to defaults (the bug case)
- * 
- * Bug: Previously, passing undefined for locations would override defaults
- * with undefined, causing "directories is not iterable" error.
- * 
- * Usage:
- *   bun packages/skills/test/init-skills.test.ts
+ * The initialization of the skills system.
+ *
+ * The test used to be a script that ran `initSkills()` while the module was
+ * imported. That scanned the real skill directories of the machine and
+ * started the vector indexing of every skill it found, which opened a
+ * connection per skill and starved every other test of the process.
+ *
+ * The test now uses a temporary directory and a registry without a vector
+ * index, so it neither reads the machine nor reaches the network.
  */
 
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
 import { initSkills } from "../src/index.js";
+import { createSkillRegistry } from "../src/loader.js";
+
+let tempDir: string;
 
-async function runTests() {
-  console.log("=== initSkills E2E Test ===\n");
-  
-  let passed = 0;
-  let failed = 0;
-
-  // Test 1: no args
-  console.log("[Test 1] initSkills() with no arguments...");
-  try {
-    const result = initSkills();
-    if (!result || !Array.isArray(result.skills) || !Array.isArray(result.errors)) {
-      throw new Error("Invalid result structure");
-    }
-    console.log(`  PASS: Returned ${result.skills.length} skills, ${result.errors.length} errors\n`);
-    passed++;
-  } catch (error) {
-    console.error(`  FAIL: ${error}\n`);
-    failed++;
-  }
-
-  // Test 2: explicit locations
-  console.log("[Test 2] initSkills({ locations: [...] })...");
-  try {
-    const result = initSkills({ locations: ["/tmp/test"] });
-    if (!result) {
-      throw new Error("No result returned");
-    }
-    console.log(`  PASS: Returned ${result.skills.length} skills\n`);
-    passed++;
-  } catch (error) {
-    console.error(`  FAIL: ${error}\n`);
-    failed++;
-  }
-
-  // Test 3: undefined locations (the bug case)
-  console.log("[Test 3] initSkills({ locations: undefined }) - THE BUG CASE...");
-  try {
-    const result = initSkills({ locations: undefined });
-    if (!result || !Array.isArray(result.skills)) {
-      throw new Error("Invalid result structure");
-    }
-    console.log(`  PASS: Returned ${result.skills.length} skills\n`);
-    passed++;
-  } catch (error) {
-    console.error(`  FAIL: ${error}\n`);
-    failed++;
-  }
-
-  // Test 4: partial config with only maxDepth
-  console.log("[Test 4] initSkills({ maxDepth: 5 })...");
-  try {
-    const result = initSkills({ maxDepth: 5 });
-    if (!result || !Array.isArray(result.skills)) {
-      throw new Error("Invalid result structure");
-    }
-    console.log(`  PASS: Returned ${result.skills.length} skills\n`);
-    passed++;
-  } catch (error) {
-    console.error(`  FAIL: ${error}\n`);
-    failed++;
-  }
-
-  // Test 5: partial config with only includeHidden
-  console.log("[Test 5] initSkills({ includeHidden: true })...");
-  try {
-    const result = initSkills({ includeHidden: true });
-    if (!result || !Array.isArray(result.skills)) {
-      throw new Error("Invalid result structure");
-    }
-    console.log(`  PASS: Returned ${result.skills.length} skills\n`);
-    passed++;
-  } catch (error) {
-    console.error(`  FAIL: ${error}\n`);
-    failed++;
-  }
-
-  // Test 6: empty locations array
-  console.log("[Test 6] initSkills({ locations: [] })...");
-  try {
-    const result = initSkills({ locations: [] });
-    if (!result) {
-      throw new Error("No result returned");
-    }
-    console.log(`  PASS: Returned ${result.skills.length} skills\n`);
-    passed++;
-  } catch (error) {
-    console.error(`  FAIL: ${error}\n`);
-    failed++;
-  }
-
-  // Summary
-  console.log("=== Summary ===");
-  console.log(`Passed: ${passed}`);
-  console.log(`Failed: ${failed}`);
-  
-  if (failed > 0) {
-    process.exit(1);
-  }
+/** Write a skill into a directory of the temporary home. */
+function writeSkill(directory: string, name: string): void {
+	const skillDir = join(tempDir, directory, name);
+	mkdirSync(skillDir, { recursive: true });
+	writeFileSync(
+		join(skillDir, "SKILL.md"),
+		[
+			"---",
+			`name: ${name}`,
+			`description: The ${name} skill.`,
+			"version: 1.0.0",
+			"---",
+			"",
+			`The body of the ${name} skill.`,
+			"",
+		].join("\n"),
+		"utf8",
+	);
 }
 
-runTests();
+beforeEach(() => {
+	tempDir = mkdtempSync(join(tmpdir(), "test-init-skills-"));
+	mkdirSync(join(tempDir, "skills"), { recursive: true });
+	writeSkill("skills", "alpha");
+	writeSkill("skills", "beta");
+});
+
+afterEach(() => {
+	rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe("the initialization of the skills system", () => {
+	it("scans the given locations", () => {
+		const result = initSkills({
+			locations: [join(tempDir, "skills")],
+			registry: createSkillRegistry({ indexer: null }),
+		});
+
+		expect(result.skills.length).toBe(2);
+		expect(result.skills.map((skill) => skill.id).sort()).toEqual(["alpha", "beta"]);
+		expect(result.errors).toEqual([]);
+	});
+
+	it("falls back to the default locations when none are given", () => {
+		// The default locations point at the machine of the test, so the
+		// result is only checked for its shape.
+		const result = initSkills({
+			registry: createSkillRegistry({ indexer: null }),
+		});
+
+		expect(Array.isArray(result.skills)).toBe(true);
+		expect(Array.isArray(result.errors)).toBe(true);
+	});
+
+	it("falls back to the default locations when they are undefined", () => {
+		// The bug case: an undefined value must not override the defaults.
+		const result = initSkills({
+			locations: undefined,
+			registry: createSkillRegistry({ indexer: null }),
+		});
+
+		expect(Array.isArray(result.skills)).toBe(true);
+		expect(Array.isArray(result.errors)).toBe(true);
+	});
+
+	it("accepts a partial configuration", () => {
+		const result = initSkills({
+			maxDepth: 5,
+			includeHidden: true,
+			registry: createSkillRegistry({ indexer: null }),
+		});
+
+		expect(Array.isArray(result.skills)).toBe(true);
+	});
+
+	it("accepts an empty list of locations", () => {
+		const result = initSkills({
+			locations: [],
+			registry: createSkillRegistry({ indexer: null }),
+		});
+
+		expect(result.skills).toEqual([]);
+	});
+
+	it("registers the scanned skills in the registry", () => {
+		const registry = createSkillRegistry({ indexer: null });
+
+		initSkills({ locations: [join(tempDir, "skills")], registry });
+
+		expect(registry.list().length).toBe(2);
+	});
+});