pi-hermes-memory 0.7.9 → 0.7.11

package/src/tools/skill-tool.ts

@@ -9,6 +9,82 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import { SkillStore } from "../store/skill-store.js";
 import { SKILL_TOOL_DESCRIPTION } from "../constants.js";
 
+function normalizeTextList(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value
+    .filter((item): item is string => typeof item === "string")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function formatOrderedList(items: string[]): string {
+  return items.map((item, index) => `${index + 1}. ${item}`).join("\n");
+}
+
+function formatBulletList(items: string[], fallback: string): string {
+  if (items.length === 0) return `- ${fallback}`;
+  return items.map((item) => `- ${item}`).join("\n");
+}
+
+function buildStructuredSkillBody(
+  whenToUse: string,
+  procedureSteps: string[],
+  pitfalls: string[],
+  verificationSteps: string[],
+): string {
+  return [
+    "## When to Use",
+    whenToUse,
+    "",
+    "## Procedure",
+    formatOrderedList(procedureSteps),
+    "",
+    "## Pitfalls",
+    formatBulletList(pitfalls, "No notable pitfalls recorded yet."),
+    "",
+    "## Verification",
+    formatOrderedList(verificationSteps),
+  ].join("\n");
+}
+
+const SKILL_ID_PARAM = Type.String({
+  description: "Stable skill id for view/patch/update/delete. e.g., 'global:debug-typescript-errors' or 'project:my-repo:release-app'. Legacy alias 'edit' also accepts this field.",
+});
+
+const SKILL_TOOL_PARAMETERS = Type.Object({
+  action: StringEnum(["create", "view", "patch", "update", "edit", "delete"] as const, {
+    description: "The skill action to perform.",
+  }),
+  name: Type.Optional(Type.String({
+    description: "Skill name for create. e.g., 'debug-typescript-errors'.",
+  })),
+  skill_id: Type.Optional(SKILL_ID_PARAM),
+  description: Type.Optional(Type.String({
+    description: "One-line description of when to use this skill. Required for create; optional for update/edit.",
+  })),
+  scope: Type.Optional(StringEnum(["global", "project"] as const, {
+    description: "Required for create. Use 'global' for portable procedures and 'project' for repo-specific workflows.",
+  })),
+  section: Type.Optional(Type.String({
+    description: "Required for patch. Section header to patch. e.g., 'Procedure', 'Pitfalls'.",
+  })),
+  content: Type.Optional(Type.String({
+    description: "Raw markdown body for create/update/edit, or new section content for patch. For create/update/edit you can provide this or the structured fields below.",
+  })),
+  when_to_use: Type.Optional(Type.String({
+    description: "Structured create/update/edit field. Explain when this skill should be used and where its boundaries are.",
+  })),
+  procedure_steps: Type.Optional(Type.Array(Type.String(), {
+    description: "Structured create/update/edit field. Ordered concrete steps for the workflow.",
+  })),
+  pitfalls: Type.Optional(Type.Array(Type.String(), {
+    description: "Structured create/update/edit field. Optional common mistakes, caveats, or failure modes to avoid.",
+  })),
+  verification_steps: Type.Optional(Type.Array(Type.String(), {
+    description: "Structured create/update/edit field. Concrete checks that confirm the workflow succeeded.",
+  })),
+}, { additionalProperties: false });
+
 export function registerSkillTool(pi: ExtensionAPI, store: SkillStore): void {
   pi.registerTool({
     name: "skill",
@@ -17,33 +93,67 @@ export function registerSkillTool(pi: ExtensionAPI, store: SkillStore): void {
     promptSnippet: "Save or manage reusable procedures and patterns",
     promptGuidelines: [
       "Use the skill tool after completing complex tasks that required trial and error or multiple tool calls.",
-      "Use 'create' to save a new reusable procedure, 'patch' to update a section of an existing skill by skill_id.",
-      "Choose scope='global' for transferable procedures and scope='project' when the workflow depends on this repo's paths, scripts, conventions, or deploy steps.",
+      "Use 'create' to save a new reusable procedure, 'patch' to update a section of an existing skill by skill_id, and 'update' for a full rewrite.",
+      "Scope is required on create: choose scope='global' for transferable procedures and scope='project' when the workflow depends on this repo's paths, scripts, conventions, or deploy steps.",
+      "Prefer structured fields for create/update: when_to_use, procedure_steps, pitfalls, and verification_steps. The tool will render valid SKILL.md sections for you.",
+      "Use 'view' before patching or updating when you need to inspect an existing skill.",
       "Do NOT use skills for temporary task state — only for durable, reusable procedures.",
     ],
-    parameters: Type.Object({
-      action: StringEnum(["create", "view", "patch", "edit", "delete"] as const),
-      name: Type.Optional(
-        Type.String({ description: "Skill name (for create). e.g., 'debug-typescript-errors'" })
-      ),
-      skill_id: Type.Optional(
-        Type.String({ description: "Stable skill id for view/patch/edit/delete. e.g., 'global:debug-typescript-errors' or 'project:my-repo:release-app'" })
-      ),
-      description: Type.Optional(
-        Type.String({ description: "One-line description of when to use this skill (for create/edit)" })
-      ),
-      scope: Type.Optional(
-        StringEnum(["global", "project"] as const, { description: "Optional creation scope. Omit to let the extension classify it automatically." })
-      ),
-      section: Type.Optional(
-        Type.String({ description: "Section header to patch (for patch action). e.g., 'Procedure', 'Pitfalls'" })
-      ),
-      content: Type.Optional(
-        Type.String({ description: "Body content for create, new section content for patch, or new body for edit" })
-      ),
-    }),
+    parameters: SKILL_TOOL_PARAMETERS,
     async execute(toolCallId, params, signal, onUpdate, ctx) {
-      const { action, name, skill_id, description, scope, section, content } = params;
+      const skillParams = params as {
+        action: "create" | "view" | "patch" | "update" | "edit" | "delete";
+        name?: string;
+        skill_id?: string;
+        description?: string;
+        scope?: "global" | "project";
+        section?: string;
+        content?: string;
+        when_to_use?: string;
+        procedure_steps?: unknown;
+        pitfalls?: unknown;
+        verification_steps?: unknown;
+      };
+      const {
+        action,
+        name,
+        skill_id,
+        description,
+        scope,
+        section,
+        content,
+        when_to_use,
+        procedure_steps,
+        pitfalls,
+        verification_steps,
+      } = skillParams;
+
+      const whenToUse = typeof when_to_use === "string" ? when_to_use.trim() : "";
+      const procedureSteps = normalizeTextList(procedure_steps);
+      const pitfallItems = normalizeTextList(pitfalls);
+      const verificationSteps = normalizeTextList(verification_steps);
+      const hasStructuredBody = Boolean(whenToUse) || procedureSteps.length > 0 || pitfallItems.length > 0 || verificationSteps.length > 0;
+
+      const buildBodyOrError = () => {
+        if (content?.trim()) return { body: content.trim() };
+        if (!hasStructuredBody) {
+          return {
+            error: "Either content or structured fields are required. Prefer when_to_use, procedure_steps, pitfalls, and verification_steps for create/update.",
+          };
+        }
+        if (!whenToUse) {
+          return { error: "when_to_use is required when content is omitted." };
+        }
+        if (procedureSteps.length === 0) {
+          return { error: "procedure_steps is required when content is omitted." };
+        }
+        if (verificationSteps.length === 0) {
+          return { error: "verification_steps is required when content is omitted." };
+        }
+        return {
+          body: buildStructuredSkillBody(whenToUse, procedureSteps, pitfallItems, verificationSteps),
+        };
+      };
 
       let result;
       switch (action) {
@@ -60,13 +170,20 @@ export function registerSkillTool(pi: ExtensionAPI, store: SkillStore): void {
               details: {},
             };
           }
-          if (!content) {
+          const createBodyResult = buildBodyOrError();
+          if (!createBodyResult.body) {
             return {
-              content: [{ type: "text", text: JSON.stringify({ success: false, error: "content (skill body) is required for 'create' action." }) }],
+              content: [{ type: "text", text: JSON.stringify({ success: false, error: createBodyResult.error }) }],
               details: {},
             };
           }
-          result = await store.create(name, description, content, scope);
+          if (!scope) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ success: false, error: "scope is required for 'create' action. Use 'global' or 'project'." }) }],
+              details: {},
+            };
+          }
+          result = await store.create(name, description, createBodyResult.body, scope);
           break;
 
         case "view":
@@ -109,15 +226,33 @@ export function registerSkillTool(pi: ExtensionAPI, store: SkillStore): void {
           result = await store.patch(skill_id, section, content);
           break;
 
-        case "edit":
+        case "update":
+        case "edit": {
+          const updateActionLabel = action === "edit" ? "edit" : "update";
           if (!skill_id) {
             return {
-              content: [{ type: "text", text: JSON.stringify({ success: false, error: "skill_id is required for 'edit' action." }) }],
+              content: [{ type: "text", text: JSON.stringify({ success: false, error: `skill_id is required for '${updateActionLabel}' action.` }) }],
+              details: {},
+            };
+          }
+          const updateBodyResult = buildBodyOrError();
+          const nextDescription = description?.trim() || "";
+          const nextBody = updateBodyResult.body ?? content?.trim() ?? "";
+          if (!nextDescription && !nextBody) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ success: false, error: `Provide description, content, or structured fields for '${updateActionLabel}'.` }) }],
+              details: {},
+            };
+          }
+          if (hasStructuredBody && !updateBodyResult.body) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ success: false, error: updateBodyResult.error }) }],
               details: {},
             };
           }
