pi-harness-runtime 1.1.410 → 1.1.412

package/packages/qdrant-skills/src/client.ts

@@ -86,19 +86,30 @@ export async function getCollectionInfo(
 } | null> {
   try {
     const info = await client.getCollection(name) as Record<string, unknown>;
-    // Vectors config can be a named config or default { size, distance }
-    const vectorsConfig = info.vectors as Record<string, unknown> | undefined;
+    // Qdrant reports the vector configuration under
+    // `config.params.vectors` - NOT at the top level. Reading `info.vectors`
+    // always yields undefined, which turns every schema check into a
+    // "dimension mismatch: got undefined" that names no real cause.
+    const config = info.config as Record<string, unknown> | undefined;
+    const params = config?.params as Record<string, unknown> | undefined;
+    const vectors = (params?.vectors ?? info.vectors) as Record<string, unknown> | undefined;
     let vectorsSize: number | undefined;
     let vectorsDistance: string | undefined;
 
-    if (vectorsConfig) {
-      // Handle both { size: number, distance: string } and named config { config: { size, distance } }
-      vectorsSize = (vectorsConfig.size ?? (vectorsConfig.config as Record<string, unknown>)?.size) as number | undefined;
-      vectorsDistance = (vectorsConfig.distance ?? (vectorsConfig.config as Record<string, unknown>)?.distance) as string | undefined;
+    if (vectors) {
+      // A named vector configuration keeps the size in every named vector.
+      const named = vectors.named as Record<string, Record<string, unknown>> | undefined;
+      const firstNamed = named ? Object.values(named)[0] : undefined;
+      const nested = vectors.config as Record<string, unknown> | undefined;
+      const size = vectors.size ?? firstNamed?.size ?? nested?.size;
+      const distance = vectors.distance ?? firstNamed?.distance ?? nested?.distance;
+      if (typeof size === "number") vectorsSize = size;
+      if (typeof distance === "string") vectorsDistance = distance;
     }
 
-    // Points count might be in different locations depending on Qdrant version
-    const pointsCount = (info.points ?? info.num_points ?? info.points_count) as number | undefined;
+    // The point count lives in `points_count`; the other names are the ones
+    // other Qdrant versions and proxies use.
+    const pointsCount = (info.points_count ?? info.num_points ?? info.points) as number | undefined;
 
     return {
       exists: true,

package/packages/qdrant-skills/src/embedder.ts

@@ -18,6 +18,15 @@ export interface EmbeddingResult {
   tokens: number;
 }
 
+/**
+ * The result of a batch embedding: one vector per input text, in the order
+ * of the input.
+ */
+export interface BatchEmbeddingResult {
+  embeddings: number[][];
+  tokens: number;
+}
+
 /** The embeddings endpoint of OpenAI. */
 const OPENAI_EMBEDDINGS_URL = "https://api.openai.com/v1/embeddings";
 
@@ -82,6 +91,18 @@ export function getOpenAIApiKey(): string | null {
   return readPiAuthToken();
 }
 
+/**
+ * The embedding model of the skill collection.
+ *
+ * The model decides the vector size, so it is part of the schema of the
+ * collection: a collection built with a different model holds vectors of a
+ * different size and cannot be searched with these vectors.
+ */
+export const EMBEDDING_MODEL = "text-embedding-3-small";
+
+/** The vector size of {@link EMBEDDING_MODEL}. */
+export const EMBEDDING_DIMENSIONS = 1536;
+
 /**
  * Create embedding for text using OpenAI
  */
@@ -101,7 +122,7 @@ export async function createEmbedding(
       "Authorization": `Bearer ${key}`,
     },
     body: JSON.stringify({
-      model: "text-embedding-3-small",
+      model: EMBEDDING_MODEL,
       input: text.slice(0, 8000), // Limit to avoid token limits
     }),
   });
@@ -122,6 +143,87 @@ export async function createEmbedding(
   };
 }
 
+/**
+ * The number of texts one embeddings request may carry. The endpoint of
+ * OpenAI accepts an array of inputs, so a batch costs one request instead of
+ * one request per text.
+ */
+const MAX_BATCH_INPUTS = 64;
+
+/**
+ * The options of an embeddings request.
+ */
+export interface EmbeddingRequestOptions {
+  /**
+   * The HTTP client of the request. The default is the global `fetch`; a
+   * caller (a test) can pass its own, so no global has to be replaced.
+   */
+  fetchImpl?: typeof fetch;
+}
+
+/**
+ * Create embeddings for many texts with as few requests as possible.
+ *
+ * One request per text exhausts the sockets of the process when a registry
+ * holds hundreds of skills: every request opens its own connection and the
+ * process then cannot talk to anything else. The endpoint of OpenAI accepts
+ * an array of inputs, so a batch stays one request per chunk.
+ */
+export async function createEmbeddingsBatch(
+  texts: string[],
+  apiKey?: string,
+  options: EmbeddingRequestOptions = {}
+): Promise<BatchEmbeddingResult> {
+  const key = apiKey || getOpenAIApiKey();
+  if (!key) {
+    throw new Error("No OpenAI API key available for embeddings");
+  }
+  if (texts.length === 0) {
+    return { embeddings: [], tokens: 0 };
+  }
+
+  const send = options.fetchImpl ?? fetch;
+  const embeddings: number[][] = [];
+  let tokens = 0;
+
+  for (let offset = 0; offset < texts.length; offset += MAX_BATCH_INPUTS) {
+    const chunk = texts
+      .slice(offset, offset + MAX_BATCH_INPUTS)
+      .map((text) => text.slice(0, 8000));
+
+    const response = await send(OPENAI_EMBEDDINGS_URL, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${key}`,
+      },
+      body: JSON.stringify({
+        model: EMBEDDING_MODEL,
+        input: chunk,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`OpenAI embedding failed: ${error}`);
+    }
+
+    const data = (await response.json()) as {
+      data: Array<{ embedding: number[]; index: number }>;
+      usage?: { total_tokens?: number };
+    };
+
+    // The endpoint may answer out of order, so the index decides the place.
+    const ordered = [...data.data].sort((a, b) => a.index - b.index);
+    for (const entry of ordered) {
+      embeddings.push(entry.embedding || []);
+    }
+    tokens += data.usage?.total_tokens || 0;
+  }
+
+  return { embeddings, tokens };
+}
+
 /**
  * Create embedding for a skill document
  */

package/packages/qdrant-skills/src/index.ts

@@ -37,8 +37,13 @@ export {
 
 export {
   createEmbedding,
+  createEmbeddingsBatch,
   embedSkillDocument,
   embedSkillsBatch,
   getOpenAIApiKey,
+  EMBEDDING_MODEL,
+  EMBEDDING_DIMENSIONS,
+  type BatchEmbeddingResult,
+  type EmbeddingRequestOptions,
   type EmbeddingResult,
 } from './embedder.js';

package/packages/qdrant-skills/test/collection-info.test.ts

@@ -0,0 +1,129 @@
+/**
+ * The collection info of Qdrant.
+ *
+ * Qdrant reports the vector configuration under `config.params.vectors` -
+ * not at the top level. Reading `info.vectors` yields undefined for every
+ * collection, which turned every schema check into "dimension mismatch:
+ * got undefined" and hid the real cause of an incompatible collection.
+ *
+ * The client is a small double, so the test never reaches the network.
+ */
+
+import { describe, expect, it } from "bun:test";
+
+import { getCollectionInfo, validateCollectionSchema } from "../src/client.js";
+
+/** A client that answers with the given collection description. */
+function fakeClient(description: unknown): {
+	getCollection: (name: string) => Promise<unknown>;
+} {
+	return {
+		getCollection: async () => description,
+	};
+}
+
+/** The description Qdrant answers with for a 384-dimensional collection. */
+const MINILM_DESCRIPTION = {
+	status: "green",
+	points_count: 79,
+	config: {
+		params: {
+			vectors: { size: 384, distance: "Cosine" },
+		},
+	},
+};
+
+describe("the collection info", () => {
+	it("reads the vector size and the distance", async () => {
+		const info = await getCollectionInfo(
+			fakeClient(MINILM_DESCRIPTION) as never,
+			"pi-harness-skills",
+		);
+		expect(info).not.toBeNull();
+		expect(info?.exists).toBe(true);
+		expect(info?.vectorsSize).toBe(384);
+		expect(info?.vectorsDistance).toBe("Cosine");
+	});
+
+	it("reads the number of points", async () => {
+		const info = await getCollectionInfo(
+			fakeClient(MINILM_DESCRIPTION) as never,
+			"pi-harness-skills",
+		);
+		expect(info?.pointsCount).toBe(79);
+	});
+
+	it("reads a named vector configuration", async () => {
+		const info = await getCollectionInfo(
+			fakeClient({
+				points_count: 3,
+				config: {
+					params: {
+						vectors: { named: { text: { size: 1536, distance: "Dot" } } },
+					},
+				},
+			}) as never,
+			"pi-harness-skills",
+		);
+		expect(info?.vectorsSize).toBe(1536);
+		expect(info?.vectorsDistance).toBe("Dot");
+	});
+
+	it("still reads a flat description", async () => {
+		// An older proxy answers without the config wrapper.
+		const info = await getCollectionInfo(
+			fakeClient({ points_count: 1, vectors: { size: 1536, distance: "Cosine" } }) as never,
+			"pi-harness-skills",
+		);
+		expect(info?.vectorsSize).toBe(1536);
+		expect(info?.vectorsDistance).toBe("Cosine");
+	});
+
+	it("reports a missing collection", async () => {
+		const client = {
+			getCollection: async () => {
+				throw new Error("Not found: Collection not found");
+			},
+		};
+		const info = await getCollectionInfo(client as never, "pi-harness-skills");
+		expect(info).toEqual({ exists: false });
+	});
+
+	it("reports an unreadable collection as unknown", async () => {
+		const client = {
+			getCollection: async () => {
+				throw new Error("connection refused");
+			},
+		};
+		expect(await getCollectionInfo(client as never, "pi-harness-skills")).toBeNull();
+	});
+});
+
+describe("the schema check", () => {
+	it("names the real dimensions of an incompatible collection", async () => {
+		const result = await validateCollectionSchema(
+			fakeClient(MINILM_DESCRIPTION) as never,
+			"pi-harness-skills",
+			1536,
+		);
+		expect(result.valid).toBe(false);
+		// The message names the size the collection really has - not
+		// "undefined".
+		expect(result.error).toContain("384");
+		expect(result.error).not.toContain("undefined");
+		expect(result.actualDimensions).toBe(384);
+	});
+
+	it("accepts a collection with the expected dimensions", async () => {
+		const result = await validateCollectionSchema(
+			fakeClient({
+				points_count: 79,
+				config: { params: { vectors: { size: 1536, distance: "Cosine" } } },
+			}) as never,
+			"pi-harness-skills",
+			1536,
+		);
+		expect(result.valid).toBe(true);
+		expect(result.actualDimensions).toBe(1536);
+	});
+});

package/packages/qdrant-skills/test/embedder-batch.test.ts

@@ -0,0 +1,184 @@
+/**
+ * The batch embeddings of the embedder.
+ *
+ * One request per text exhausts the sockets of the process when a registry
+ * holds hundreds of skills. The endpoint of OpenAI accepts an array of
+ * inputs, so a batch stays one request per chunk.
+ *
+ * The HTTP client is injected, so the test never replaces a global and never
+ * reaches the network.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createEmbeddingsBatch } from "../src/embedder.js";
+
+/** One recorded request. */
+interface RecordedRequest {
+	url: string;
+	body: { model: string; input: string[] };
+	authorization: string;
+}
+
+/** A client that answers with the given vectors. */
+function fakeFetch(
+	vectors: number[][],
+	recorded: RecordedRequest[],
+): typeof fetch {
+	return (async (input: string | URL | Request, init?: RequestInit) => {
+		const body = JSON.parse(String(init?.body ?? "{}")) as {
+			model: string;
+			input: string[];
+		};
+		recorded.push({
+			url: String(input),
+			body,
+			authorization: String(
+				(init?.headers as Record<string, string>)?.Authorization ?? "",
+			),
+		});
+		return {
+			ok: true,
+			json: async () => ({
+				// The endpoint may answer out of order.
+				data: body.input.map((_, index) => {
+					const position = body.input.length - 1 - index;
+					return { index: position, embedding: vectors[position] };
+				}),
+				usage: { total_tokens: body.input.length * 3 },
+			}),
+			text: async () => "",
+		} as Response;
+	}) as unknown as typeof fetch;
+}
+
+/** The environment variables the key lookup looks at. */
+const ENV_KEYS = ["OPENAI_API_KEY", "HOME", "USERPROFILE"] as const;
+
+let saved: Record<string, string | undefined> = {};
+let tempHome: string;
+
+beforeEach(() => {
+	saved = {};
+	for (const key of ENV_KEYS) {
+		saved[key] = process.env[key];
+		delete process.env[key];
+	}
+	// A fresh home directory: the test never reads the key of the machine
+	// it runs on.
+	tempHome = mkdtempSync(join(homedir(), ".test-qdrant-batch-"));
+	process.env.HOME = tempHome;
+	process.env.USERPROFILE = tempHome;
+});
+
+afterEach(() => {
+	for (const key of ENV_KEYS) {
+		if (saved[key] === undefined) delete process.env[key];
+		else process.env[key] = saved[key];
+	}
+	rmSync(tempHome, { recursive: true, force: true });
+});
+
+describe("the batch embeddings of the embedder", () => {
+	it("sends one request for many texts", async () => {
+		const recorded: RecordedRequest[] = [];
+		const texts = ["first", "second", "third"];
+
+		const result = await createEmbeddingsBatch(
+			texts,
+			"sk-test-key",
+			{ fetchImpl: fakeFetch([[1], [2], [3]], recorded) },
+		);
+
+		expect(recorded.length).toBe(1);
+		expect(recorded[0].body.input).toEqual(texts);
+		expect(result.embeddings).toEqual([[1], [2], [3]]);
+		expect(result.tokens).toBe(9);
+	});
+
+	it("keeps the order of the texts even when the answer is out of order", async () => {
+		const recorded: RecordedRequest[] = [];
+
+		const result = await createEmbeddingsBatch(
+			["a", "b", "c"],
+			"sk-test-key",
+			{ fetchImpl: fakeFetch([[10], [20], [30]], recorded) },
+		);
+
+		expect(result.embeddings).toEqual([[10], [20], [30]]);
+	});
+
+	it("splits a large input into chunks", async () => {
+		const recorded: RecordedRequest[] = [];
+		const texts = Array.from({ length: 150 }, (_, index) => `text-${index}`);
+
+		const result = await createEmbeddingsBatch(
+			texts,
+			"sk-test-key",
+			{ fetchImpl: fakeFetch(texts.map((_, index) => [index]), recorded) },
+		);
+
+		// The chunk size is 64, so 150 texts need three requests.
+		expect(recorded.length).toBe(3);
+		expect(recorded[0].body.input.length).toBe(64);
+		expect(recorded[1].body.input.length).toBe(64);
+		expect(recorded[2].body.input.length).toBe(22);
+		expect(result.embeddings.length).toBe(150);
+		expect(result.tokens).toBe(150 * 3);
+	});
+
+	it("sends no request for an empty input", async () => {
+		const recorded: RecordedRequest[] = [];
+
+		const result = await createEmbeddingsBatch([], "sk-test-key", {
+			fetchImpl: fakeFetch([], recorded),
+		});
+
+		expect(recorded.length).toBe(0);
+		expect(result.embeddings).toEqual([]);
+		expect(result.tokens).toBe(0);
+	});
+
+	it("sends the OpenAI key of the caller", async () => {
+		const recorded: RecordedRequest[] = [];
+
+		await createEmbeddingsBatch(["text"], "sk-test-key", {
+			fetchImpl: fakeFetch([[1]], recorded),
+		});
+
+		expect(recorded[0].authorization).toBe("Bearer sk-test-key");
+		expect(recorded[0].url).toBe("https://api.openai.com/v1/embeddings");
+	});
+
+	it("trims a very long text", async () => {
+		const recorded: RecordedRequest[] = [];
+
+		await createEmbeddingsBatch(["x".repeat(9000)], "sk-test-key", {
+			fetchImpl: fakeFetch([[1]], recorded),
+		});
+
+		expect(recorded[0].body.input[0].length).toBe(8000);
+	});
+
+	it("reports a failed request", async () => {
+		const failing = (async () =>
+			({
+				ok: false,
+				text: async () => "the endpoint refused the request",
+			}) as Response) as unknown as typeof fetch;
+
+		await expect(
+			createEmbeddingsBatch(["text"], "sk-test-key", { fetchImpl: failing }),
+		).rejects.toThrow(/OpenAI embedding failed/);
+	});
+
+	it("reports a missing key", async () => {
+		// The home directory points at a fresh directory and the environment
+		// carries no key, so the machine of the test cannot provide one.
+		await expect(
+			createEmbeddingsBatch(["text"], "", { fetchImpl: fakeFetch([[1]], []) }),
+		).rejects.toThrow(/No OpenAI API key/);
+	});
+});

package/packages/quota-manager/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/quota-manager",
-  "version": "1.1.410",
+  "version": "1.1.412",
   "description": "pi-harness-runtime — quota-manager",
   "type": "module",
   "main": "./dist/index.js",

package/packages/rate-limiter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/rate-limiter",
-  "version": "1.1.410",
+  "version": "1.1.412",
   "type": "module",
   "description": "Rate limiting with token bucket algorithm (RFC-0023)",
   "main": "dist/index.js",

package/packages/react-vite-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/react-vite-plugin",
-  "version": "1.1.410",
+  "version": "1.1.412",
   "description": "React/Vite framework analysis — components, config, TypeScript setup",
   "type": "module",
   "main": "./dist/index.js",

package/packages/relay/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/relay",
-  "version": "1.1.410",
+  "version": "1.1.412",
   "type": "module",
   "description": "Cloud relay for remote access - T3 Connect style for pi-harness",
   "main": "./dist/index.js",

package/packages/release-manager/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/release-manager",
-  "version": "1.1.410",
+  "version": "1.1.412",
   "type": "module",
   "description": "Release management for pi-harness",
   "main": "dist/index.js",

package/packages/requirement-compiler/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/requirement-compiler",
-  "version": "1.1.410",
+  "version": "1.1.412",
   "description": "Compiles raw requirements into validated CompiledRequirement with ambiguity detection and risk tagging",
   "type": "module",
   "main": "./dist/index.js",

package/packages/runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/runtime",
-  "version": "1.1.410",
+  "version": "1.1.412",
   "description": "pi-harness-runtime — runtime",
   "type": "module",
   "main": "./dist/index.js",

package/packages/scheduler/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/scheduler",
-  "version": "1.1.410",
+  "version": "1.1.412",
   "description": "pi-harness-runtime — scheduler",
   "type": "module",
   "main": "./dist/index.js",

package/packages/scheduler-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/scheduler-adapter",
-  "version": "1.1.410",
+  "version": "1.1.412",
   "description": "Scheduler Adapter — cron, systemd, launchd, internal adapters for autonomous runtime (RFC-0101 §6)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/session/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/session",
-  "version": "1.1.410",
+  "version": "1.1.412",
   "description": "Session management system for pi-harness-runtime",
   "type": "module",
   "main": "./dist/index.js",

package/packages/session-api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/session-api",
-  "version": "1.1.410",
+  "version": "1.1.412",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/session-export/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/session-export",
-  "version": "1.1.410",
+  "version": "1.1.412",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/shared-context/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/shared-context",
-  "version": "1.1.410",
+  "version": "1.1.412",
   "description": "pi-harness-runtime — shared-context",
   "type": "module",
   "main": "./dist/index.js",

package/packages/skill-mcp-client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/skill-mcp-client",
-  "version": "1.1.410",
+  "version": "1.1.412",
   "description": "MCP client for Skills SaaS backend",
   "type": "module",
   "main": "./dist/index.js",

package/packages/skill-registry/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/skill-registry",
-  "version": "1.1.410",
+  "version": "1.1.412",
   "description": "Skill Registry for pi-harness-runtime — dynamic skill discovery and invocation",
   "type": "module",
   "main": "./dist/index.js",

package/packages/skills/dist/index.d.ts

@@ -11,18 +11,36 @@ export * from "./types.js";
 export * from "./parser.js";
 export * from "./scanner.js";
 export * from "./loader.js";
+export * from "./vector-schema.js";
+export * from "./remote-source.js";
 export * from "./skill-commands.js";
 export * from "./skill-tool.js";
 export * from "./skill-versioning.js";
 export * from "./linter.js";
 import type { SkillsConfig, ScanResult } from "./types.js";
+import { type SkillRegistry } from "./loader.js";
+/**
+ * The result of the skill initialization.
+ *
+ * The registry is part of the result so a caller can ask the vector store
+ * about its state (how many skills it holds) without reaching for the
+ * global registry.
+ */
+export interface SkillsInitResult extends ScanResult {
+    /** The registry the skills were registered in. */
+    registry: SkillRegistry;
+}
 /**
  * Initialize skills system
+ *
+ * A caller (a test) can pass its own registry, so the initialization does
+ * not have to touch the global one.
  */
 export declare function initSkills(config?: Partial<SkillsConfig & {
     maxDepth?: number;
     includeHidden?: boolean;
-}>): ScanResult;
+    registry?: SkillRegistry;
+}>): SkillsInitResult;
 /**
  * Get skills summary
  */