pi-harness-runtime 1.1.411 → 1.1.413

package/packages/skills/dist/remote-source.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The server-held skills.
+ *
+ * The vector store holds an INDEX: the name, the description and a
+ * truncated body. That is enough to FIND a skill, but not to use it - a
+ * complete SKILL.md (with its references and examples) is larger than a
+ * vector store payload should be.
+ *
+ * The remote source is therefore the authoritative store of the complete
+ * skill content. It is reached through an authenticated service, so the
+ * SERVER decides which skills this user may see. A client never decides
+ * that on its own.
+ */
+import type { Skill } from "./types.js";
+/** A skill the server holds. */
+export interface RemoteSkill {
+    /** The id the server knows the skill by. */
+    id: string;
+    /** The name of the skill. */
+    name: string;
+    /** What the skill does. */
+    description: string;
+    /** The version of the content. */
+    version?: string;
+    /** When the content changed the last time. */
+    updatedAt?: string;
+    /** The content of the skill (the body of SKILL.md). */
+    content?: string;
+    /**
+     * Whether the content is the COMPLETE skill.
+     *
+     * A vector store payload carries a truncated body - that is not a
+     * complete skill. The service returns the whole thing, so it sets
+     * this flag.
+     */
+    contentComplete?: boolean;
+}
+/** Where the server-held skills come from. */
+export interface RemoteSkillSource {
+    /**
+     * The skills the server holds for this user and workspace.
+     *
+     * @param options The search term and the number of skills to return.
+     */
+    list(options?: {
+        search?: string;
+        limit?: number;
+    }): Promise<RemoteSkill[]>;
+    /** The complete content of one skill. */
+    get(id: string): Promise<RemoteSkill | null>;
+}
+/** The reasons a call to the remote source can fail. */
+export type RemoteSkillFailure = 
+/** The service refused the call - the token is missing or wrong. */
+"denied"
+/** The service could not be reached. */
+ | "unavailable";
+/** The state of the server-held skills. */
+export type RemoteSkillState = 
+/** No service is configured. */
+"not-configured"
+/** The service refused the call. */
+ | "denied"
+/** The service could not be reached. */
+ | "unavailable"
+/** The service holds no skill for this user. */
+ | "empty"
+/** The service holds skills. */
+ | "populated";
+/** What the remote source knows. */
+export interface RemoteSkillStats {
+    /** The state of the source. */
+    state: RemoteSkillState;
+    /** The number of skills the source holds. */
+    count: number;
+    /** The reason of a failed call. */
+    error?: string;
+}
+/**
+ * A skill from a remote record.
+ *
+ * The record carries the content, so the skill is usable without a local
+ * copy. The path stays empty: a server skill has no directory on this
+ * machine.
+ */
+export declare function skillFromRemote(record: RemoteSkill): Skill;
+/**
+ * The version of a cached remote skill.
+ *
+ * A skill without a version cannot be compared - the cache keeps it.
+ */
+export declare function remoteVersion(skill: Skill | undefined): string | undefined;
+/**
+ * The safe reason of a failed call.
+ *
+ * The message never carries a credential: a token that a service echoed
+ * back is removed before the message leaves the process.
+ */
+export declare function describeRemoteFailure(error: unknown): string;
+/**
+ * Whether the cached skill is older than the record.
+ *
+ * A record without a version never replaces a cached skill: an unknown
+ * version is not evidence of a change.
+ */
+export declare function isStale(cached: Skill | undefined, record: RemoteSkill): boolean;
+//# sourceMappingURL=remote-source.d.ts.map

package/packages/skills/dist/remote-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-source.d.ts","sourceRoot":"","sources":["../src/remote-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,gCAAgC;AAChC,MAAM,WAAW,WAAW;IAC3B,4CAA4C;IAC5C,EAAE,EAAE,MAAM,CAAC;IACX,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,8CAA8C;AAC9C,MAAM,WAAW,iBAAiB;IACjC;;;;OAIG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAC5E,yCAAyC;IACzC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CAC7C;AAED,wDAAwD;AACxD,MAAM,MAAM,kBAAkB;AAC7B,oEAAoE;AAClE,QAAQ;AACV,wCAAwC;GACtC,aAAa,CAAC;AAEjB,2CAA2C;AAC3C,MAAM,MAAM,gBAAgB;AAC3B,gCAAgC;AAC9B,gBAAgB;AAClB,oCAAoC;GAClC,QAAQ;AACV,wCAAwC;GACtC,aAAa;AACf,gDAAgD;GAC9C,OAAO;AACT,gCAAgC;GAC9B,WAAW,CAAC;AAEf,oCAAoC;AACpC,MAAM,WAAW,gBAAgB;IAChC,+BAA+B;IAC/B,KAAK,EAAE,gBAAgB,CAAC;IACxB,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK,CAqB1D;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAE1E;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQ5D;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,KAAK,GAAG,SAAS,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAI/E"}

