pi-harness-runtime 0.5.0 → 0.6.3-beta.13

package/packages/skill-registry/src/defaults.ts

@@ -0,0 +1,92 @@
+/**
+ * Default Skill Definitions (RFC-0052)
+ */
+
+import type { Skill } from "./types.js";
+import { createKeywordTrigger, createIntentTrigger } from "./matching.js";
+
+/**
+ * Introspection skill - lists all registered skills
+ */
+const introspectSkill: Skill = {
+	id: "skill-registry-introspect",
+	name: "Introspect Skill Registry",
+	description: "Lists all registered skills and their triggers",
+	version: "1.0.0",
+	trigger: createKeywordTrigger(["list skills", "show skills", "what skills"]),
+	handler: async (context) => {
+		const registry = context.metadata.registry as
+			| { list(): Skill[] }
+			| undefined;
+		if (!registry || typeof registry.list !== "function") {
+			return { success: false, error: "Registry not available in context" };
+		}
+		const skills = registry.list();
+		const summary = skills
+			.map((s) => `- ${s.name} (${s.id}): ${s.description}`)
+			.join("\n");
+		return {
+			success: true,
+			output: `Registered Skills:\n${summary}`,
+			metadata: { count: skills.length },
+		};
+	},
+	metadata: {
+		tags: ["meta", "debug", "introspection"],
+		examples: ["list skills", "show me all skills"],
+	},
+};
+
+/**
+ * Help skill - provides help about available commands
+ */
+const helpSkill: Skill = {
+	id: "skill-help",
+	name: "Help Assistant",
+	description: "Provides help and guidance for using the runtime",
+	version: "1.0.0",
+	trigger: createKeywordTrigger(["help", "how to", "what is"]),
+	handler: async () => {
+		const taskDescription = "";
+		return {
+			success: true,
+			output: `Available commands and skills:\n- Type "list skills" to see all skills\n- Use standard agent commands for file operations\n- Ask for help on specific topics`,
+			metadata: { context: taskDescription },
+		};
+	},
+	metadata: {
+		tags: ["help", "documentation"],
+		examples: ["help me", "how do I", "what is this"],
+	},
+};
+
+/**
+ * Status skill - shows runtime status
+ */
+const statusSkill: Skill = {
+	id: "skill-status",
+	name: "Runtime Status",
+	description: "Shows current runtime status and statistics",
+	version: "1.0.0",
+	trigger: createIntentTrigger(["status", "health", "stats", "statistics"]),
+	handler: async () => {
+		return {
+			success: true,
+			output: "Runtime Status: Active\nAll systems operational",
+			metadata: {
+				timestamp: Date.now(),
+				uptime: Math.round(Date.now() / 1000),
+			},
+		};
+	},
+	metadata: {
+		tags: ["status", "monitoring"],
+		examples: ["check status", "show stats"],
+	},
+};
+
+export const DEFAULT_SKILLS: Skill[] = [
+	introspectSkill,
+	helpSkill,
+	statusSkill,
+];

package/packages/skill-registry/src/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Skill Registry Package (RFC-0052)
+ *
+ * A centralized registry for dynamic skill discovery and invocation.
+ *
+ * @example
+ * ```typescript
+ * import { createSkillRegistry } from "@pi-harness/skill-registry";
+ *
+ * const registry = createSkillRegistry();
+ *
+ * // Find skills by trigger
+ * const skills = registry.find({ type: "keyword", value: "help" });
+ *
+ * // Invoke a skill
+ * const result = await registry.invoke("skill-help", context);
+ * ```
+ */
+
+// Types
+export type {
+	TriggerType,
+	SkillTrigger,
+	ToolCall,
+	SkillContext,
+	SkillResult,
+	SkillHandler,
+	SkillMetadata,
+	Skill,
+	SkillRegistry,
+	SkillRegistryEvent,
+} from "./types.js";
+
+// Registry
+export { InMemorySkillRegistry, createSkillRegistry } from "./registry.js";
+
+// Defaults
+export { DEFAULT_SKILLS } from "./defaults.js";
+
+// Matching utilities
+export {
+	matchTrigger,
+	findBestMatch,
+	findAllMatches,
+	createKeywordTrigger,
+	createIntentTrigger,
+	createPatternTrigger,
+} from "./matching.js";

package/packages/skill-registry/src/matching.ts

