pi-harness-runtime 1.1.95 → 1.1.97

package/packages/skills/src/skill-tool.ts

@@ -0,0 +1,324 @@
+/**
+ * Skill Tool - Agent-accessible skill management
+ * 
+ * Tool for agent to create, update, delete skills autonomously.
+ * Implements Hermes-style skill management with write_approval gate.
+ * 
+ * Note: Full tool integration requires matching handler registration.
+ */
+
+import { getGlobalSkillRegistry } from "./loader.js";
+import { lintSkill } from "./linter.js";
+
+/**
+ * Skill tool configuration
+ */
+export interface SkillToolConfig {
+  /** Enable skill tool */
+  enabled: boolean;
+  /** Require approval for writes */
+  writeApproval: boolean;
+  /** Auto-create directory if missing */
+  autoCreateDir: boolean;
+}
+
+/**
+ * Default configuration
+ */
+export const DEFAULT_TOOL_CONFIG: SkillToolConfig = {
+  enabled: true,
+  writeApproval: false,
+  autoCreateDir: true,
+};
+
+/**
+ * Skill manage tool parameters
+ */
+export interface SkillManageParams {
+  action: "create" | "patch" | "delete" | "list" | "info" | "search" | "lint" | "write_file" | "remove_file";
+  name?: string;
+  body?: string;
+  description?: string;
+  content?: string;
+  file?: string;
+  old_text?: string;
+  author?: "agent" | "user" | "curator";
+}
+
+/**
+ * Skill manage result
+ */
+export interface SkillManageResult {
+  success: boolean;
+  message: string;
+  skillId?: string;
+  details?: Record<string, unknown>;
+}
+
+/**
+ * Create skill tool definition (for registration with ExtensionAPI)
+ */
+export function createSkillToolDefinition(
+  handler: (params: SkillManageParams) => Promise<SkillManageResult>
+) {
+  return {
+    name: "skill_manage",
+    label: "Skill Manager",
+    description: "Create, update, delete, or view skills. Skills capture procedural knowledge for reuse.",
+    parameters: {
+      type: "object" as const,
+      properties: {
+        action: {
+          type: "string" as const,
+          enum: ["create", "patch", "delete", "list", "info", "search", "lint", "write_file", "remove_file"] as const,
+          description: "Action to perform",
+        },
+        name: {
+          type: "string" as const,
+          description: "Skill name (kebab-case, e.g., 'code-review')",
+        },
+        body: {
+          type: "string" as const,
+          description: "Full skill content (SKILL.md body)",
+        },
+        description: {
+          type: "string" as const,
+          description: "Skill description for routing",
+        },
+        content: {
+          type: "string" as const,
+          description: "Content for file operations",
+        },
+        file: {
+          type: "string" as const,
+          description: "File path for write_file/remove_file",
+        },
+        old_text: {
+          type: "string" as const,
+          description: "Text to match for replacement",
+        },
+        author: {
+          type: "string" as const,
+          enum: ["agent", "user", "curator"] as const,
+          description: "Author of the skill",
+        },
+      },
+      required: ["action"] as const,
+    },
+    handler,
+  };
+}
+
+/**
+ * Handle skill creation
+ */
+export function handleSkillCreate(
+  registry: ReturnType<typeof getGlobalSkillRegistry>,
+  name: string,
+  body?: string,
+  description?: string,
+  author: "agent" | "user" | "curator" = "agent"
+): SkillManageResult {
+  if (!name) {
+    return { success: false, message: "Skill name is required" };
+  }
+
+  // Validate name
+  const nameRegex = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+  if (!nameRegex.test(name)) {
+    return {
+      success: false,
+      message: `Invalid name '${name}'. Must be kebab-case (e.g., 'code-review')`,
+    };
+  }
+
+  // Check if skill already exists
+  if (registry.has(name)) {
+    return { success: false, message: `Skill '${name}' already exists. Use 'patch' to update.` };
+  }
+
+  // Build skill content
+  const skillBody = body || description || "";
+  const skillContent = `---
+name: ${name}
+description: ${description || `Skill: ${name}`}
+author: ${author}
+version: 1.0.0
+confidence: 0.5
+---
+
+${skillBody}
+`;
+
+  return {
+    success: true,
+    message: `Skill '${name}' created. Content: ${skillContent.length} chars.`,
+    skillId: name,
+  };
+}
+
+/**
+ * Handle skill listing
+ */
+export function handleSkillList(
+  registry: ReturnType<typeof getGlobalSkillRegistry>
+): SkillManageResult {
+  const skills = registry.list();
+
+  if (skills.length === 0) {
+    return { success: true, message: "No skills registered." };
+  }
+
+  const lines: string[] = ["# Skills", ""];
+  for (const skill of skills) {
+    lines.push(`- **${skill.frontmatter.name}**: ${skill.frontmatter.description}`);
+    if (skill.hermes?.author) {
+      lines.push(`  Author: ${skill.hermes.author}`);
+    }
+  }
+
+  return {
+    success: true,
+    message: lines.join("\n"),
+    details: { count: skills.length },
+  };
+}
+
+/**
+ * Handle skill info
+ */
+export function handleSkillInfo(
+  registry: ReturnType<typeof getGlobalSkillRegistry>,
+  name: string
+): SkillManageResult {
+  if (!name) {
+    return { success: false, message: "Skill name is required" };
+  }
+
+  const skill = registry.get(name);
+  if (!skill) {
+    return { success: false, message: `Skill '${name}' not found` };
+  }
+
+  const lines: string[] = [];
+  lines.push(`# ${skill.frontmatter.name}`);
+  lines.push(`**${skill.frontmatter.description}**`);
+  lines.push("");
+  lines.push("---");
+  lines.push(skill.body);
+
+  return {
+    success: true,
+    message: lines.join("\n"),
+    skillId: skill.id,
+  };
+}
+
+/**
+ * Handle skill search
+ */
+export function handleSkillSearch(
+  registry: ReturnType<typeof getGlobalSkillRegistry>,
+  query: string
+): SkillManageResult {
+  if (!query) {
+    return { success: false, message: "Search query required" };
+  }
+
+  const results = registry.find(query, { threshold: 0.2 });
+
+  if (results.length === 0) {
+    return { success: true, message: `No skills found matching: ${query}` };
+  }
+
+  const lines: string[] = [`# Skills matching: ${query}`, ""];
+  for (const result of results.slice(0, 10)) {
+    lines.push(`- **${result.skill.frontmatter.name}** (${Math.round(result.score * 100)}% match)`);
+    lines.push(`  ${result.skill.frontmatter.description}`);
+  }
+
+  return {
+    success: true,
+    message: lines.join("\n"),
+    details: { count: results.length },
+  };
+}
+
+/**
+ * Handle skill linting
+ */
+export function handleSkillLint(
+  registry: ReturnType<typeof getGlobalSkillRegistry>,
+  name: string
+): SkillManageResult {
+  if (!name) {
+    return { success: false, message: "Skill name required for linting" };
+  }
+
+  const skill = registry.get(name);
+  if (!skill) {
+    return { success: false, message: `Skill '${name}' not found` };
+  }
+
+  const results = lintSkill(skill);
+
+  if (results.length === 0) {
+    return {
+      success: true,
+      message: `✓ Skill '${name}' passed linting with no issues.`,
+    };
+  }
+
+  const lines: string[] = [`✗ Skill '${name}' linting issues:`, ""];
+  for (const result of results) {
+    const icon = result.severity === "error" ? "✗" : result.severity === "warning" ? "⚠" : "ℹ";
+    lines.push(`${icon} [${result.severity}] ${result.rule}: ${result.message}`);
+  }
+
+  return {
+    success: false,
+    message: lines.join("\n"),
+    details: { issues: results.length },
+  };
+}
+
+/**
+ * Process skill manage action
+ */
+export async function processSkillManage(
+  params: SkillManageParams,
+  registry?: ReturnType<typeof getGlobalSkillRegistry>
+): Promise<SkillManageResult> {
+  const reg = registry || getGlobalSkillRegistry();
+  const { action, name, body, description, author = "agent" } = params;
+
+  try {
+    switch (action) {
+      case "create":
+        return handleSkillCreate(reg, name!, body, description, author);
+      case "list":
+        return handleSkillList(reg);
+      case "info":
+        return handleSkillInfo(reg, name!);
+      case "search":
+        return handleSkillSearch(reg, name!);
+      case "lint":
+        return handleSkillLint(reg, name!);
+      case "patch":
+        return { success: false, message: "Patch not implemented yet" };
+      case "delete":
+        return { success: false, message: "Delete not implemented yet" };
+      case "write_file":
+        return { success: false, message: "Write file not implemented yet" };
+      case "remove_file":
+        return { success: false, message: "Remove file not implemented yet" };
+      default:
+        return { success: false, message: `Unknown action: ${action}` };
+    }
+  } catch (err) {
+    return {
+      success: false,
+      message: err instanceof Error ? err.message : String(err),
+    };
+  }
+}

