pi-harness-runtime 1.1.413 → 1.1.415

package/packages/skills/src/vector-schema.ts

@@ -16,6 +16,8 @@
  * of the vector store.
  */
 
+import { sanitizeText, skillPointName } from "./sanitize.js";
+
 /**
  * The collection the runtime indexes into and searches.
  *
@@ -51,12 +53,133 @@ export interface SkillVectorSchema {
 }
 
 /**
- * Why the collection does not match the expected schema - or null when it
- * does.
+ * The payload of a skill point.
+ *
+ * Both writers of the collection - the runtime registry and
+ * `scripts/sync-to-qdrant.ts` - store the SAME payload under the SAME
+ * point id. A point is addressed by its id, so a writer that used a
+ * different id for the same skill would leave two points behind, and a
+ * writer whose id happened to collide with a foreign one would overwrite
+ * an unrelated skill.
+ */
+export type SkillPointPayload = {
+  /** The name of the skill. The point id is derived from it. */
+  name: string;
+  /** What the skill does. */
+  description: string;
+  /** The body of the skill. */
+  body: string;
+  /** The text the vector was built from. */
+  text: string;
+};
+
+/**
+ * The body of a payload is truncated.
+ *
+ * A payload is an index, not a file store - the complete skill comes from
+ * the skill service.
+ */
+export const SKILL_PAYLOAD_BODY_LIMIT = 2000;
+
+/** The text of a payload is truncated as well. */
+export const SKILL_PAYLOAD_TEXT_LIMIT = 1500;
+
+/**
+ * A stable hash of a string.
+ *
+ * The same string always produces the same number, in every process and
+ * on every machine - a point id has to survive a restart.
+ *
+ * Two uses:
+ * - the id of a point is the hash of the name its payload carries, so the
+ *   point id and the payload name always belong together. Two writers
+ *   that store the same name address the same point.
+ * - the hash of the text of a skill says whether its content changed.
+ */
+export function stableHash(value: string): number {
+  let hash = 0;
+  for (let i = 0; i < value.length; i++) {
+    hash = (Math.imul(31, hash) + value.charCodeAt(i)) | 0;
+  }
+  return Math.abs(hash);
+}
+
+/**
+ * The text a skill vector is built from.
  *
- * The message names the numbers, so the reader can tell WHICH schema the
- * collection was built with.
+ * The title is added when it differs from the name: a skill whose
+ * directory is named differently from its title carries both.
  */
+export function skillPointText(input: {
+  /** The name the payload carries - the identity of the skill. */
+  name: string;
+  /** The title of the skill, when it differs from the name. */
+  title?: string;
+  /** What the skill does. */
+  description: string;
+  /** The body of the skill. */
+  body: string;
+}): string {
+  const parts = [input.name];
+  if (input.title && input.title !== input.name) parts.push(input.title);
+  parts.push(input.description);
+  parts.push(input.body.slice(0, SKILL_PAYLOAD_TEXT_LIMIT));
+  return parts.join(" ");
+}
+
+/**
+ * A point of the skill collection.
+ *
+ * The id is the hash of the name the payload carries, so the point id and
+ * the payload name always belong together: two writers that store the
+ * same name address the same point.
+ */
+export interface SkillQdrantPoint {
+  id: number;
+  payload: SkillPointPayload;
+}
+
+/**
+ * The point of a skill.
+ *
+ * The runtime registry and `scripts/sync-to-qdrant.ts` both build their
+ * points here, so they cannot drift apart. A writer that used its own id
+ * would leave a second point for every skill the other one indexes, and
+ * an id that happens to collide with a foreign one would overwrite an
+ * unrelated skill.
+ */
+export function skillQdrantPoint(payload: SkillPointPayload): SkillQdrantPoint {
+  return { id: stableHash(payload.name), payload };
+}
+
+/**
+ * The payload of a skill point.
+ *
+ * The payload is sanitized: the collection is shared, so the client names
+ * of a user must not travel into it. Both writers use this function, so
+ * both write the same sanitized payload for the same skill.
+ */
+export function skillPointPayload(input: {
+  /** The name the payload carries - the identity of the skill. */
+  name: string;
+  /** The title of the skill, when it differs from the name. */
+  title?: string;
+  /** What the skill does. */
+  description: string;
+  /** The body of the skill. */
+  body: string;
+}): SkillPointPayload {
+  const name = skillPointName(input.name);
+  const title = input.title ? skillPointName(input.title) : undefined;
+  const description = sanitizeText(input.description);
+  const body = sanitizeText(input.body).slice(0, SKILL_PAYLOAD_BODY_LIMIT);
+  return {
+    name,
+    description,
+    body,
+    text: skillPointText({ name, title, description, body }),
+  };
+}
 export function describeSkillSchemaMismatch(
 	actual: { dimensions?: number; distance?: string },
 	expected: SkillVectorSchema,

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

@@ -169,6 +169,47 @@ describe("a skill that only exists in the vector store", () => {
 	});
 });
 