-          result = await store.edit(skill_id, description || "", content || "");
+          result = await store.edit(skill_id, nextDescription, nextBody);
           break;
+        }
 
         case "delete":
           if (!skill_id) {
@@ -132,7 +267,7 @@ export function registerSkillTool(pi: ExtensionAPI, store: SkillStore): void {
         default:
           result = {
             success: false,
-            error: `Unknown action '${action}'. Use: create, view, patch, edit, delete`,
+            error: `Unknown action '${action}'. Use: create, view, patch, update, delete`,
           };
       }
 

package/src/types.ts

@@ -126,6 +126,10 @@ export interface SkillIndex {
   displayName?: string;
   /** Short description shown in skill listings */
   description: string;
+  /** ISO date created */
+  created: string;
+  /** ISO date last updated */
+  updated: string;
 }
 
 export interface SkillDocument extends SkillIndex {
@@ -133,10 +137,6 @@ export interface SkillDocument extends SkillIndex {
   body: string;
   /** Version number */
   version: number;
-  /** ISO date created */
-  created: string;
-  /** ISO date last updated */
-  updated: string;
 }
 
 export interface SkillResult {
@@ -149,7 +149,7 @@ export interface SkillResult {
   path?: string;
   conflictType?: "duplicate" | "similar" | "name-collision" | "scope-conflict";
   similarSkillIds?: string[];
-  suggestedAction?: "patch" | "edit" | "rename";
+  suggestedAction?: "patch" | "update" | "rename";
 }
 
 /**

package/src/handlers/skill-auto-trigger.ts

@@ -1,128 +0,0 @@
-/**
- * Skill auto-trigger — after complex tasks (8+ tool calls, 2+ distinct tool types),
- * trigger automatic skill extraction via pi.exec().
- *
- * This implements Hermes' "self-evaluation checkpoint" pattern.
- */
-
-import * as path from "node:path";
-import { fileURLToPath } from "node:url";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { MemoryStore } from "../store/memory-store.js";
-import { SkillStore } from "../store/skill-store.js";
-import { COMBINED_REVIEW_PROMPT, DEFAULT_SKILL_TRIGGER_TOOL_CALLS, ENTRY_DELIMITER } from "../constants.js";
-import type { MemoryConfig } from "../types.js";
-import { getMessageText } from "../types.js";
-
-const proceduralSkillCreatorPath = path.join(
-  path.dirname(fileURLToPath(import.meta.url)),
-  "..",
-  "skills",
-  "procedural-skill-creator",
-);
-
-export function setupSkillAutoTrigger(
-  pi: ExtensionAPI,
-  store: MemoryStore,
-  skillStore: SkillStore,
-  config: MemoryConfig,
-): void {
-  let triggeredThisSession = false;
-
-  // Accumulate tool calls across turns (reset on trigger)
-  let toolCallCount = 0;
-  const toolTypes = new Set<string>();
-
-  pi.on("turn_end", async (event, ctx) => {
-    if (triggeredThisSession) return;
-
-    // Count tool calls from this turn's message only (not cumulative branch scan —
-    // otherwise the counter accumulates historical tool calls and fires prematurely).
-    try {
-      const msg = event.message;
-      if (msg?.role === "assistant") {
-        const content = msg?.content;
-        if (Array.isArray(content)) {
-          for (const block of content) {
-            if (block && typeof block === "object" && block.type === "toolCall") {
-              toolCallCount++;
-              if ((block as { name?: string }).name) toolTypes.add((block as { name: string }).name);
-            }
-          }
-        }
-      }
-    } catch {
-      return;
-    }
-
-    // Require 8+ tool calls AND 2+ distinct tool types
-    if (toolCallCount < DEFAULT_SKILL_TRIGGER_TOOL_CALLS) return;
-    if (toolTypes.size < 2) return;
-
-    triggeredThisSession = true;
-
-    try {
-      // Build conversation context
-      const branch = ctx.sessionManager.getBranch();
-      const parts: string[] = [];
-
-      for (const entry of branch) {
-        if (entry.type !== "message") continue;
-        const msg = entry.message;
-        const text = getMessageText(msg);
-        if (!text) continue;
-        const prefix = msg.role === "user" ? "[USER]" : "[ASSISTANT]";
-        parts.push(`${prefix}: ${text}`);
-      }
-
-      // Only include recent context
-      const recentParts = parts.slice(-10);
-
-      const currentMemory = store.getMemoryEntries().join(ENTRY_DELIMITER);
-      const skillIndex = await skillStore.loadIndex();
-      const skillSummary = skillIndex
-        .map((skill) => `${skill.skillId} [${skill.scope}]: ${skill.displayName || skill.name} - ${skill.description}`)
-        .join("\n");
-
-      const activeProjectName = skillStore.getProjectName();
-      const scopeLine = activeProjectName
-        ? `Active project context: '${activeProjectName}'. If workflow details depend on this project, use scope='project'; otherwise use scope='global'.`
-        : "No active project context detected. Use scope='global' unless the workflow is clearly project-specific.";
-
-      const prompt = [
-        "This was a complex task that required multiple tool calls. Extract any reusable procedures as skills.",
-        "A bundled skill named procedural-skill-creator is loaded for you. Read and follow it before deciding whether to create or patch a skill.",
-        "Always pass scope explicitly when creating a skill: scope='global' or scope='project'.",
-        "Choose scope='global' for transferable procedures and scope='project' when the workflow depends on this repo's paths, scripts, architecture, deploy steps, or conventions.",
-        scopeLine,
-        "",
-        "--- Existing Skills ---",
-        skillSummary || "(none)",
-        "",
-        "--- Current Memory ---",
-        currentMemory || "(empty)",
-        "",
-        "--- Recent Conversation ---",
-        recentParts.join("\n\n"),
-        "",
-        "If a skill should be created, use the skill tool with action 'create'.",
-        "If a related skill already exists, use 'patch' with its skill_id to update it.",
-        "If nothing reusable happened, say 'Nothing to extract.' and stop.",
-      ].join("\n");
-
-      const result = await pi.exec("pi", ["-p", "--no-session", "--skill", proceduralSkillCreatorPath, prompt], {
-        signal: ctx.signal,
-        timeout: 60000,
-      });
-
-      if (result.code === 0 && result.stdout) {
-        const output = result.stdout.trim();
-        if (output && !output.toLowerCase().includes("nothing to extract")) {
-          ctx.ui.notify("🧠 Complex task detected — skill extracted", "info");
-        }
-      }
-    } catch {
-      // Best-effort — don't block
-    }
-  });
-}

package/src/skills/procedural-skill-creator/SKILL.md

@@ -1,146 +0,0 @@
----
-name: procedural-skill-creator
-description: Create, patch, or improve a procedural skill using the extension's skill tool. Use when recent work should be captured as a reusable global or project-scoped procedure.
----
-
-# Procedural Skill Creator
-
-Turn recent work into a durable procedural skill managed by the extension `skill` tool.
-
-## Goal
-
-Capture repeatable **how-to workflows** so future agents can execute them reliably.
-
-- `create` when no skill covers the workflow.
-- `patch` when an existing skill should absorb new learning.
-- skip extraction when the work is one-off.
-
-## Operating Principle
-
-Extract from what already happened first (conversation, commands, edits, failures, fixes).
-Ask follow-up questions only if critical details are missing.
-
-## Extraction Gate
-
-Save a skill only if all checks pass:
-
-1. Multi-step workflow (not a single trivial action)
-2. Likely to recur
-3. Includes non-obvious pitfalls/decision points
-4. Can be verified with concrete pass/fail checks
-
-If any check fails, respond exactly:
-
-`Nothing to extract.`
-
-## Scope Decision
-
-- `global`: portable across repos/projects
-- `project`: depends on this repo's paths, scripts, architecture, or conventions
-
-Heuristic: if repo-specific paths or commands are required, use `project`.
-
-## Global Skill De-duplication Protocol
-
-Before creating a **global** skill, prevent overlap with existing global skills.
-
-1. List skills with `skill(action="view")`.
-2. Filter to `scope=global`.
-3. Compare candidate against existing skills in three passes:
-   - **Name pass**: exact slug match or near-name match (same core verb+noun)
-   - **Description pass**: same trigger intent / same expected outcome
-   - **Procedure pass**: substantially same step sequence
-4. Decide action:
-   - **Exact same name/intent** → do **not** create; use `patch`/`edit`
-   - **Different name, same intent** → merge into existing skill (patch existing), avoid duplicate
-   - **Adjacent but distinct intent** → create new skill with sharper boundary in `When to Use`
-
-If uncertain between two similar skills, run a tie-breaker:
-- ask: "Would both skills trigger for the same user prompt and produce the same outcome?"
-- if yes, merge; if no, keep separate and clarify boundaries.
-
-Default bias: **merge over duplicate**.
-
-## Action Decision
-
-- `create`: no existing skill covers the core job
-- `patch`: existing skill exists; improve only changed section(s)
-
-Prefer patching over creating overlapping skills.
-
-## Workflow
-
-1. **Capture intent**
-   - What job should this skill enable?
-   - When should it trigger?
-   - What outcome should it produce?
-2. **Collect evidence from recent work**
-   - successful sequence
-   - dead ends and corrections
-   - verification signals
-3. **Run de-dup check** (required for global scope)
-4. **Decide** `create` / `patch` / `Nothing to extract.`
-5. **Draft or revise** using required sections:
-   - `## When to Use`
-   - `## Procedure`
-   - `## Pitfalls`
-   - `## Verification`
-6. **Run a lightweight eval pass** (before saving):
-   - one normal case
-   - one edge case
-   - one near-miss (should *not* use this skill)
-   Refine if ambiguous.
-7. **Persist with `skill` tool**
-   - create: `name`, `description`, `scope` (always explicit), full body
-   - patch: `skill_id`, `section`, section content
-
-## Authoring Standards
-
-### Name
-
-- short kebab-case (`debug-ci-timeouts`, `backfill-flag-rollout`)
-- name the reusable job, not the incident
-
-### Description (Trigger Quality)
-
-The description is the main trigger signal.
-Include:
-- what it does
-- when to use it
-- nearby phrasing users might use
-
-Be explicit enough to avoid under-triggering, without becoming spammy.
-
-### Section Quality
-
-- **When to Use**: trigger conditions + boundaries
-- **Procedure**: ordered, actionable steps
-- **Pitfalls**: frequent failure modes + prevention
-- **Verification**: concrete checks (tests, logs, files, outputs)
-
-## Generalization Guardrails
-
-- Don’t overfit to one transcript.
-- Explain *why* key steps matter when non-obvious.
-- Prefer principles + steps over rigid cargo-cult rules.
-- Keep it lean; remove steps that do not change outcomes.
-
-## Patch Guidance
-
-When patching:
-
-- use existing `skill_id`
-- patch only changed section(s)
-- prioritize `Procedure`, `Pitfalls`, `Verification`
-- avoid rewriting unrelated content
-
-## Rules
-
-- Use `skill` tool only (no direct file writes).
-- Prefer one strong skill over many near-duplicates.
-- Do not store temporary task state, ticket notes, or one-off results.
-
-## Completion Standard
-
-A saved skill must allow a future agent to execute the workflow with minimal guesswork and clear verification.
-If not, refine before saving.