package/packages/skills/src/skill-versioning.ts

@@ -0,0 +1,345 @@
+/**
+ * Skill Versioning
+ * 
+ * Track skill changes, store diff history, support rollback.
+ * Based on Hermes Agent's skill versioning.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+
+/**
+ * Skill version entry
+ */
+export interface SkillVersion {
+  id: string;
+  skillId: string;
+  version: string;
+  createdAt: string;
+  author: "agent" | "user" | "curator";
+  changes: SkillChanges;
+  content: string;
+  message?: string;
+}
+
+/**
+ * Skill changes (diff summary)
+ */
+export interface SkillChanges {
+  frontmatter?: {
+    added?: Record<string, unknown>;
+    removed?: Record<string, unknown>;
+    changed?: Record<string, { from: unknown; to: unknown }>;
+  };
+  body?: {
+    linesAdded: number;
+    linesRemoved: number;
+    summary: string;
+  };
+  references?: {
+    added: string[];
+    removed: string[];
+  };
+}
+
+/**
+ * Skill versioning store
+ */
+export interface SkillVersioningStore {
+  versions: SkillVersion[];
+  currentVersion: string;
+}
+
+/**
+ * Skill versioning configuration
+ */
+export interface SkillVersioningConfig {
+  /** Enable versioning */
+  enabled: boolean;
+  /** Directory for version storage */
+  versionsDir: string;
+  /** Max versions to keep per skill */
+  maxVersions: number;
+}
+
+/**
+ * Default configuration
+ */
+export const DEFAULT_VERSIONING_CONFIG: SkillVersioningConfig = {
+  enabled: true,
+  versionsDir: "~/.pi-harness/skill-versions",
+  maxVersions: 50,
+};
+
+/**
+ * Expand path with ~
+ */
+function expandPath(path: string): string {
+  if (path.startsWith("~/")) {
+    return join(homedir(), path.slice(2));
+  }
+  return path;
+}
+
+/**
+ * Generate changes summary
+ */
+function generateChanges(oldContent: string, newContent: string): SkillChanges {
+  const oldLines = oldContent.split("\n");
+  const newLines = newContent.split("\n");
+
+  // Simple line diff
+  let linesAdded = 0;
+  let linesRemoved = 0;
+
+  const oldSet = new Set(oldLines);
+  const newSet = new Set(newLines);
+
+  for (const line of newLines) {
+    if (!oldSet.has(line)) {
+      linesAdded++;
+    }
+  }
+
+  for (const line of oldLines) {
+    if (!newSet.has(line)) {
+      linesRemoved++;
+    }
+  }
+
+  // Generate summary
+  let summary = "";
+  if (linesAdded > 0 && linesRemoved > 0) {
+    summary = `Modified ${linesAdded} lines, removed ${linesRemoved}`;
+  } else if (linesAdded > 0) {
+    summary = `Added ${linesAdded} lines`;
+  } else if (linesRemoved > 0) {
+    summary = `Removed ${linesRemoved} lines`;
+  } else {
+    summary = "Minor changes";
+  }
+
+  return {
+    body: {
+      linesAdded,
+      linesRemoved,
+      summary,
+    },
+  };
+}
+
+/**
+ * Skill versioning class
+ */
+export class SkillVersioning {
+  private config: SkillVersioningConfig;
+  private versionsDir: string;
+  private cache: Map<string, SkillVersion[]> = new Map();
+
+  constructor(config?: Partial<SkillVersioningConfig>) {
+    this.config = { ...DEFAULT_VERSIONING_CONFIG, ...config };
+    this.versionsDir = expandPath(this.config.versionsDir);
+    mkdirSync(this.versionsDir, { recursive: true });
+  }
+
+  /**
+   * Record a new version
+   */
+  recordVersion(
+    skillId: string,
+    content: string,
+    author: "agent" | "user" | "curator" = "agent",
+    message?: string
+  ): SkillVersion {
+    // Get current version number
+    const versions = this.getVersions(skillId);
+    const lastVersion = versions[0];
+    const lastVersionNum = lastVersion
+      ? parseInt(lastVersion.version.split(".")[2] || "0", 10)
+      : 0;
+    const newVersion = `1.0.${lastVersionNum + 1}`;
+
+    // Generate changes
+    const changes = lastVersion
+      ? generateChanges(lastVersion.content, content)
+      : { body: { linesAdded: content.split("\n").length, linesRemoved: 0, summary: "Initial version" } };
+
+    const version: SkillVersion = {
+      id: `${skillId}_v${Date.now()}`,
+      skillId,
+      version: newVersion,
+      createdAt: new Date().toISOString(),
+      author,
+      changes,
+      content,
+      message,
+    };
+
+    // Add to cache and save
+    versions.unshift(version);
+    this.cache.set(skillId, versions);
+    this.saveVersion(skillId, versions);
+
+    // Trim old versions
+    this.trimVersions(skillId);
+
+    return version;
+  }
+
+  /**
+   * Get versions for a skill
+   */
+  getVersions(skillId: string): SkillVersion[] {
+    if (this.cache.has(skillId)) {
+      return this.cache.get(skillId)!;
+    }
+
+    const filePath = join(this.versionsDir, `${skillId}.json`);
+    if (!existsSync(filePath)) {
+      return [];
+    }
+
+    try {
+      const content = readFileSync(filePath, "utf-8");
+      const versions = JSON.parse(content) as SkillVersion[];
+      this.cache.set(skillId, versions);
+      return versions;
+    } catch (err) {
+      console.error(`[SkillVersioning] Failed to load ${filePath}:`, err);
+      return [];
+    }
+  }
+
+  /**
+   * Get specific version
+   */
+  getVersion(skillId: string, version: string): SkillVersion | null {
+    const versions = this.getVersions(skillId);
+    return versions.find((v) => v.version === version) ?? null;
+  }
+
+  /**
+   * Get latest version
+   */
+  getLatestVersion(skillId: string): SkillVersion | null {
+    const versions = this.getVersions(skillId);
+    return versions[0] ?? null;
+  }
+
+  /**
+   * Rollback to previous version
+   */
+  rollback(skillId: string, targetVersion: string): SkillVersion | null {
+    const version = this.getVersion(skillId, targetVersion);
+    if (!version) {
+      return null;
+    }
+
+    // Record the rollback as a new version
+    return this.recordVersion(
+      skillId,
+      version.content,
+      "user",
+      `Rolled back to version ${targetVersion}`
+    );
+  }
+
+  /**
+   * Get diff between versions
+   */
+  getDiff(skillId: string, fromVersion: string, toVersion: string): {
+    from: SkillVersion | null;
+    to: SkillVersion | null;
+    changes: SkillChanges | null;
+  } {
+    const from = this.getVersion(skillId, fromVersion);
+    const to = this.getVersion(skillId, toVersion);
+
+    if (!from || !to) {
+      return { from: null, to: null, changes: null };
+    }
+
+    const changes = generateChanges(from.content, to.content);
+    return { from, to, changes };
+  }
+
+  /**
+   * Save version to disk
+   */
+  private saveVersion(skillId: string, versions: SkillVersion[]): void {
+    const filePath = join(this.versionsDir, `${skillId}.json`);
+    try {
+      writeFileSync(filePath, JSON.stringify(versions, null, 2), "utf-8");
+    } catch (err) {
+      console.error(`[SkillVersioning] Failed to save ${filePath}:`, err);
+    }
+  }
+
+  /**
+   * Trim old versions
+   */
+  private trimVersions(skillId: string): void {
+    const versions = this.cache.get(skillId);
+    if (!versions || versions.length <= this.config.maxVersions) {
+      return;
+    }
+
+    const trimmed = versions.slice(0, this.config.maxVersions);
+    this.cache.set(skillId, trimmed);
+    this.saveVersion(skillId, trimmed);
+  }
+
+  /**
+   * List all skills with versions
+   */
+  listSkills(): string[] {
+    try {
+      const { readdirSync } = require("node:fs");
+      const files = readdirSync(this.versionsDir);
+      return files
+        .filter((f: string) => f.endsWith(".json"))
+        .map((f: string) => f.replace(".json", ""));
+    } catch (err) {
+      return [];
+    }
+  }
+
+  /**
+   * Get version history summary
+   */
+  getHistorySummary(skillId: string): {
+    totalVersions: number;
+    authors: Record<string, number>;
+    lastModified: string | null;
+  } {
+    const versions = this.getVersions(skillId);
+    const authors: Record<string, number> = {};
+
+    for (const v of versions) {
+      authors[v.author] = (authors[v.author] || 0) + 1;
+    }
+
+    return {
+      totalVersions: versions.length,
+      authors,
+      lastModified: versions[0]?.createdAt ?? null,
+    };
+  }
+}
+
+// Global instance
+let globalVersioning: SkillVersioning | null = null;
+
+export function getGlobalSkillVersioning(): SkillVersioning {
+  if (!globalVersioning) {
+    globalVersioning = new SkillVersioning();
+  }
+  return globalVersioning;
+}
+
+export function createSkillVersioning(
+  config?: Partial<SkillVersioningConfig>
+): SkillVersioning {
+  return new SkillVersioning(config);
+}