package/packages/skills/dist/remote-source.js

@@ -0,0 +1,79 @@
+/**
+ * The server-held skills.
+ *
+ * The vector store holds an INDEX: the name, the description and a
+ * truncated body. That is enough to FIND a skill, but not to use it - a
+ * complete SKILL.md (with its references and examples) is larger than a
+ * vector store payload should be.
+ *
+ * The remote source is therefore the authoritative store of the complete
+ * skill content. It is reached through an authenticated service, so the
+ * SERVER decides which skills this user may see. A client never decides
+ * that on its own.
+ */
+/**
+ * A skill from a remote record.
+ *
+ * The record carries the content, so the skill is usable without a local
+ * copy. The path stays empty: a server skill has no directory on this
+ * machine.
+ */
+export function skillFromRemote(record) {
+    const version = record.version;
+    return {
+        id: record.id,
+        path: "",
+        frontmatter: {
+            name: record.name,
+            description: record.description,
+            ...(version ? { version } : {}),
+        },
+        body: record.content ?? "",
+        references: [],
+        examples: [],
+        metadata: {
+            name: record.name,
+            description: record.description,
+            ...(version ? { version } : {}),
+            ...(record.updatedAt ? { updated_at: record.updatedAt } : {}),
+        },
+        loaded: true,
+    };
+}
+/**
+ * The version of a cached remote skill.
+ *
+ * A skill without a version cannot be compared - the cache keeps it.
+ */
+export function remoteVersion(skill) {
+    return skill?.frontmatter.version ?? skill?.metadata.version;
+}
+/**
+ * The safe reason of a failed call.
+ *
+ * The message never carries a credential: a token that a service echoed
+ * back is removed before the message leaves the process.
+ */
+export function describeRemoteFailure(error) {
+    const raw = error instanceof Error ? error.message : String(error ?? "");
+    const safe = raw
+        .replace(/bearer\s+\S+/gi, "bearer <redacted>")
+        .replace(/\b[A-Za-z0-9_-]{32,}\b/g, "<redacted>")
+        .replace(/\s+/g, " ")
+        .trim();
+    return safe.slice(0, 200) || "the service could not be reached";
+}
+/**
+ * Whether the cached skill is older than the record.
+ *
+ * A record without a version never replaces a cached skill: an unknown
+ * version is not evidence of a change.
+ */
+export function isStale(cached, record) {
+    if (!cached)
+        return true;
+    if (!record.version)
+        return false;
+    return remoteVersion(cached) !== record.version;
+}
+//# sourceMappingURL=remote-source.js.map

package/packages/skills/dist/remote-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-source.js","sourceRoot":"","sources":["../src/remote-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAsEH;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,MAAmB;IAClD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAC/B,OAAO;QACN,EAAE,EAAE,MAAM,CAAC,EAAE;QACb,IAAI,EAAE,EAAE;QACR,WAAW,EAAE;YACZ,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC/B;QACD,IAAI,EAAE,MAAM,CAAC,OAAO,IAAI,EAAE;QAC1B,UAAU,EAAE,EAAE;QACd,QAAQ,EAAE,EAAE;QACZ,QAAQ,EAAE;YACT,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/B,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC7D;QACD,MAAM,EAAE,IAAI;KACZ,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,KAAwB;IACrD,OAAO,KAAK,EAAE,WAAW,CAAC,OAAO,IAAI,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC;AAC9D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,MAAM,GAAG,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;IACzE,MAAM,IAAI,GAAG,GAAG;SACb,OAAO,CAAC,gBAAgB,EAAE,mBAAmB,CAAC;SAC9C,OAAO,CAAC,yBAAyB,EAAE,YAAY,CAAC;SAChD,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,IAAI,EAAE,CAAC;IACV,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,kCAAkC,CAAC;AAClE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CAAC,MAAyB,EAAE,MAAmB;IACrE,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAClC,OAAO,aAAa,CAAC,MAAM,CAAC,KAAK,MAAM,CAAC,OAAO,CAAC;AACjD,CAAC"}

