@selesai/code 0.13.0 → 0.13.1

package/dist/extensions/pi-hermes-memory/src/tools/skill-tool.ts

@@ -0,0 +1,333 @@
+/**
+ * Skill manager tool — registers the LLM-callable `skill_manage` tool for procedural memory.
+ * Complements the `memory` tool (declarative knowledge) with procedural knowledge.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { SkillStore } from "../store/skill-store.js";
+import { SKILL_TOOL_DESCRIPTION } from "../constants.js";
+import { createSharedToolResultRenderer } from "./shared-output-view.js";
+import { skillResultView } from "./tool-result-views.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', 'Verification', 'When to Use'.",
+  })),
+  content: Type.Optional(Type.String({
+    description: "Raw markdown body for create/update/edit, or Markdown section body for patch. Prefer structured fields over free-form content when possible. For patch, JSON arrays are auto-coerced for list sections; JSON objects are rejected.",
+  })),
+  when_to_use: Type.Optional(Type.String({
+    description: "Structured create/update/edit field, or structured patch body when section is 'When to Use'.",
+  })),
+  procedure_steps: Type.Optional(Type.Array(Type.String(), {
+    description: "Structured create/update/edit field, or structured patch body when section is 'Procedure'. Ordered concrete steps.",
+  })),
+  pitfalls: Type.Optional(Type.Array(Type.String(), {
+    description: "Structured create/update/edit field, or structured patch body when section is 'Pitfalls'.",
+  })),
+  verification_steps: Type.Optional(Type.Array(Type.String(), {
+    description: "Structured create/update/edit field, or structured patch body when section is 'Verification'.",
+  })),
+}, { additionalProperties: false });
+
+export const SKILL_MANAGE_TOOL_NAME = "skill_manage";
+
+export function registerSkillTool(pi: ExtensionAPI, store: SkillStore): void {
+  pi.registerTool({
+    name: SKILL_MANAGE_TOOL_NAME,
+    label: "Skill Manager",
+    description: SKILL_TOOL_DESCRIPTION,
+    promptSnippet: "Create, inspect, and update reusable procedures and patterns",
+    promptGuidelines: [
+      "Use the skill_manage 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, 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/patch: when_to_use, procedure_steps, pitfalls, and verification_steps. The tool renders valid SKILL.md sections for you.",
+      "For patch, pass section plus the matching structured field (e.g. section='Procedure' with procedure_steps). Avoid free-form content that is a JSON array/object string.",
+      "Prefer 'update' for multi-section rewrites when patch content would be large or format-unstable.",
+      "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.",
+    ],
+    renderResult: createSharedToolResultRenderer(skillResultView),
+    parameters: SKILL_TOOL_PARAMETERS,
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      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) {
+        case "create":
+          if (!name) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ success: false, error: "name is required for 'create' action." }) }],
+              details: {},
+            };
+          }
+          if (!description) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ success: false, error: "description is required for 'create' action." }) }],
+              details: {},
+            };
+          }
+          const createBodyResult = buildBodyOrError();
+          if (!createBodyResult.body) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ success: false, error: createBodyResult.error }) }],
+              details: {},
+            };
+          }
+          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":
+          if (!skill_id) {
+            const index = await store.loadIndex();
+            return {
+              content: [{ type: "text", text: JSON.stringify({ success: true, skills: index }) }],
+              details: { skills: index },
+            };
+          }
+          const doc = await store.loadSkill(skill_id);
+          if (!doc) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ success: false, error: `Skill '${skill_id}' not found.` }) }],
+              details: {},
+            };
+          }
+          result = { success: true, ...doc };
+          break;
+
+        case "patch": {
+          if (!skill_id) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ success: false, error: "skill_id is required for 'patch' action." }) }],
+              details: {},
+            };
+          }
+          if (!section) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ success: false, error: "section is required for 'patch' action." }) }],
+              details: {},
+            };
+          }
+
+          const sectionKey = section.replace(/^#+\s*/, "").trim().toLowerCase();
+          let patchContent = content?.trim() ?? "";
+
+          // Prefer structured fields matching the target section so the LLM
+          // does not have to invent Markdown list formatting.
+          if (sectionKey === "procedure" && procedureSteps.length > 0) {
+            patchContent = formatOrderedList(procedureSteps);
+          } else if (sectionKey === "pitfalls" && pitfallItems.length > 0) {
+            patchContent = formatBulletList(pitfallItems, "No notable pitfalls recorded yet.");
+          } else if (sectionKey === "verification" && verificationSteps.length > 0) {
+            patchContent = formatOrderedList(verificationSteps);
+          } else if ((sectionKey === "when to use" || sectionKey === "when_to_use") && whenToUse) {
+            patchContent = whenToUse;
+          } else if (!patchContent && hasStructuredBody) {
+            // Allow a single structured field even if section name is non-standard.
+            if (procedureSteps.length > 0 && pitfallItems.length === 0 && verificationSteps.length === 0 && !whenToUse) {
+              patchContent = formatOrderedList(procedureSteps);
+            } else if (pitfallItems.length > 0 && procedureSteps.length === 0 && verificationSteps.length === 0 && !whenToUse) {
+              patchContent = formatBulletList(pitfallItems, "No notable pitfalls recorded yet.");
+            } else if (verificationSteps.length > 0 && procedureSteps.length === 0 && pitfallItems.length === 0 && !whenToUse) {
+              patchContent = formatOrderedList(verificationSteps);
+            } else if (whenToUse && procedureSteps.length === 0 && pitfallItems.length === 0 && verificationSteps.length === 0) {
+              patchContent = whenToUse;
+            } else {
+              return {
+                content: [{
+                  type: "text",
+                  text: JSON.stringify({
+                    success: false,
+                    error: "For patch, provide content or exactly one structured field matching the target section (procedure_steps, pitfalls, verification_steps, or when_to_use). Use update for multi-section rewrites.",
+                  }),
+                }],
+                details: {},
+              };
+            }
+          }
+
+          if (!patchContent) {
+            return {
+              content: [{
+                type: "text",
+                text: JSON.stringify({
+                  success: false,
+                  error: "content or a matching structured field is required for 'patch' action. Prefer procedure_steps/pitfalls/verification_steps/when_to_use.",
+                }),
+              }],
+              details: {},
+            };
+          }
+
+          result = await store.patch(skill_id, section, patchContent);
+          break;
+        }
+
+        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 '${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, nextDescription, nextBody);
+          break;
+        }
+
+        case "delete":
+          if (!skill_id) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ success: false, error: "skill_id is required for 'delete' action." }) }],
+              details: {},
+            };
+          }
+          result = await store.delete(skill_id);
+          break;
+
+        default:
+          result = {
+            success: false,
+            error: `Unknown action '${action}'. Use: create, view, patch, update, delete`,
+          };
+      }
+
+      return {
+        content: [{ type: "text", text: JSON.stringify(result) }],
+        details: result,
+      };
+    },
+  });
+}