+describe("a hit that carries the shared name of a local skill", () => {
+	it("resolves to the local skill", async () => {
+		// The collection is shared, so the point carries the SANITIZED name.
+		const client = fakeClient([
+			{
+				id: 1,
+				score: 0.9,
+				payload: {
+					name: "client-a-pe-approval-workflow",
+					description: "the workflow",
+					body: "the body",
+				},
+			},
+		]);
+		const registry = createSkillRegistry({
+			qdrantClient: client,
+			embedder: fakeEmbedder,
+			collection: "pi-harness-skills-test",
+		});
+		registry.register(localSkill("inpac-pe-approval-workflow"));
+
+		const results = await registry.findVector("workflow");
+
+		expect(results).toHaveLength(1);
+		// The skill of this machine stays a local skill - with its own
+		// name and its own body, not the sanitized copy.
+		expect(results[0].source).toBe("local");
+		expect(results[0].skill.id).toBe("inpac-pe-approval-workflow");
+		expect(results[0].skill.body).toBe("the local body of inpac-pe-approval-workflow");
+	});
+
+	it("resolves the shared name of a local skill in a lookup", () => {
+		const registry = createSkillRegistry({ indexer: null });
+		registry.register(localSkill("inpac-pe-approval-workflow"));
+
+		expect(registry.get("client-a-pe-approval-workflow")?.id).toBe(
+			"inpac-pe-approval-workflow",
+		);
+	});
+});
+
 describe("the state of the vector store", () => {
 	it("reports the number of skills", async () => {
 		const client = fakeClient([], {

package/packages/skills/test/sanitize.test.ts

@@ -0,0 +1,88 @@
+/**
+ * Tests for the sanitization of a skill for the shared collection.
+ *
+ * The collection is shared, so the client names of a user must not travel
+ * into it. The rules used to live in `scripts/sync-to-qdrant.ts` - the
+ * only writer that could reach them. The runtime registry writes into the
+ * same collection, so it needs them too.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import { sanitizeText, skillPointName } from "../src/sanitize.js";
+import { skillPointPayload } from "../src/vector-schema.js";
+
+describe("the sanitization of a text", () => {
+	test("the name of a client is replaced", () => {
+		expect(sanitizeText("the inpac workflow")).toBe("the [Client A] workflow");
+		expect(sanitizeText("for digisoft")).toBe("for [Client B]");
+		expect(sanitizeText("gse-insurance step")).toBe("[Insurance Project] step");
+	});
+
+	test("the name of a client is replaced in any case", () => {
+		expect(sanitizeText("INPAC and Inpac")).toBe("[Client A] and [Client A]");
+	});
+
+	test("a text without a client name stays the same", () => {
+		expect(sanitizeText("a plain skill")).toBe("a plain skill");
+	});
+
+	test("the generic phrases are replaced", () => {
+		expect(sanitizeText("Company Name")).toBe("[Client Name]");
+		expect(sanitizeText("your company")).toBe("[Client]");
+		expect(sanitizeText("our client")).toBe("[Client]");
+	});
+});
+
+describe("the name of a skill in the shared collection", () => {
+	test("a name of the map is renamed", () => {
+		expect(skillPointName("inpac-pe-approval-workflow")).toBe(
+			"client-a-pe-approval-workflow",
+		);
+		expect(skillPointName("tbs-import-clearance-lcv")).toBe(
+			"import-project-clearance",
+		);
+		expect(skillPointName("whispertool")).toBe("whisper-tool");
+	});
+
+	test("a name without a client name stays the same", () => {
+		expect(skillPointName("code-review")).toBe("code-review");
+	});
+
+	test("the name never carries a client name", () => {
+		for (const name of [
+			"inpac-pe-approval-workflow",
+			"gse-insurance-step5-slot-filter",
+			"tbs-import-clearance-lcv",
+			"whispertool",
+		]) {
+			expect(skillPointName(name)).not.toMatch(/inpac|gse-insurance|tbs-import/i);
+		}
+	});
+});
+
+describe("the payload of a point is sanitized", () => {
+	test("the client names of the body do not travel into the collection", () => {
+		const payload = skillPointPayload({
+			name: "inpac-pe-approval-workflow",
+			description: "the workflow of inpac",
+			body: "the approval of inpac for the client",
+		});
+
+		expect(payload.name).toBe("client-a-pe-approval-workflow");
+		expect(payload.description).not.toMatch(/inpac/i);
+		expect(payload.body).not.toMatch(/inpac/i);
+		expect(payload.text).not.toMatch(/inpac/i);
+	});
+
+	test("the text is built from the sanitized parts", () => {
+		const payload = skillPointPayload({
+			name: "inpac-pe-approval-workflow",
+			description: "the workflow",
+			body: "the body",
+		});
+
+		expect(payload.text).toContain("client-a-pe-approval-workflow");
+		expect(payload.text).not.toContain("inpac-pe-approval-workflow");
+	});
+});

package/packages/skills/test/vector-schema.test.ts

@@ -0,0 +1,167 @@
+/**
+ * Regression tests for the point identity of the skill collection.
+ *
+ * Two writers fill the same collection: the runtime registry and
+ * `scripts/sync-to-qdrant.ts`. They used to disagree about the identity of
+ * a point - the runtime hashed the name of the skill, the script used a
+ * running number. The same skill then existed twice, and a running number
+ * could overwrite a point of an unrelated skill.
+ *
+ * The identity now comes from one shared place, and these tests hold it
+ * there.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import {
+	createSkillRegistry,
+	type SkillVectorIndexer,
+	type SkillVectorPoint,
+} from "../src/loader.js";
+import {
+	SKILL_PAYLOAD_BODY_LIMIT,
+	SKILL_PAYLOAD_TEXT_LIMIT,
+	skillPointPayload,
+	skillQdrantPoint,
+	stableHash,
+} from "../src/vector-schema.js";
+import type { Skill } from "../src/types.js";
+
+/** Wait until the registry has no index work left. */
+async function settle(registry: { isIndexing(): boolean }): Promise<void> {
+	for (let attempt = 0; attempt < 200 && registry.isIndexing(); attempt++) {
+		await new Promise((resolve) => setTimeout(resolve, 5));
+	}
+}
+
+/** A skill with the given id and body. */
+function makeSkill(id: string, body = `body of ${id}`): Skill {
+	return {
+		id,
+		path: `/tmp/skills/${id}`,
+		frontmatter: {
+			name: id,
+			description: `the ${id} skill`,
+		},
+		body,
+		metadata: {} as Skill["metadata"],
+	} as Skill;
+}
+
+/** An indexer that keeps the points it receives. */
+class RecordingIndexer implements SkillVectorIndexer {
+	readonly upsertCalls: SkillVectorPoint[][] = [];
+
+	async embed(texts: string[]): Promise<number[][]> {
+		return texts.map((text) => [text.length, 1, 2]);
+	}
+
+	async upsert(points: SkillVectorPoint[]): Promise<void> {
+		this.upsertCalls.push(points);
+	}
+}
+
+describe("the identity of a skill point", () => {
+	test("the id of the point is the hash of the name in the payload", () => {
+		const payload = skillPointPayload({
+			name: "a-skill",
+			description: "does something",
+			body: "the body",
+		});
+		const point = skillQdrantPoint(payload);
+
+		expect(point.id).toBe(stableHash(payload.name));
+	});
+
+	test("the same name always addresses the same point", () => {
+		const first = skillQdrantPoint(
+			skillPointPayload({ name: "a-skill", description: "one", body: "one" }),
+		);
+		const second = skillQdrantPoint(
+			skillPointPayload({ name: "a-skill", description: "two", body: "two" }),
+		);
+
+		// The content may change, the identity of the point may not.
+		expect(second.id).toBe(first.id);
+	});
+
+	test("different names address different points", () => {
+		const first = skillQdrantPoint(
+			skillPointPayload({ name: "a-skill", description: "d", body: "b" }),
+		);
+		const second = skillQdrantPoint(
+			skillPointPayload({ name: "b-skill", description: "d", body: "b" }),
+		);
+
+		expect(second.id).not.toBe(first.id);
+	});
+
+	test("the payload carries the shared fields and nothing else", () => {
+		const payload = skillPointPayload({
+			name: "a-skill",
+			title: "A Skill",
+			description: "does something",
+			body: "the body",
+		});
+
+		expect(Object.keys(payload).sort()).toEqual([
+			"body",
+			"description",
+			"name",
+			"text",
+		]);
+	});
+
+	test("the payload and the text are truncated", () => {
+		const payload = skillPointPayload({
+			name: "a-skill",
+			description: "d",
+			body: "x".repeat(SKILL_PAYLOAD_BODY_LIMIT + 500),
+		});
+
+		expect(payload.body.length).toBe(SKILL_PAYLOAD_BODY_LIMIT);
+		expect(payload.text.length).toBeLessThanOrEqual(
+			SKILL_PAYLOAD_TEXT_LIMIT + payload.name.length + payload.description.length + 10,
+		);
+	});
+
+	test("the title is part of the text when it differs from the name", () => {
+		const withTitle = skillPointPayload({
+			name: "a-skill",
+			title: "A Human Title",
+			description: "d",
+			body: "b",
+		});
+		const withoutTitle = skillPointPayload({
+			name: "a-skill",
+			description: "d",
+			body: "b",
+		});
+
+		expect(withTitle.text).toContain("A Human Title");
+		expect(withoutTitle.text).not.toContain("A Human Title");
+	});
+});
+
+describe("the runtime writes the points of the shared schema", () => {
+	test("the indexed point carries the shared payload and id", async () => {
+		const indexer = new RecordingIndexer();
+		const registry = createSkillRegistry({ indexer });
+
+		registry.register(makeSkill("alpha"));
+		await settle(registry);
+
+		const points = indexer.upsertCalls.flat();
+		expect(points.length).toBe(1);
+
+		const point = points[0];
+		expect(point.id).toBe(stableHash(point.payload.name));
+		expect(point.payload.name).toBe("alpha");
+		expect(Object.keys(point.payload).sort()).toEqual([
+			"body",
+			"description",
+			"name",
+			"text",
+		]);
+	});
+});

package/packages/sprint-planner/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/sprint-planner",
-  "version": "1.1.413",
+  "version": "1.1.415",
   "type": "module",
   "description": "Sprint planning engine for pi-harness",
   "main": "dist/index.js",

package/packages/subscription-engine/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/subscription-engine",
-  "version": "1.1.413",
+  "version": "1.1.415",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/task-compiler/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/task-compiler",
-  "version": "1.1.413",
+  "version": "1.1.415",
   "description": "Task Compiler for pi-harness-runtime — produces deterministic task DAG from CompiledRequirement",
   "type": "module",
   "main": "./dist/index.js",

package/packages/telegram/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/telegram",
-  "version": "1.1.413",
+  "version": "1.1.415",
   "description": "pi-harness-runtime — Telegram inbound/outbound",
   "type": "module",
   "main": "./src/index.js",

package/packages/tencentdb-memory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moocoding/tencentdb-memory",
-  "version": "1.1.413",
+  "version": "1.1.415",
   "description": "TencentDB Agent Memory client - sync skills to centralized knowledge base",
   "type": "module",
   "main": "src/index.ts",

package/packages/tencentdb-sync/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/tencentdb-sync",
-  "version": "1.1.413",
+  "version": "1.1.415",
   "description": "Sync SKILL.md skills to TencentDB-Agent-Memory server (RFC-0105/0106)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/test-data-generator/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/test-data-generator",
-  "version": "1.1.413",
+  "version": "1.1.415",
   "description": "Test data generation for pi-harness-runtime",
   "type": "module",
   "main": "./dist/index.js",

package/packages/test-generator/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/test-generator",
-  "version": "1.1.413",
+  "version": "1.1.415",
   "description": "Auto-Test Generator — generate unit and E2E tests from source code (RFC-0013)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/todo-bd-sync/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moocoding/todo-bd-sync",
-  "version": "1.1.413",
+  "version": "1.1.415",
   "description": "Two-way sync between rpiv-todo overlay and bd issue tracker",
   "type": "module",
   "main": "src/index.ts",

package/packages/token-estimation/package.json

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

package/packages/token-optimizer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/token-optimizer",
-  "version": "1.1.413",
+  "version": "1.1.415",
   "description": "Token Budget Optimizer — maximize prompt value within token limits (RFC-0011)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/tooling-preference/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/tooling-preference",
-  "version": "1.1.413",
+  "version": "1.1.415",
   "description": "pi-harness-runtime — JS/TS tooling preference (Biome vs ESLint/Prettier) proposal",
   "type": "module",
   "main": "./dist/index.js",

package/packages/trajectory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/trajectory",
-  "version": "1.1.413",
+  "version": "1.1.415",
   "description": "Trajectory capture for the write-review loop — persists cycle records for learning",
   "type": "module",
   "main": "./dist/src/index.js",

package/packages/tui/package.json

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

package/packages/two-phase-review/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/two-phase-review",
-  "version": "1.1.413",
+  "version": "1.1.415",
   "description": "pi-harness-runtime — two-phase implementation and review workflow (queue review signals, gate the phase, scope the diff)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/types/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/types",
-  "version": "1.1.413",
+  "version": "1.1.415",
   "description": "Shared TypeScript types for pi-harness-runtime packages",
   "type": "module",
   "main": "./dist/index.js",

package/packages/voice-api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/voice-api",
-  "version": "1.1.413",
+  "version": "1.1.415",
   "type": "module",
   "description": "Voice-to-text API using Whisper for Telegram and LINE integration",
   "main": "./dist/index.js",

package/packages/webmcp-tester/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/webmcp-tester",
-  "version": "1.1.413",
+  "version": "1.1.415",
   "description": "WebMCP-powered E2E testing for pi-harness - natural language test scenarios",
   "type": "module",
   "main": "./dist/index.js",

package/packages/wiki/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/wiki",
-  "version": "1.1.413",
+  "version": "1.1.415",
   "description": "LLM Wiki integration for pi-harness-runtime",
   "type": "module",
   "main": "./dist/index.js",

package/packages/workflow-events/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/workflow-events",
-  "version": "1.1.413",
+  "version": "1.1.415",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/workspace-scanner/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/workspace-scanner",
-  "version": "1.1.413",
+  "version": "1.1.415",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/worktree/package.json

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

package/packages/write-review/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moocoding/write-review",
-  "version": "1.1.413",
+  "version": "1.1.415",
   "description": "Two-agent write-review loop with blackboard coordination",
   "type": "module",
   "main": "src/index.ts",