@alexgorbatchev/pi-skill-library 0.1.0

package/src/createLibraryReport.ts

@@ -0,0 +1,42 @@
+import { groupLibrarySummariesByScope } from './groupLibrarySummariesByScope.js';
+import { replaceHomeDirectoryWithTilde } from './replaceHomeDirectoryWithTilde.js';
+import type { ILibraryReportDetails, ILibrarySkillDiscovery, ILibrarySummary } from './types.js';
+
+export function createLibraryReport(librarySkillDiscovery: ILibrarySkillDiscovery): string {
+  return createLibraryReportFromDetails({
+    diagnostics: librarySkillDiscovery.diagnostics,
+    librarySummaries: librarySkillDiscovery.librarySummaries,
+  });
+}
+
+export function createLibraryReportFromDetails(details: ILibraryReportDetails): string {
+  const lines = ['[Skills Library]'];
+  if (details.librarySummaries.length === 0) {
+    lines.push('  No library skills were discovered.');
+    return lines.join('\n');
+  }
+
+  const librarySummariesByScope = groupLibrarySummariesByScope(details.librarySummaries);
+  for (const [scope, librarySummaries] of librarySummariesByScope) {
+    lines.push(`  ${scope}`);
+    for (const librarySummary of librarySummaries) {
+      appendLibrarySummary(lines, librarySummary);
+    }
+  }
+
+  if (details.diagnostics.length > 0) {
+    lines.push('  diagnostics');
+    for (const diagnostic of details.diagnostics) {
+      lines.push(`    ${replaceHomeDirectoryWithTilde(diagnostic)}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+function appendLibrarySummary(lines: string[], librarySummary: ILibrarySummary): void {
+  lines.push(`    ${replaceHomeDirectoryWithTilde(librarySummary.libraryPath)}`);
+  for (const skillName of librarySummary.skillNames) {
+    lines.push(`      /library:${skillName}`);
+  }
+}

package/src/discoverLibrarySkills.ts

@@ -0,0 +1,365 @@
+import {
+  DefaultResourceLoader,
+  getAgentDir,
+  loadSkills,
+  type ResourceDiagnostic,
+  SettingsManager,
+  type Skill,
+} from '@mariozechner/pi-coding-agent';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import type { ILibrarySkillDiscovery, ILibrarySummary } from './types.js';
+
+const SETTINGS_KEY = '@alexgorbatchev/pi-skills-library';
+const LIBRARY_DIRECTORY_NAME = 'skills-library';
+
+interface IConfiguredLibrarySettings {
+  paths: string[];
+}
+
+type LibraryPathScope = 'project' | 'user' | 'temporary';
+
+interface ILibraryPathCandidate {
+  path: string;
+  scope: LibraryPathScope;
+}
+
+export async function discoverLibrarySkills(
+  cwd: string,
+  extensionPackageRoot: string,
+): Promise<ILibrarySkillDiscovery> {
+  const settingsManager = SettingsManager.create(cwd);
+  const projectSettings = settingsManager.getProjectSettings();
+  const userSettings = settingsManager.getGlobalSettings();
+  const projectSettingsBaseDir = path.join(cwd, '.pi');
+  const userSettingsBaseDir = getAgentDir();
+
+  const projectConfiguredPaths = getConfiguredLibraryPaths(projectSettings, projectSettingsBaseDir, 'project');
+  const userConfiguredPaths = getConfiguredLibraryPaths(userSettings, userSettingsBaseDir, 'user');
+  const projectConfiguredSkillSiblingPaths = getConfiguredSkillSiblingLibraryPaths(
+    projectSettings,
+    projectSettingsBaseDir,
+    'project',
+  );
+  const userConfiguredSkillSiblingPaths = getConfiguredSkillSiblingLibraryPaths(
+    userSettings,
+    userSettingsBaseDir,
+    'user',
+  );
+
+  const conventionalPaths = getConventionalLibraryPaths(cwd);
+  const derivedPaths = await getDerivedLibraryPaths(cwd, extensionPackageRoot);
+
+  const orderedPaths = dedupeLibraryPaths([
+    ...filterPathsByScope(projectConfiguredPaths, 'project'),
+    ...filterPathsByScope(projectConfiguredSkillSiblingPaths, 'project'),
+    ...filterPathsByScope(conventionalPaths, 'project'),
+    ...filterPathsByScope(derivedPaths, 'project'),
+    ...filterPathsByScope(projectConfiguredPaths, 'temporary'),
+    ...filterPathsByScope(conventionalPaths, 'temporary'),
+    ...filterPathsByScope(derivedPaths, 'temporary'),
+    ...filterPathsByScope(userConfiguredPaths, 'user'),
+    ...filterPathsByScope(userConfiguredSkillSiblingPaths, 'user'),
+    ...filterPathsByScope(conventionalPaths, 'user'),
+    ...filterPathsByScope(derivedPaths, 'user'),
+  ]);
+
+  const existingPaths = orderedPaths.filter((candidate) => existsSync(candidate.path));
+  const agentDir = getAgentDir();
+  const libraryResult = loadSkills({
+    cwd,
+    agentDir,
+    includeDefaults: false,
+    skillPaths: existingPaths.map((candidate) => candidate.path),
+  });
+
+  const libraryPaths = existingPaths.map((candidate) => candidate.path);
+  return {
+    skills: libraryResult.skills,
+    skillByName: createSkillMap(libraryResult.skills),
+    diagnostics: libraryResult.diagnostics.map(formatDiagnostic),
+    libraryPaths,
+    librarySummaries: createLibrarySummaries(existingPaths, libraryResult.skills),
+  };
+}
+
+function getConfiguredLibraryPaths(
+  settings: object,
+  baseDir: string,
+  scope: LibraryPathScope,
+): ILibraryPathCandidate[] {
+  const configuredSettings = parseConfiguredLibrarySettings(Reflect.get(settings, SETTINGS_KEY));
+  return configuredSettings.paths.map((configuredPath) => ({
+    path: resolveSettingsPath(configuredPath, baseDir),
+    scope,
+  }));
+}
+
+function getConfiguredSkillSiblingLibraryPaths(
+  settings: object,
+  baseDir: string,
+  scope: LibraryPathScope,
+): ILibraryPathCandidate[] {
+  return readStringArray(Reflect.get(settings, 'skills'))
+    .map((configuredSkillPath) => resolveSettingsPath(configuredSkillPath, baseDir))
+    .map((resolvedSkillPath) => toLibraryPathFromSkillPath(resolvedSkillPath))
+    .filter((libraryPath): libraryPath is string => libraryPath !== null)
+    .map((libraryPath) => ({ path: libraryPath, scope }));
+}
+
+function parseConfiguredLibrarySettings(value: unknown): IConfiguredLibrarySettings {
+  if (!isRecord(value)) {
+    return { paths: [] };
+  }
+
+  return {
+    paths: readStringArray(value.paths),
+  };
+}
+
+function getConventionalLibraryPaths(cwd: string): ILibraryPathCandidate[] {
+  const agentDir = getAgentDir();
+  const ancestorDirectories = getAncestorDirectories(cwd);
+
+  const projectPaths = [
+    path.join(cwd, '.pi', LIBRARY_DIRECTORY_NAME),
+    ...ancestorDirectories.map((directoryPath) => path.join(directoryPath, '.agents', LIBRARY_DIRECTORY_NAME)),
+  ];
+  const userPaths = [
+    path.join(agentDir, LIBRARY_DIRECTORY_NAME),
+    path.join(homedir(), '.agents', LIBRARY_DIRECTORY_NAME),
+  ];
+
+  return [
+    ...projectPaths.map(
+      (libraryPath): ILibraryPathCandidate => ({ path: libraryPath, scope: 'project' }),
+    ),
+    ...userPaths.map(
+      (libraryPath): ILibraryPathCandidate => ({ path: libraryPath, scope: 'user' }),
+    ),
+  ];
+}
+
+async function getDerivedLibraryPaths(cwd: string, extensionPackageRoot: string): Promise<ILibraryPathCandidate[]> {
+  const agentDir = getAgentDir();
+  const resourceLoader = new DefaultResourceLoader({
+    cwd,
+    agentDir,
+    noExtensions: true,
+    noPromptTemplates: true,
+    noThemes: true,
+  });
+  await resourceLoader.reload();
+
+  const skillPaths: ILibraryPathCandidate[] = [];
+  const extensionScope = classifyExtensionScope(extensionPackageRoot, cwd);
+  skillPaths.push({
+    path: path.join(extensionPackageRoot, LIBRARY_DIRECTORY_NAME),
+    scope: extensionScope,
+  });
+
+  for (const skill of resourceLoader.getSkills().skills) {
+    const derivedPath = getSiblingLibraryPath(skill);
+    if (derivedPath !== null) {
+      skillPaths.push({
+        path: derivedPath,
+        scope: skill.sourceInfo.scope,
+      });
+    }
+
+    const packageLibraryPath = getPackageLibraryPath(skill);
+    if (packageLibraryPath !== null) {
+      skillPaths.push({
+        path: packageLibraryPath,
+        scope: skill.sourceInfo.scope,
+      });
+    }
+  }
+
+  return skillPaths;
+}
+
+function classifyExtensionScope(extensionPackageRoot: string, cwd: string): LibraryPathScope {
+  const normalizedPackageRoot = path.resolve(extensionPackageRoot);
+  const normalizedProjectRoot = path.resolve(cwd);
+  const projectPiRoot = path.resolve(cwd, '.pi');
+
+  if (
+    isPathInside(normalizedPackageRoot, normalizedProjectRoot) || isPathInside(normalizedPackageRoot, projectPiRoot)
+  ) {
+    return 'project';
+  }
+
+  return 'user';
+}
+
+function getSiblingLibraryPath(skill: Skill): string | null {
+  return toLibraryPathFromSkillPath(skill.filePath);
+}
+
+function getPackageLibraryPath(skill: Skill): string | null {
+  if (skill.sourceInfo.origin !== 'package' || skill.sourceInfo.baseDir === undefined) {
+    return null;
+  }
+
+  return path.join(skill.sourceInfo.baseDir, LIBRARY_DIRECTORY_NAME);
+}
+
+function filterPathsByScope(paths: ILibraryPathCandidate[], scope: LibraryPathScope): ILibraryPathCandidate[] {
+  return paths.filter((candidate) => candidate.scope === scope);
+}
+
+function dedupeLibraryPaths(paths: ILibraryPathCandidate[]): ILibraryPathCandidate[] {
+  const dedupedPaths: ILibraryPathCandidate[] = [];
+  const seenPaths = new Set<string>();
+
+  for (const candidate of paths) {
+    const normalizedPath = path.normalize(candidate.path);
+    if (seenPaths.has(normalizedPath)) {
+      continue;
+    }
+
+    seenPaths.add(normalizedPath);
+    dedupedPaths.push({
+      path: normalizedPath,
+      scope: candidate.scope,
+    });
+  }
+
+  return dedupedPaths;
+}
+
+function getAncestorDirectories(cwd: string): string[] {
+  const resolvedCwd = path.resolve(cwd);
+  const ancestorDirectories: string[] = [];
+
+  let currentDirectory = resolvedCwd;
+  for (;;) {
+    ancestorDirectories.push(currentDirectory);
+
+    if (existsSync(path.join(currentDirectory, '.git'))) {
+      return ancestorDirectories;
+    }
+
+    const parentDirectory = path.dirname(currentDirectory);
+    if (parentDirectory === currentDirectory) {
+      return ancestorDirectories;
+    }
+
+    currentDirectory = parentDirectory;
+  }
+}
+
+function createLibrarySummaries(libraryPaths: ILibraryPathCandidate[], skills: Skill[]): ILibrarySummary[] {
+  const libraryPathValues = libraryPaths.map((libraryPath) => libraryPath.path);
+  return libraryPaths
+    .map((libraryPath) => ({
+      libraryPath: libraryPath.path,
+      scope: libraryPath.scope,
+      skillNames: findSkillNamesForLibraryPath(libraryPath.path, libraryPathValues, skills),
+    }))
+    .filter((librarySummary) => librarySummary.skillNames.length > 0);
+}
+
+function findSkillNamesForLibraryPath(libraryPath: string, libraryPaths: string[], skills: Skill[]): string[] {
+  return skills
+    .filter((skill) => findOwningLibraryPath(skill, libraryPaths) === libraryPath)
+    .map((skill) => skill.name)
+    .sort();
+}
+
+function findOwningLibraryPath(skill: Skill, libraryPaths: string[]): string | null {
+  const skillDirectoryPath = path.normalize(skill.baseDir);
+  const matchingLibraryPaths = libraryPaths
+    .filter((libraryPath) => isPathInside(skillDirectoryPath, path.normalize(libraryPath)))
+    .sort((leftPath, rightPath) => rightPath.length - leftPath.length);
+
+  const owningLibraryPath = matchingLibraryPaths[0];
+  return owningLibraryPath ?? null;
+}
+
+function createSkillMap(skills: Skill[]): Map<string, Skill> {
+  const skillByName = new Map<string, Skill>();
+  for (const skill of skills) {
+    if (!skillByName.has(skill.name)) {
+      skillByName.set(skill.name, skill);
+    }
+  }
+
+  return skillByName;
+}
+
+function formatDiagnostic(diagnostic: ResourceDiagnostic): string {
+  const location = diagnostic.path ? ` (${diagnostic.path})` : '';
+  return `${diagnostic.type}: ${diagnostic.message}${location}`;
+}
+
+function resolveSettingsPath(configuredPath: string, baseDir: string): string {
+  const trimmedPath = configuredPath.trim();
+  const expandedPath = expandHomeDirectory(trimmedPath);
+  if (path.isAbsolute(expandedPath)) {
+    return path.normalize(expandedPath);
+  }
+
+  return path.resolve(baseDir, expandedPath);
+}
+
+function expandHomeDirectory(configuredPath: string): string {
+  if (configuredPath === '~') {
+    return homedir();
+  }
+
+  if (configuredPath.startsWith('~/')) {
+    return path.join(homedir(), configuredPath.slice(2));
+  }
+
+  return configuredPath;
+}
+
+function toLibraryPathFromSkillPath(resolvedSkillPath: string): string | null {
+  const normalizedSkillPath = path.normalize(resolvedSkillPath);
+  const pathSegments = normalizedSkillPath.split(path.sep).filter((segment) => segment.length > 0);
+  const skillsSegmentIndex = pathSegments.lastIndexOf('skills');
+  if (skillsSegmentIndex === -1) {
+    return null;
+  }
+
+  const leadingSegments = pathSegments.slice(0, skillsSegmentIndex);
+  if (normalizedSkillPath.startsWith(path.sep)) {
+    return path.join(path.sep, ...leadingSegments, LIBRARY_DIRECTORY_NAME);
+  }
+
+  return path.join(...leadingSegments, LIBRARY_DIRECTORY_NAME);
+}
+
+function isPathInside(candidatePath: string, containerPath: string): boolean {
+  const relativePath = path.relative(containerPath, candidatePath);
+  return relativePath === '' || (!relativePath.startsWith('..') && !path.isAbsolute(relativePath));
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function readStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  const stringValues: string[] = [];
+  for (const entry of value) {
+    if (typeof entry !== 'string') {
+      continue;
+    }
+
+    const trimmedEntry = entry.trim();
+    if (trimmedEntry.length === 0) {
+      continue;
+    }
+
+    stringValues.push(trimmedEntry);
+  }
+
+  return stringValues;
+}

package/src/expandLibrarySkill.ts

@@ -0,0 +1,10 @@
+import { type Skill, stripFrontmatter } from '@mariozechner/pi-coding-agent';
+import { readFile } from 'node:fs/promises';
+
+export async function expandLibrarySkill(skill: Skill, args: string): Promise<string> {
+  const content = await readFile(skill.filePath, 'utf8');
+  const body = stripFrontmatter(content).trim();
+  const skillBlock =
+    `<skill name="${skill.name}" location="${skill.filePath}">\nReferences are relative to ${skill.baseDir}.\n\n${body}\n</skill>`;
+  return args.length > 0 ? `${skillBlock}\n\n${args}` : skillBlock;
+}

package/src/groupLibrarySummariesByScope.ts

@@ -0,0 +1,37 @@
+import type { ILibrarySummary } from './types.js';
+
+export function groupLibrarySummariesByScope(librarySummaries: ILibrarySummary[]): Map<string, ILibrarySummary[]> {
+  const librarySummariesByScope = new Map<string, ILibrarySummary[]>();
+  for (const librarySummary of librarySummaries) {
+    const displayScope = toDisplayScope(librarySummary.scope);
+    const existingSummaries = librarySummariesByScope.get(displayScope) ?? [];
+    existingSummaries.push(librarySummary);
+    librarySummariesByScope.set(displayScope, existingSummaries);
+  }
+
+  const orderedScopes = ['project', 'user', 'path'];
+  const orderedLibrarySummariesByScope = new Map<string, ILibrarySummary[]>();
+  for (const orderedScope of orderedScopes) {
+    const scopedSummaries = librarySummariesByScope.get(orderedScope);
+    if (scopedSummaries === undefined) {
+      continue;
+    }
+
+    orderedLibrarySummariesByScope.set(
+      orderedScope,
+      [...scopedSummaries].sort((leftSummary, rightSummary) =>
+        leftSummary.libraryPath.localeCompare(rightSummary.libraryPath)
+      ),
+    );
+  }
+
+  return orderedLibrarySummariesByScope;
+}
+
+function toDisplayScope(scope: ILibrarySummary['scope']): string {
+  if (scope === 'temporary') {
+    return 'path';
+  }
+
+  return scope;
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { default } from './piSkillLibraryExtension.js';

package/src/parseLibraryCommand.ts

@@ -0,0 +1,22 @@
+import type { ILibraryCommand } from './types.js';
+
+const LIBRARY_COMMAND_PREFIX = '/library:';
+
+export function parseLibraryCommand(text: string): ILibraryCommand | null {
+  if (!text.startsWith(LIBRARY_COMMAND_PREFIX)) {
+    return null;
+  }
+
+  const commandBody = text.slice(LIBRARY_COMMAND_PREFIX.length);
+  const spaceIndex = commandBody.indexOf(' ');
+  const skillName = spaceIndex === -1 ? commandBody.trim() : commandBody.slice(0, spaceIndex).trim();
+  if (skillName.length === 0) {
+    return null;
+  }
+
+  const args = spaceIndex === -1 ? '' : commandBody.slice(spaceIndex + 1).trim();
+  return {
+    skillName,
+    args,
+  };
+}

package/src/piSkillLibraryExtension.ts

@@ -0,0 +1,209 @@
+import type { ExtensionAPI, ExtensionContext, InputEventResult } from '@mariozechner/pi-coding-agent';
+import { Box, Text } from '@mariozechner/pi-tui';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createLibraryReport } from './createLibraryReport.js';
+import { discoverLibrarySkills } from './discoverLibrarySkills.js';
+import { expandLibrarySkill } from './expandLibrarySkill.js';
+import { parseLibraryCommand } from './parseLibraryCommand.js';
+import { renderLibraryReport } from './renderLibraryReport.js';
+import type { ILibraryReportDetails, ILibrarySkillDiscovery } from './types.js';
+
+const INFO_COMMAND_NAME = 'pi-skill-library';
+const STARTUP_REPORT_MESSAGE_TYPE = 'pi-skill-library.startup-report';
+const extensionPackageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const handledInputEventResult: InputEventResult = { action: 'handled' };
+
+export default function piSkillLibraryExtension(pi: ExtensionAPI): void {
+  let cachedLibrarySkillDiscovery: ILibrarySkillDiscovery | null = null;
+  let cachedCwd = '';
+
+  const ensureLibrarySkillCommandsRegistered = (librarySkillDiscovery: ILibrarySkillDiscovery): void => {
+    for (const librarySkill of librarySkillDiscovery.skills) {
+      const commandName = createLibraryCommandName(librarySkill.name);
+      pi.registerCommand(commandName, {
+        description: librarySkill.description,
+        handler: async (args, ctx) => {
+          const refreshedLibrarySkillDiscovery = await refreshLibrarySkillDiscovery(ctx.cwd);
+          const requestedSkill = refreshedLibrarySkillDiscovery.skillByName.get(librarySkill.name);
+          if (requestedSkill === undefined) {
+            if (ctx.hasUI) {
+              ctx.ui.notify(
+                `Library skill is no longer available: ${librarySkill.name}. Run /reload if discovery changed.`,
+                'error',
+              );
+            }
+            return;
+          }
+
+          const expandedText = await expandLibrarySkill(requestedSkill, args.trim());
+          if (ctx.isIdle()) {
+            pi.sendUserMessage(expandedText);
+            return;
+          }
+
+          pi.sendUserMessage(expandedText, { deliverAs: 'followUp' });
+        },
+      });
+    }
+  };
+
+  const refreshLibrarySkillDiscovery = async (cwd: string): Promise<ILibrarySkillDiscovery> => {
+    if (cachedLibrarySkillDiscovery !== null && cachedCwd === cwd) {
+      return cachedLibrarySkillDiscovery;
+    }
+
+    cachedLibrarySkillDiscovery = await discoverLibrarySkills(cwd, extensionPackageRoot);
+    cachedCwd = cwd;
+    ensureLibrarySkillCommandsRegistered(cachedLibrarySkillDiscovery);
+    return cachedLibrarySkillDiscovery;
+  };
+
+  const invalidateLibrarySkillDiscovery = (): void => {
+    cachedLibrarySkillDiscovery = null;
+    cachedCwd = '';
+  };
+
+  const onSessionChanged = async (_event: unknown, ctx: ExtensionContext): Promise<void> => {
+    invalidateLibrarySkillDiscovery();
+    await refreshLibrarySkillDiscovery(ctx.cwd);
+  };
+
+  pi.registerMessageRenderer(STARTUP_REPORT_MESSAGE_TYPE, (message, _options, theme) => {
+    const reportDetails = readLibraryReportDetails(message.details);
+    const reportText = reportDetails === null
+      ? getMessageTextContent(message.content)
+      : renderLibraryReport(theme, reportDetails);
+    const box = new Box(0, 0);
+    box.addChild(new Text(reportText, 0, 0));
+    return box;
+  });
+
+  pi.on('session_start', async (_event, ctx) => {
+    invalidateLibrarySkillDiscovery();
+    const librarySkillDiscovery = await refreshLibrarySkillDiscovery(ctx.cwd);
+    pi.sendMessage({
+      customType: STARTUP_REPORT_MESSAGE_TYPE,
+      content: createLibraryReport(librarySkillDiscovery),
+      display: true,
+      details: createLibraryReportDetails(librarySkillDiscovery),
+    });
+  });
+  pi.on('session_switch', onSessionChanged);
+  pi.on('session_fork', onSessionChanged);
+  pi.on('session_tree', onSessionChanged);
+
+  pi.registerCommand(INFO_COMMAND_NAME, {
+    description: 'Print the discovered skills-library roots and skills',
+    handler: async (_args, ctx) => {
+      const librarySkillDiscovery = await refreshLibrarySkillDiscovery(ctx.cwd);
+      pi.sendMessage({
+        customType: STARTUP_REPORT_MESSAGE_TYPE,
+        content: createLibraryReport(librarySkillDiscovery),
+        display: true,
+        details: createLibraryReportDetails(librarySkillDiscovery),
+      });
+    },
+  });
+
+  pi.on('context', async (event) => {
+    return {
+      messages: event.messages.filter((message) => {
+        const messageCustomType = 'customType' in message ? message.customType : undefined;
+        return messageCustomType !== STARTUP_REPORT_MESSAGE_TYPE;
+      }),
+    };
+  });
+
+  pi.on('input', async (event, ctx): Promise<InputEventResult | undefined> => {
+    const libraryCommand = parseLibraryCommand(event.text);
+    if (libraryCommand === null) {
+      return undefined;
+    }
+
+    const librarySkillDiscovery = await refreshLibrarySkillDiscovery(ctx.cwd);
+    const skill = librarySkillDiscovery.skillByName.get(libraryCommand.skillName);
+    if (skill === undefined) {
+      const availableSkillNames = librarySkillDiscovery.skills.map((librarySkill) => librarySkill.name).sort();
+      const availableSkillSummary = availableSkillNames.length === 0
+        ? 'No library skills are currently available.'
+        : `Available library skills: ${availableSkillNames.join(', ')}`;
+
+      if (ctx.hasUI) {
+        ctx.ui.notify(`Unknown library skill: ${libraryCommand.skillName}. ${availableSkillSummary}`, 'error');
+      }
+
+      return handledInputEventResult;
+    }
+
+    const expandedText = await expandLibrarySkill(skill, libraryCommand.args);
+    return createTransformInputEventResult(expandedText);
+  });
+}
+
+function createLibraryReportDetails(librarySkillDiscovery: ILibrarySkillDiscovery): ILibraryReportDetails {
+  return {
+    diagnostics: librarySkillDiscovery.diagnostics,
+    librarySummaries: librarySkillDiscovery.librarySummaries,
+  };
+}
+
+function readLibraryReportDetails(details: unknown): ILibraryReportDetails | null {
+  if (!isLibraryReportDetails(details)) {
+    return null;
+  }
+
+  return details;
+}
+
+function isLibraryReportDetails(value: unknown): value is ILibraryReportDetails {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+
+  const diagnostics = Reflect.get(value, 'diagnostics');
+  const librarySummaries = Reflect.get(value, 'librarySummaries');
+  return Array.isArray(diagnostics)
+    && diagnostics.every((diagnostic) => typeof diagnostic === 'string')
+    && Array.isArray(librarySummaries)
+    && librarySummaries.every(isLibrarySummary);
+}
+
+function isLibrarySummary(value: unknown): value is ILibraryReportDetails['librarySummaries'][number] {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+
+  const libraryPath = Reflect.get(value, 'libraryPath');
+  const scope = Reflect.get(value, 'scope');
+  const skillNames = Reflect.get(value, 'skillNames');
+  return typeof libraryPath === 'string'
+    && isLibrarySummaryScope(scope)
+    && Array.isArray(skillNames)
+    && skillNames.every((skillName) => typeof skillName === 'string');
+}
+
+function isLibrarySummaryScope(value: unknown): value is ILibraryReportDetails['librarySummaries'][number]['scope'] {
+  return value === 'project' || value === 'user' || value === 'temporary';
+}
+
+function getMessageTextContent(content: string | Array<{ type: string; text?: string; }>): string {
+  if (typeof content === 'string') {
+    return content;
+  }
+
+  return content
+    .map((part) => ('text' in part && typeof part.text === 'string' ? part.text : '[non-text content omitted]'))
+    .join('\n');
+}
+
+function createLibraryCommandName(skillName: string): string {
+  return `library:${skillName}`;
+}
+
+function createTransformInputEventResult(text: string): InputEventResult {
+  return {
+    action: 'transform',
+    text,
+  };
+}