package/dist/extensions/pi-hermes-memory/src/tools/tool-result-views.ts

@@ -0,0 +1,105 @@
+import type { SharedOutputView } from "./shared-output-view.js";
+import { normalizeSharedOutputView } from "./shared-output-view.js";
+
+function record(value: unknown): Record<string, any> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, any>
+    : null;
+}
+
+function resultData(result: unknown): Record<string, any> | null {
+  const resultRecord = record(result);
+  const details = record(resultRecord?.details);
+  if (details && Object.keys(details).length > 0) return details;
+
+  const content = resultRecord?.content;
+  if (!Array.isArray(content) || content.length !== 1) return null;
+  const text = record(content[0])?.text;
+  if (typeof text !== "string" || !text.trimStart().startsWith("{")) return null;
+  try {
+    return record(JSON.parse(text));
+  } catch {
+    return null;
+  }
+}
+
+function firstText(...values: unknown[]): string | null {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return null;
+}
+
+function warningText(data: Record<string, any>): string | null {
+  const warnings = Array.isArray(data.warnings)
+    ? data.warnings.filter((value: unknown) => typeof value === "string" && value.trim())
+    : [];
+  return firstText(data.warning, ...warnings);
+}
+
+export function memoryResultView(result: unknown): SharedOutputView {
+  const base = normalizeSharedOutputView(result);
+  const data = resultData(result);
+  if (!data) return base;
+
+  if (data.success === false || (data.success !== true && firstText(data.error))) {
+    const failureReason = firstText(data.error, data.message);
+    return { ...base, status: "failure", summary: failureReason ? `Error · ${failureReason}` : "Error" };
+  }
+  if (data.success !== true) return base;
+
+  const primaryMessage = (firstText(data.message) ?? "").split(/\s*\bWarning:/)[0].trim();
+  const evicted = typeof data.evicted_count === "number"
+    ? data.evicted_count
+    : Array.isArray(data.evicted_entries)
+      ? data.evicted_entries.length
+      : 0;
+  const outcome = /^Entry added\.$/.test(primaryMessage) || /^Failure memory saved:/.test(primaryMessage) || evicted > 0
+    ? "Saved"
+    : /^Entry replaced\.$/.test(primaryMessage)
+      ? "Replaced"
+      : /^Entry removed\.$/.test(primaryMessage)
+        ? "Removed"
+        : /^Entry already exists/.test(primaryMessage)
+          ? "Unchanged"
+          : "Updated";
+  const parts = [outcome];
+  if (typeof data.target === "string" && data.target.trim()) parts.push(`target: ${data.target.trim()}`);
+  const category = typeof data.category === "string" && data.category.trim()
+    ? data.category.trim()
+    : data.target === "failure"
+      ? primaryMessage.match(/^Failure memory saved:\s*(\S+)/i)?.[1] ?? null
+      : null;
+  if (category) parts.push(`category: ${category}`);
+  if (evicted > 0) parts.push(`evicted: ${evicted}`);
+  if (typeof data.entry_count === "number") parts.push(`${data.entry_count} ${data.entry_count === 1 ? "entry" : "entries"}`);
+  if (typeof data.usage === "string" && data.usage.trim()) parts.push(data.usage.trim());
+  const warning = warningText(data);
+  if (warning) parts.push(`Warning: ${warning}`);
+  return { ...base, status: "success", summary: parts.join(" · ") };
+}
+
+export function searchResultView(result: unknown): SharedOutputView {
+  const base = normalizeSharedOutputView(result);
+  const data = resultData(result);
+  if (!data || data.success === false) return base;
+  if (typeof data.count === "number") {
+    return { ...base, summary: data.count === 1 ? "Found 1 result" : `Found ${data.count} results` };
+  }
+  return base;
+}
+
+export function skillResultView(result: unknown): SharedOutputView {
+  const base = normalizeSharedOutputView(result);
+  const data = resultData(result);
+  if (!data) return base;
+  if (data.success === false) {
+    const failureReason = firstText(data.error, data.message);
+    return { ...base, status: "failure", summary: failureReason ? `Error · ${failureReason}` : "Error" };
+  }
+  if (Array.isArray(data.skills)) return { ...base, summary: `Skills: ${data.skills.length} available` };
+
+  const name = firstText(data.displayName, data.name, data.skillId, data.skill_id);
+  if (name) return { ...base, summary: `Skill: ${name}` };
+  return { ...base, summary: firstText(data.message) ?? "Skill updated" };
+}