package/packages/skills/dist/vector-schema.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The vector schema of the skill collection.
+ *
+ * A Qdrant collection holds vectors of exactly ONE size. Two different
+ * embedding models produce two different vector sizes, so they must never
+ * write into the same collection: the second writer is rejected by the
+ * server with a dimension error, and the data of the first writer becomes
+ * unsearchable by the second.
+ *
+ * The collection name carries the model and a version, so a change of the
+ * model leads to a NEW collection instead of a silent mix of two vector
+ * spaces.
+ *
+ * The model itself lives in the Qdrant package (the embedder owns it). This
+ * module owns the collection - that is a decision of the skills domain, not
+ * of the vector store.
+ */
+/**
+ * The collection the runtime indexes into and searches.
+ *
+ * `QDRANT_COLLECTION` overrides it, so a cluster that already holds a
+ * collection under another name keeps working.
+ */
+export declare const SKILL_COLLECTION = "pi-harness-skills-openai-v1";
+/**
+ * The collection that was used before the schema was versioned.
+ *
+ * It holds 384-dimensional vectors - the model that
+ * `scripts/sync-to-qdrant.ts` used - and is NOT compatible with the
+ * runtime. It is named here so a mismatch can name the real cause instead
+ * of only the numbers.
+ */
+export declare const LEGACY_SKILL_COLLECTION = "pi-harness-skills";
+/** The model of the legacy collection. */
+export declare const LEGACY_SKILL_COLLECTION_MODEL = "sentence-transformers/all-MiniLM-L6-v2";
+/** The vector size of the legacy collection. */
+export declare const LEGACY_SKILL_COLLECTION_DIMENSIONS = 384;
+/** The schema a skill collection is expected to have. */
+export interface SkillVectorSchema {
+    /** The vector size. */
+    dimensions: number;
+    /** The distance metric. */
+    distance: string;
+    /** The embedding model, when it is known. */
+    model?: string;
+}
+/**
+ * Why the collection does not match the expected schema - or null when it
+ * does.
+ *
+ * The message names the numbers, so the reader can tell WHICH schema the
+ * collection was built with.
+ */
+export declare function describeSkillSchemaMismatch(actual: {
+    dimensions?: number;
+    distance?: string;
+}, expected: SkillVectorSchema): string | null;
+//# sourceMappingURL=vector-schema.d.ts.map

package/packages/skills/dist/vector-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-schema.d.ts","sourceRoot":"","sources":["../src/vector-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,gCAAgC,CAAC;AAE9D;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,sBAAsB,CAAC;AAE3D,0CAA0C;AAC1C,eAAO,MAAM,6BAA6B,2CAA2C,CAAC;AAEtF,gDAAgD;AAChD,eAAO,MAAM,kCAAkC,MAAM,CAAC;AAEtD,yDAAyD;AACzD,MAAM,WAAW,iBAAiB;IACjC,uBAAuB;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAC1C,MAAM,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,EAClD,QAAQ,EAAE,iBAAiB,GACzB,MAAM,GAAG,IAAI,CASf"}

package/packages/skills/dist/vector-schema.js