@@ -0,0 +1,118 @@
+/**
+ * Skill Matching Functions (RFC-0052)
+ */
+
+import type { Skill, SkillTrigger } from "./types.js";
+
+/**
+ * Match a skill trigger against input
+ */
+export function matchTrigger(skill: Skill, input: string): number {
+	const { trigger } = skill;
+	const value = trigger.value;
+
+	switch (trigger.type) {
+		case "keyword": {
+			const keywords = typeof value === "string" ? value.split(" ") : value;
+			const inputLower = input.toLowerCase();
+			const matchedCount = keywords.filter((k) => {
+				const kw = k.toLowerCase();
+				// Match if input contains keyword OR keyword contains input
+				return inputLower.includes(kw) || kw.includes(inputLower);
+			}).length;
+			return matchedCount / keywords.length; // normalize to 0-1
+		}
+
+		case "pattern": {
+			try {
+				let regex: RegExp;
+				if (typeof value === "string") {
+					regex = new RegExp(value);
+				} else {
+					regex = new RegExp(value.join("|"));
+				}
+				return regex.test(input) ? 1 : 0;
+			} catch {
+				return 0;
+			}
+		}
+
+		case "intent": {
+			const intents = typeof value === "string" ? [value] : value;
+			const matched = intents.some((i) =>
+				input.toLowerCase().includes(i.toLowerCase()),
+			);
+			return matched ? 1 : 0;
+		}
+
+		case "tool_request": {
+			return input.toLowerCase().includes("tool") ? 1 : 0;
+		}
+
+		default:
+			return 0;
+	}
+}
+
+/**
+ * Find best matching skill
+ */
+export function findBestMatch(
+	skills: Skill[],
+	input: string,
+	minConfidence = 0.5,
+): Skill | undefined {
+	const matches = skills
+		.map((skill) => ({
+			skill,
+			score: matchTrigger(skill, input),
+		}))
+		.filter((m) => m.score >= (m.skill.trigger.confidence ?? minConfidence))
+		.sort((a, b) => b.score - a.score);
+
+	return matches[0]?.skill;
+}
+
+/**
+ * Find all matching skills above threshold
+ */
+export function findAllMatches(
+	skills: Skill[],
+	input: string,
+	minConfidence = 0.5,
+): Array<{ skill: Skill; score: number }> {
+	return skills
+		.map((skill) => ({
+			skill,
+			score: matchTrigger(skill, input),
+		}))
+		.filter((m) => m.score >= (m.skill.trigger.confidence ?? minConfidence))
+		.sort((a, b) => b.score - a.score);
+}
+
+/**
+ * Create a skill trigger from common patterns
+ */
+export function createKeywordTrigger(keywords: string[]): SkillTrigger {
+	return {
+		type: "keyword",
+		value: keywords,
+		confidence: 0.3, // Lower threshold for partial matches
+	};
+}
+
+export function createIntentTrigger(intents: string[]): SkillTrigger {
+	return {
+		type: "intent",
+		value: intents,
+		confidence: 0.3,
+	};
+}
+
+export function createPatternTrigger(pattern: string): SkillTrigger {
+	return {
+		type: "pattern",
+		value: pattern,
+		confidence: 0.7,
+	};
+}

package/packages/skill-registry/src/registry.ts