package/dist/extensions/pi-hermes-memory/src/types.ts

@@ -0,0 +1,214 @@
+/**
+ * Shared TypeScript types for the Hermes Memory extension.
+ */
+
+import type { ModelThinkingLevel, TextContent } from "@earendil-works/pi-ai";
+
+export type MemoryOverflowStrategy = "auto-consolidate" | "reject" | "fifo-evict";
+
+export type SessionSearchVariant = "legacy" | "anchors";
+
+export type ThinkingLevel = ModelThinkingLevel;
+
+export type ReviewTransport = "direct" | "subprocess";
+
+export interface SessionSearchConfig {
+  /** Session search implementation variant. Default: legacy */
+  variant: SessionSearchVariant;
+}
+
+export interface MemoryConfig {
+  /** Prompt memory mode. Default: policy-only */
+  memoryMode: "policy-only" | "legacy-inject";
+  /** Policy prompt style used when memoryMode is policy-only. Default: full */
+  memoryPolicyStyle?: "full" | "compact" | "custom" | "none";
+  /** Custom policy prompt text used when memoryPolicyStyle is custom */
+  memoryPolicyCustomText?: string;
+  /** Max chars for MEMORY.md (agent notes). Default: 5000 */
+  memoryCharLimit: number;
+  /** Max chars for USER.md (user profile). Default: 5000 */
+  userCharLimit: number;
+  /** Max chars for project-level MEMORY.md. Default: 5000 */
+  projectCharLimit: number;
+  /** Turns between background auto-reviews. Default: 10 */
+  nudgeInterval: number;
+  /** Recent conversation messages included in background review. 0 = all. Default: 0 */
+  reviewRecentMessages?: number;
+  /** Enable background learning loop. Default: true */
+  reviewEnabled: boolean;
+  /** How background review invokes the LLM. Default: direct */
+  reviewTransport?: ReviewTransport;
+  /** Flush memories before compaction. Default: true */
+  flushOnCompact: boolean;
+  /** Flush memories on session shutdown. Default: true */
+  flushOnShutdown: boolean;
+  /** Minimum user turns before flush triggers. Default: 6 */
+  flushMinTurns: number;
+  /** Recent conversation messages included in session flush. 0 = all. Default: 0 */
+  flushRecentMessages?: number;
+  /** Override extension storage directory. Default: ~/.selesai/agent/pi-hermes-memory */
+  memoryDir?: string;
+  /** Directory for project-scoped memory (relative to ~/.selesai/agent). Default: "projects-memory" */
+  projectsMemoryDir?: string;
+  /** Session search configuration. Default: { variant: "legacy" } */
+  sessionSearch?: SessionSearchConfig;
+  /** Override model used for child pi -p subprocess LLM calls. Default: unset */
+  llmModelOverride?: string;
+  /** Override thinking level used for child pi -p subprocess LLM calls. Default: unset */
+  llmThinkingOverride?: ThinkingLevel;
+  /** Trusted Pi extension sources required by child processes, such as custom providers or auth adapters. */
+  childExtensionPaths?: string[];
+  /** Strategy when memory is full. Default: auto-consolidate */
+  memoryOverflowStrategy?: MemoryOverflowStrategy;
+  /** Wall-clock grace after overflow before automatic consolidation. Default: 180000 */
+  overflowGraceMs?: number;
+  /** Legacy alias for memoryOverflowStrategy. Default: true */
+  autoConsolidate: boolean;
+  /** Detect user corrections and trigger immediate memory save. Default: true */
+  correctionDetection: boolean;
+  /** Override strong correction regex sources. Missing = defaults; [] = none. */
+  correctionStrongPatterns?: string[];
+  /** Override weak correction regex sources. Missing = defaults; [] = none. */
+  correctionWeakPatterns?: string[];
+  /** Override negative correction regex sources. Missing = defaults; [] = none. */
+  correctionNegativePatterns?: string[];
+  /** Override directive words used after weak correction patterns. Missing = defaults; [] = none. */
+  correctionDirectiveWords?: string[];
+  /** Inject recent failure memories into the system prompt. Default: true */
+  failureInjectionEnabled: boolean;
+  /** Maximum age in days for injected failure memories. Default: 7 */
+  failureInjectionMaxAgeDays: number;
+  /** Maximum number of failure memories to inject. Default: 5 */
+  failureInjectionMaxEntries: number;
+  /** Tool calls before triggering background review (in addition to turn count). Default: 15 */
+  nudgeToolCalls: number;
+  /** Maximum time in milliseconds for a consolidation run, auto or manual. Default: 180000 */
+  consolidationTimeoutMs: number;
+  /** Log failed auto-consolidation attempts to the session console. Default: true */
+  autoConsolidationWarnOnFailure: boolean;
+  /** Inject pinned STANDING.md instructions into every session. Default: true */
+  standingInstructionsEnabled: boolean;
+}
+
+export type MemoryCategory =
+  | "failure"
+  | "correction"
+  | "insight"
+  | "preference"
+  | "convention"
+  | "tool-quirk";
+
+export interface MemoryResult {
+  success: boolean;
+  error?: string;
+  message?: string;
+  warning?: string;
+  warnings?: string[];
+  target?: "memory" | "user" | "failure" | "project";
+  entries?: string[];
+  usage?: string;
+  entry_count?: number;
+  evicted_entries?: string[];
+  evicted_count?: number;
+  matches?: string[];
+  /** Targets that contain old_text when a replace/remove was sent to the wrong one. */
+  matching_targets?: Array<"memory" | "user" | "failure" | "project">;
+}
+
+export interface MemoryMutationOperation {
+  action: "add" | "replace" | "remove";
+  content?: string;
+  oldText?: string;
+  category?: MemoryCategory;
+  failureReason?: string;
+  project?: string;
+}
+
+export interface MemorySnapshot {
+  memory: string;
+  user: string;
+}
+
+export interface ConsolidationResult {
+  /** Whether consolidation succeeded */
+  consolidated: boolean;
+  /** Error message if consolidation failed */
+  error?: string;
+  /**
+   * Set when another session already holds the consolidation lock for this
+   * target. Nothing is broken — the work is happening elsewhere — so callers
+   * should tell the user to retry rather than report a failed consolidation.
+   */
+  deferred?: boolean;
+}
+
+export type SkillScope = "global" | "project";
+
+export interface SkillIndex {
+  /** Stable id for read/update/delete operations */
+  skillId: string;
+  /** Whether the skill is global or project-scoped */
+  scope: SkillScope;
+  /** File name on disk (usually SKILL.md) */
+  fileName: string;
+  /** Absolute path to the skill file */
+  path: string;
+  /** Active project name for project-scoped skills */
+  projectName?: string;
+  /** Pi skill slug stored in frontmatter and folder name */
+  name: string;
+  /** Optional human-friendly title preserved for UI output */
+  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 {
+  /** Full markdown body (after frontmatter) */
+  body: string;
+  /** Version number */
+  version: number;
+}
+
+export interface SkillResult {
+  success: boolean;
+  error?: string;
+  message?: string;
+  fileName?: string;
+  skillId?: string;
+  scope?: SkillScope;
+  path?: string;
+  conflictType?: "duplicate" | "similar" | "name-collision" | "scope-conflict";
+  similarSkillIds?: string[];
+  suggestedAction?: "patch" | "update" | "rename";
+}
+
+/**
+ * Extract displayable text from a Pi session entry message.
+ *
+ * Accepts any value — returns null for non-message entries (BashExecutionMessage,
+ * NotificationMessage, etc.) that lack a `content` property.
+ *
+ * Returns the concatenated text, truncated to `maxLength` chars.
+ */
+export function getMessageText(msg: unknown, maxLength = 500): string | null {
+  if (typeof msg !== "object" || msg === null) return null;
+  const { role, content } = msg as Record<string, unknown>;
+  if (typeof role !== "string") return null;
+
+  if (typeof content === "string") {
+    return content.slice(0, maxLength);
+  }
+  if (Array.isArray(content)) {
+    const text = (content as TextContent[])
+      .filter((block): block is TextContent => block.type === "text" && typeof block.text === "string")
+      .map((block) => block.text)
+      .join("\n");
+    return text.length > 0 ? text.slice(0, maxLength) : null;
+  }
+  return null;
+}