@@ -0,0 +1,55 @@
+/**
+ * The vector schema of the skill collection.
+ *
+ * A Qdrant collection holds vectors of exactly ONE size. Two different
+ * embedding models produce two different vector sizes, so they must never
+ * write into the same collection: the second writer is rejected by the
+ * server with a dimension error, and the data of the first writer becomes
+ * unsearchable by the second.
+ *
+ * The collection name carries the model and a version, so a change of the
+ * model leads to a NEW collection instead of a silent mix of two vector
+ * spaces.
+ *
+ * The model itself lives in the Qdrant package (the embedder owns it). This
+ * module owns the collection - that is a decision of the skills domain, not
+ * of the vector store.
+ */
+/**
+ * The collection the runtime indexes into and searches.
+ *
+ * `QDRANT_COLLECTION` overrides it, so a cluster that already holds a
+ * collection under another name keeps working.
+ */
+export const SKILL_COLLECTION = "pi-harness-skills-openai-v1";
+/**
+ * The collection that was used before the schema was versioned.
+ *
+ * It holds 384-dimensional vectors - the model that
+ * `scripts/sync-to-qdrant.ts` used - and is NOT compatible with the
+ * runtime. It is named here so a mismatch can name the real cause instead
+ * of only the numbers.
+ */
+export const LEGACY_SKILL_COLLECTION = "pi-harness-skills";
+/** The model of the legacy collection. */
+export const LEGACY_SKILL_COLLECTION_MODEL = "sentence-transformers/all-MiniLM-L6-v2";
+/** The vector size of the legacy collection. */
+export const LEGACY_SKILL_COLLECTION_DIMENSIONS = 384;
+/**
+ * Why the collection does not match the expected schema - or null when it
+ * does.
+ *
+ * The message names the numbers, so the reader can tell WHICH schema the
+ * collection was built with.
+ */
+export function describeSkillSchemaMismatch(actual, expected) {
+    if (actual.dimensions !== undefined && actual.dimensions !== expected.dimensions) {
+        const model = expected.model ? ` (${expected.model})` : "";
+        return `the collection holds ${actual.dimensions}-dimensional vectors, the runtime embeds with ${expected.dimensions}${model}`;
+    }
+    if (actual.distance !== undefined && actual.distance !== expected.distance) {
+        return `the collection uses the ${actual.distance} distance, the runtime expects ${expected.distance}`;
+    }
+    return null;
+}
+//# sourceMappingURL=vector-schema.js.map

package/packages/skills/dist/vector-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-schema.js","sourceRoot":"","sources":["../src/vector-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,6BAA6B,CAAC;AAE9D;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,mBAAmB,CAAC;AAE3D,0CAA0C;AAC1C,MAAM,CAAC,MAAM,6BAA6B,GAAG,wCAAwC,CAAC;AAEtF,gDAAgD;AAChD,MAAM,CAAC,MAAM,kCAAkC,GAAG,GAAG,CAAC;AAYtD;;;;;;GAMG;AACH,MAAM,UAAU,2BAA2B,CAC1C,MAAkD,EAClD,QAA2B;IAE3B,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS,IAAI,MAAM,CAAC,UAAU,KAAK,QAAQ,CAAC,UAAU,EAAE,CAAC;QAClF,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3D,OAAO,wBAAwB,MAAM,CAAC,UAAU,iDAAiD,QAAQ,CAAC,UAAU,GAAG,KAAK,EAAE,CAAC;IAChI,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,SAAS,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,CAAC,QAAQ,EAAE,CAAC;QAC5E,OAAO,2BAA2B,MAAM,CAAC,QAAQ,kCAAkC,QAAQ,CAAC,QAAQ,EAAE,CAAC;IACxG,CAAC;IACD,OAAO,IAAI,CAAC;AACb,CAAC"}

package/packages/skills/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/skills",
-  "version": "1.1.411",
+  "version": "1.1.413",
   "description": "File-based skill system with pi.dev compatibility and Hermes self-improvement",
   "type": "module",
   "main": "src/index.ts",

package/packages/skills/src/index.ts

@@ -13,6 +13,8 @@ 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";
@@ -22,6 +24,18 @@ import type { SkillsConfig, ScanResult, ScanOptions } from "./types.js";
 import { scanForSkillsSync } from "./scanner.js";
 import { getGlobalSkillRegistry, 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
  *
@@ -36,7 +50,7 @@ export function initSkills(
       registry?: SkillRegistry;
     }
   >
-): ScanResult {
+): SkillsInitResult {
   const registry = config?.registry ?? getGlobalSkillRegistry();
 
   // Scan for skills
@@ -58,7 +72,7 @@ export function initSkills(
   // Hint: if ~/.pi-harness-runtime/skills/ is empty, suggest the sync script
   checkEmptySkillsDir();
 
-  return result;
+  return { ...result, registry };
 }
 
 /** Show sync hint if the harness skills dir is empty. */