@@ -0,0 +1,176 @@
+/**
+ * Skill Registry Implementation (RFC-0052)
+ */
+
+import type {
+	Skill,
+	SkillContext,
+	SkillResult,
+	SkillRegistryEvent,
+	TriggerType,
+} from "./types.js";
+import { DEFAULT_SKILLS } from "./defaults.js";
+import { findBestMatch, findAllMatches } from "./matching.js";
+
+type EventHandler = (event: SkillRegistryEvent) => void;
+
+/**
+ * In-memory skill registry with event emission
+ */
+export class InMemorySkillRegistry {
+	private skills: Map<string, Skill> = new Map();
+	private eventHandlers: Set<EventHandler> = new Set();
+
+	constructor(loadDefaults = true) {
+		if (loadDefaults) {
+			this.loadDefaults();
+		}
+	}
+
+	/**
+	 * Load default skills
+	 */
+	private loadDefaults(): void {
+		for (const skill of DEFAULT_SKILLS) {
+			this.register(skill);
+		}
+	}
+
+	/**
+	 * Register a skill
+	 */
+	register(skill: Skill): void {
+		if (skill.metadata.deprecated) {
+			return; // Don't register deprecated skills
+		}
+		this.skills.set(skill.id, skill);
+		this.emit({
+			type: "skill.registered",
+			skillId: skill.id,
+			name: skill.name,
+		});
+	}
+
+	/**
+	 * Unregister a skill
+	 */
+	unregister(skillId: string): void {
+		if (this.skills.has(skillId)) {
+			this.skills.delete(skillId);
+			this.emit({
+				type: "skill.unregistered",
+				skillId,
+			});
+		}
+	}
+
+	/**
+	 * Get a skill by ID
+	 */
+	get(skillId: string): Skill | undefined {
+		return this.skills.get(skillId);
+	}
+
+	/**
+	 * List all skills
+	 */
+	list(): Skill[] {
+		return Array.from(this.skills.values());
+	}
+
+	/**
+	 * Find skills matching a trigger
+	 */
+	find(trigger: { type: TriggerType; value: string }): Skill[] {
+		const all = this.list();
+		const input = trigger.value;
+
+		// Filter by type first
+		const matchingType = all.filter((s) => s.trigger.type === trigger.type);
+
+		// Then score
+		const scored = findAllMatches(matchingType, input);
+		return scored.map((s) => s.skill);
+	}
+
+	/**
+	 * Invoke a skill by ID
+	 */
+	async invoke(skillId: string, context: SkillContext): Promise<SkillResult> {
+		const skill = this.skills.get(skillId);
+		if (!skill) {
+			return { success: false, error: `Skill not found: ${skillId}` };
+		}
+
+		const startTime = Date.now();
+		try {
+			const result = await skill.handler(context);
+			this.emit({
+				type: "skill.invoked",
+				skillId,
+				success: result.success,
+				duration: Date.now() - startTime,
+			});
+			return result;
+		} catch (err) {
+			const error = err instanceof Error ? err.message : String(err);
+			this.emit({
+				type: "skill.error",
+				skillId,
+				error,
+			});
+			return { success: false, error };
+		}
+	}
+
+	/**
+	 * Invoke the best matching skill for a trigger
+	 */
+	async invokeBestMatch(
+		trigger: { type: TriggerType; value: string },
+		context: SkillContext,
+	): Promise<SkillResult> {
+		const all = this.list();
+		const matching = all.filter((s) => s.trigger.type === trigger.type);
+		const bestMatch = findBestMatch(matching, trigger.value);
+
+		if (!bestMatch) {
+			return {
+				success: false,
+				error: "No matching skill found",
+			};
+		}
+
+		return this.invoke(bestMatch.id, context);
+	}
+
+	/**
+	 * Subscribe to events
+	 */
+	onEvent(handler: EventHandler): () => void {
+		this.eventHandlers.add(handler);
+		return () => this.eventHandlers.delete(handler);
+	}
+
+	/**
+	 * Emit an event
+	 */
+	private emit(event: SkillRegistryEvent): void {
+		for (const handler of this.eventHandlers) {
+			try {
+				handler(event);
+			} catch {
+				// Ignore handler errors
+			}
+		}
+	}
+}
+
+/**
+ * Create a new skill registry
+ */
+export function createSkillRegistry(
+	loadDefaults = true,
+): InMemorySkillRegistry {
+	return new InMemorySkillRegistry(loadDefaults);
+}

package/packages/skill-registry/src/types.ts

@@ -0,0 +1,97 @@
+/**
+ * Skill Registry Types (RFC-0052)
+ */
+
+// ─── Trigger Types ─────────────────────────────────────────────────────
+
+export type TriggerType = "keyword" | "pattern" | "intent" | "tool_request";
+
+export interface SkillTrigger {
+	type: TriggerType;
+	value: string | string[];
+	confidence?: number;
+}
+
+// ─── Skill Types ──────────────────────────────────────────────────────
+
+export interface ToolCall {
+	name: string;
+	arguments: Record<string, unknown>;
+}
+
+export interface SkillContext {
+	messages: Array<{
+		role: "user" | "assistant" | "system";
+		content: string;
+	}>;
+	task?: {
+		id: string;
+		title: string;
+		description: string;
+	};
+	requirement?: {
+		id: string;
+		description: string;
+	};
+	tools: Array<{
+		name: string;
+		description?: string;
+	}>;
+	metadata: Record<string, unknown>;
+}
+
+export interface SkillResult {
+	success: boolean;
+	output?: string;
+	toolCalls?: ToolCall[];
+	error?: string;
+	metadata?: Record<string, unknown>;
+}
+
+export type SkillHandler = (context: SkillContext) => Promise<SkillResult>;
+
+export interface SkillMetadata {
+	author?: string;
+	tags: string[];
+	examples?: string[];
+	requiresCapabilities?: string[];
+	deprecated?: boolean;
+}
+
+export interface Skill {
+	id: string;
+	name: string;
+	description: string;
+	version: string;
+	trigger: SkillTrigger;
+	handler: SkillHandler;
+	metadata: SkillMetadata;
+}
+
+// ─── Registry Types ────────────────────────────────────────────────────
+
+export interface SkillRegistry {
+	register(skill: Skill): void;
+	unregister(skillId: string): void;
+	get(skillId: string): Skill | undefined;
+	list(): Skill[];
+	find(trigger: { type: TriggerType; value: string }): Skill[];
+	invoke(skillId: string, context: SkillContext): Promise<SkillResult>;
+	invokeBestMatch(
+		trigger: { type: TriggerType; value: string },
+		context: SkillContext,
+	): Promise<SkillResult>;
+}
+
+// ─── Event Types ─────────────────────────────────────────────────────
+
+export type SkillRegistryEvent =
+	| { type: "skill.registered"; skillId: string; name: string }
+	| { type: "skill.unregistered"; skillId: string }
+	| {
+			type: "skill.invoked";
+			skillId: string;
+			success: boolean;
+			duration: number;
+	  }
+	| { type: "skill.error"; skillId: string; error: string };