@mrclrchtr/supi-skills 4.7.0

package/src/skill-model-invocation.ts

@@ -0,0 +1,134 @@
+import {
+  type BuildSystemPromptOptions,
+  formatSkillsForPrompt,
+} from "@earendil-works/pi-coding-agent";
+import {
+  loadSupiConfigSectionForScope,
+  removeSupiConfigKey,
+  writeSupiConfig,
+} from "@mrclrchtr/supi-core/config";
+import type { SettingsScope, ValueSource } from "@mrclrchtr/supi-core/settings";
+
+const CONFIG_SECTION = "skills";
+const MODEL_INVOCATION_KEY = "modelInvocation";
+
+export const ENABLED = "Enabled";
+export const MODEL_DISABLED = "Model invocation disabled";
+export const DISABLED = "Disabled";
+
+function invocationMap(
+  scope: SettingsScope,
+  cwd: string,
+  homeDir?: string,
+): Record<string, boolean> {
+  const section = loadSupiConfigSectionForScope(CONFIG_SECTION, cwd, { scope, homeDir });
+  const value = section?.[MODEL_INVOCATION_KEY];
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  return Object.fromEntries(
+    Object.entries(value).filter(
+      (entry): entry is [string, boolean] => typeof entry[1] === "boolean",
+    ),
+  );
+}
+
+interface InvocationOptions {
+  name: string;
+  scope: SettingsScope;
+  cwd: string;
+  homeDir?: string;
+}
+
+interface ResolveInvocationOptions extends InvocationOptions {
+  sourceDefault: boolean;
+  projectTrusted: boolean;
+}
+
+/** Resolve a scoped model-invocation preference without reading untrusted project config. */
+export function resolveInvocation({
+  name,
+  sourceDefault,
+  scope,
+  cwd,
+  projectTrusted,
+  homeDir,
+}: ResolveInvocationOptions): { disabled: boolean; source: ValueSource } {
+  if (scope === "project" && projectTrusted) {
+    const project = invocationMap("project", cwd, homeDir);
+    if (Object.hasOwn(project, name)) {
+      return { disabled: project[name] ?? sourceDefault, source: "project" };
+    }
+  }
+  const global = invocationMap("global", cwd, homeDir);
+  if (Object.hasOwn(global, name)) {
+    return { disabled: global[name] ?? sourceDefault, source: "global" };
+  }
+  return { disabled: sourceDefault, source: "default" };
+}
+
+/** Set or remove one scoped model-invocation preference. */
+export function persistInvocation({
+  name,
+  disabled,
+  scope,
+  cwd,
+  homeDir,
+}: InvocationOptions & { disabled: boolean | undefined }): void {
+  const values = invocationMap(scope, cwd, homeDir);
+  if (disabled === undefined) delete values[name];
+  else {
+    Object.defineProperty(values, name, {
+      value: disabled,
+      enumerable: true,
+      configurable: true,
+      writable: true,
+    });
+  }
+  if (Object.keys(values).length === 0) {
+    removeSupiConfigKey({ section: CONFIG_SECTION, scope, cwd }, MODEL_INVOCATION_KEY, {
+      homeDir,
+    });
+    return;
+  }
+  writeSupiConfig(
+    { section: CONFIG_SECTION, scope, cwd },
+    { [MODEL_INVOCATION_KEY]: values },
+    { homeDir },
+  );
+}
+
+/** Replace PI's generated skill block with the effective scoped invocation state. */
+export function applyPromptOverrides({
+  options,
+  systemPrompt,
+  cwd,
+  projectTrusted,
+  homeDir,
+}: {
+  options: BuildSystemPromptOptions;
+  systemPrompt: string;
+  cwd: string;
+  projectTrusted: boolean;
+  homeDir?: string;
+}): string | undefined {
+  if (options.selectedTools && !options.selectedTools.includes("read")) return undefined;
+  const skills = options.skills ?? [];
+  const effective = skills.map((skill) => ({
+    ...skill,
+    disableModelInvocation: resolveInvocation({
+      name: skill.name,
+      sourceDefault: skill.disableModelInvocation,
+      scope: "project",
+      cwd,
+      projectTrusted,
+      homeDir,
+    }).disabled,
+  }));
+  const original = formatSkillsForPrompt(skills);
+  const replacement = formatSkillsForPrompt(effective);
+  if (original === replacement) return undefined;
+  if (!original) return `${systemPrompt}${replacement}`;
+  if (systemPrompt.includes(original)) return systemPrompt.replace(original, replacement);
+  // biome-ignore lint/suspicious/noConsole: prompt mismatch must not fail silently
+  console.warn("[supi-skills] Could not apply skill model-invocation overrides");
+  return undefined;
+}

package/src/skill-settings.ts

@@ -0,0 +1,400 @@
+import {
+  DefaultPackageManager,
+  type ExtensionAPI,
+  type ExtensionContext,
+  getAgentDir,
+  type ResolvedResource,
+  SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+import {
+  registerSettings,
+  type ScopedFieldValue,
+  type SettingsAction,
+  type SettingsApplyResult,
+  type SettingsContext,
+  type SettingsModule,
+  type SettingsScope,
+  type ValueSource,
+} from "@mrclrchtr/supi-core/settings";
+import {
+  buildSkillCatalog,
+  mergeRuntimeSkills,
+  type SkillCatalog,
+  type SkillRecord,
+  skillSourceIdentity,
+} from "./skill-catalog.ts";
+import {
+  hasExactSkillLoadOverride,
+  type SkillLoadOverride,
+  updateSkillLoadOverrides,
+} from "./skill-load-settings.ts";
+import {
+  applyPromptOverrides,
+  DISABLED,
+  ENABLED,
+  MODEL_DISABLED,
+  persistInvocation,
+  resolveInvocation,
+} from "./skill-model-invocation.ts";
+
+const SETTINGS_SECTION_ID = "skills";
+
+interface SkillSettingsOptions {
+  agentDir?: string;
+  homeDir?: string;
+}
+
+interface SkillSettingsControllerOptions {
+  cwd: string;
+  agentDir: string;
+  homeDir?: string;
+  projectTrusted: boolean;
+  settingsManager: SettingsManager;
+  globalSettingsManager: SettingsManager;
+}
+
+function recordResources(record: SkillRecord): ResolvedResource[] {
+  return record.sources.flatMap((source) => (source.resource ? [source.resource] : []));
+}
+
+function isLoaded(record: SkillRecord): boolean {
+  return (
+    record.activeSkill !== undefined ||
+    record.sources.some((source) => source.runtime || source.resource?.enabled)
+  );
+}
+
+function canDisable(record: SkillRecord): boolean {
+  return record.sources.length > 0 && record.sources.every((source) => !source.runtime);
+}
+
+function sourceDefault(record: SkillRecord): boolean {
+  const winner =
+    record.activeSkill ??
+    record.sources.find((source) => source.runtime || source.resource?.enabled)?.skill ??
+    record.sources[0]?.skill;
+  return winner?.disableModelInvocation ?? false;
+}
+
+function moreSpecificSource(left: ValueSource, right: ValueSource): ValueSource {
+  const rank: Record<ValueSource, number> = { default: 0, global: 1, project: 2 };
+  return rank[left] >= rank[right] ? left : right;
+}
+
+function displayValue(value: string, source: ValueSource): string {
+  return `${value} (${source})`;
+}
+
+function validateAction(record: SkillRecord, action: SettingsAction): void {
+  if (action.kind !== "set") return;
+  if (![ENABLED, MODEL_DISABLED, DISABLED].includes(action.value)) {
+    throw new Error(`Invalid skill state: "${action.value}"`);
+  }
+  if (action.value === DISABLED && !canDisable(record)) {
+    throw new Error(`Full disable is unavailable for skill "${record.name}"`);
+  }
+}
+
+function loadOverride(
+  record: SkillRecord,
+  action: SettingsAction,
+  hasExactOverride: boolean,
+): SkillLoadOverride | undefined {
+  if (action.kind === "unset") return hasExactOverride ? "inherit" : undefined;
+  if (action.value === DISABLED) return "unload";
+  return isLoaded(record) ? undefined : "load";
+}
+
+class SkillSettingsController {
+  private readonly cwd: string;
+  private readonly agentDir: string;
+  private readonly homeDir: string | undefined;
+  private readonly projectTrusted: boolean;
+  private readonly settingsManager: SettingsManager;
+  private readonly globalSettingsManager: SettingsManager;
+  private readonly pendingDisabled = new Map<string, Set<string>>();
+  private globalCatalog: SkillCatalog = new Map();
+  private projectCatalog: SkillCatalog = new Map();
+
+  private constructor(options: SkillSettingsControllerOptions) {
+    this.cwd = options.cwd;
+    this.agentDir = options.agentDir;
+    this.homeDir = options.homeDir;
+    this.projectTrusted = options.projectTrusted;
+    this.settingsManager = options.settingsManager;
+    this.globalSettingsManager = options.globalSettingsManager;
+  }
+
+  static async create(
+    cwd: string,
+    projectTrusted: boolean,
+    options: SkillSettingsOptions,
+  ): Promise<SkillSettingsController> {
+    const agentDir = options.agentDir ?? getAgentDir();
+    const controller = new SkillSettingsController({
+      cwd,
+      agentDir,
+      homeDir: options.homeDir,
+      projectTrusted,
+      settingsManager: SettingsManager.create(cwd, agentDir, { projectTrusted }),
+      globalSettingsManager: SettingsManager.create(cwd, agentDir, { projectTrusted: false }),
+    });
+    await controller.refreshCatalogs();
+    return controller;
+  }
+
+  private async refreshCatalogs(): Promise<void> {
+    await Promise.all([this.settingsManager.reload(), this.globalSettingsManager.reload()]);
+    const [globalPaths, projectPaths] = await Promise.all([
+      new DefaultPackageManager({
+        cwd: this.cwd,
+        agentDir: this.agentDir,
+        settingsManager: this.globalSettingsManager,
+      }).resolve(async () => "skip"),
+      new DefaultPackageManager({
+        cwd: this.cwd,
+        agentDir: this.agentDir,
+        settingsManager: this.settingsManager,
+      }).resolve(async () => "skip"),
+    ]);
+    this.globalCatalog = buildSkillCatalog(globalPaths.skills, this.cwd, this.agentDir);
+    this.projectCatalog = buildSkillCatalog(projectPaths.skills, this.cwd, this.agentDir);
+  }
+
+  private records(scope: SettingsScope, ctx?: ExtensionContext): SkillCatalog {
+    return mergeRuntimeSkills(
+      scope === "project" ? this.projectCatalog : this.globalCatalog,
+      ctx,
+      scope,
+      this.pendingDisabled,
+    );
+  }
+
+  /**
+   * Prefer original global provenance when a project support path resolves the
+   * same file as a project resource. This lets Unset remove both the exact
+   * override and the generated support path after a catalog refresh.
+   */
+  private actionResources(record: SkillRecord, scope: SettingsScope): ResolvedResource[] {
+    const globalResources =
+      scope === "project" ? recordResources(this.globalCatalog.get(record.name) ?? record) : [];
+    const unique = new Map<string, ResolvedResource>();
+    for (const resource of [...globalResources, ...recordResources(record)]) {
+      const key = `${resource.path}\0${resource.metadata.origin}\0${resource.metadata.source}`;
+      if (!unique.has(key)) unique.set(key, resource);
+    }
+    return Array.from(unique.values());
+  }
+
+  /**
+   * Attribute the effective load value to the narrowest scoped override.
+   * Project resources can be support-path surrogates, so attribution compares
+   * their effective load state with the original global catalog.
+   */
+  private loadSource(record: SkillRecord, scope: SettingsScope): ValueSource {
+    const resources = recordResources(record);
+    const exact = hasExactSkillLoadOverride({
+      settingsManager: this.settingsManager,
+      resources,
+      scope,
+      cwd: this.cwd,
+      agentDir: this.agentDir,
+    });
+    if (exact) return scope;
+    if (scope === "global") {
+      return resources.some((resource) => !resource.enabled) ? "global" : "default";
+    }
+    if (resources.some((resource) => resource.metadata.scope === "project" && !resource.enabled)) {
+      return "project";
+    }
+    const globalRecord = this.globalCatalog.get(record.name);
+    if (!globalRecord) return "default";
+    const globalResources = recordResources(globalRecord);
+    const projectLoaded = resources.some((resource) => resource.enabled);
+    const globalLoaded = globalResources.some((resource) => resource.enabled);
+    if (projectLoaded !== globalLoaded) return "project";
+    return this.loadSource(globalRecord, "global");
+  }
+
+  private rowSource(
+    record: SkillRecord,
+    scope: SettingsScope,
+    invocationSource: ValueSource,
+  ): ValueSource {
+    return moreSpecificSource(this.loadSource(record, scope), invocationSource);
+  }
+
+  private row(record: SkillRecord, scope: SettingsScope): ScopedFieldValue {
+    const invocation = resolveInvocation({
+      name: record.name,
+      sourceDefault: sourceDefault(record),
+      scope,
+      cwd: this.cwd,
+      projectTrusted: this.projectTrusted,
+      homeDir: this.homeDir,
+    });
+    const value = !isLoaded(record) ? DISABLED : invocation.disabled ? MODEL_DISABLED : ENABLED;
+    const source = this.rowSource(record, scope, invocation.source);
+    const values = canDisable(record)
+      ? [ENABLED, MODEL_DISABLED, DISABLED]
+      : [ENABLED, MODEL_DISABLED];
+    const sourceCount = record.sources.length;
+    const limitation = canDisable(record)
+      ? ""
+      : " Full disable is unavailable because PI does not expose a load setting for one or more sources.";
+    return {
+      field: {
+        kind: "enum",
+        key: record.name,
+        label: record.name,
+        values,
+        description: `${record.description}${sourceCount > 1 ? ` ${sourceCount} sources.` : ""}${limitation}`,
+      },
+      displayValue: displayValue(value, source),
+      editValue: value,
+      source,
+      ...(scope === "project" && source === "project"
+        ? {
+            inheritanceSource:
+              this.globalRowSource(record.name) === "global" ? "global" : "default",
+          }
+        : {}),
+    };
+  }
+
+  private globalRowSource(name: string): ValueSource {
+    const record = this.globalCatalog.get(name);
+    if (!record) return "default";
+    const invocation = resolveInvocation({
+      name,
+      sourceDefault: sourceDefault(record),
+      scope: "global",
+      cwd: this.cwd,
+      projectTrusted: false,
+      homeDir: this.homeDir,
+    });
+    return this.rowSource(record, "global", invocation.source);
+  }
+
+  read(scope: SettingsScope, ctx?: ExtensionContext): ScopedFieldValue[] {
+    return Array.from(this.records(scope, ctx).values())
+      .sort((left, right) => left.name.localeCompare(right.name))
+      .map((record) => this.row(record, scope));
+  }
+
+  private updatePendingDisabled(
+    fieldKey: string,
+    nextLoadOverride: SkillLoadOverride,
+    activeSkillIdentity: string | undefined,
+  ): void {
+    if (nextLoadOverride !== "unload") {
+      this.pendingDisabled.delete(fieldKey);
+      return;
+    }
+    if (activeSkillIdentity) {
+      this.pendingDisabled.set(fieldKey, new Set([activeSkillIdentity]));
+    }
+  }
+
+  async apply(
+    scope: SettingsScope,
+    fieldKey: string,
+    action: SettingsAction,
+    ctx?: ExtensionContext,
+  ): Promise<SettingsApplyResult> {
+    if (scope === "project" && !this.projectTrusted) {
+      throw new Error("Project is not trusted; refusing to write project skill settings");
+    }
+    const record = this.records(scope, ctx).get(fieldKey);
+    if (!record) return {};
+    validateAction(record, action);
+    const activeSkillIdentity = record.activeSkill
+      ? skillSourceIdentity(record.activeSkill)
+      : undefined;
+
+    if (action.kind !== "set" || action.value !== DISABLED) {
+      persistInvocation({
+        name: fieldKey,
+        disabled: action.kind === "set" ? action.value === MODEL_DISABLED : undefined,
+        scope,
+        cwd: this.cwd,
+        homeDir: this.homeDir,
+      });
+    }
+
+    const resources = this.actionResources(record, scope);
+    const hasLoadOverride = hasExactSkillLoadOverride({
+      settingsManager: this.settingsManager,
+      resources,
+      scope,
+      cwd: this.cwd,
+      agentDir: this.agentDir,
+    });
+    const nextLoadOverride = loadOverride(record, action, hasLoadOverride);
+    if (nextLoadOverride && resources.length > 0) {
+      updateSkillLoadOverrides({
+        settingsManager: this.settingsManager,
+        resources,
+        scope,
+        state: nextLoadOverride,
+        cwd: this.cwd,
+        agentDir: this.agentDir,
+      });
+      await this.settingsManager.flush();
+      const error = this.settingsManager.drainErrors()[0];
+      await this.refreshCatalogs();
+      if (error) throw error.error;
+      this.updatePendingDisabled(fieldKey, nextLoadOverride, activeSkillIdentity);
+      return {
+        notice: { message: "Reload required for skill load changes", level: "info" },
+      };
+    }
+    return {};
+  }
+}
+
+function createSkillSettingsModule(options: SkillSettingsOptions): SettingsModule {
+  let controllerKey: string | undefined;
+  let controllerPromise: Promise<SkillSettingsController> | undefined;
+
+  const getController = (context: SettingsContext): Promise<SkillSettingsController> => {
+    const projectTrusted = context.ctx?.isProjectTrusted() ?? false;
+    const key = `${context.cwd}\0${projectTrusted}`;
+    if (!controllerPromise || controllerKey !== key) {
+      controllerKey = key;
+      controllerPromise = SkillSettingsController.create(context.cwd, projectTrusted, options);
+    }
+    return controllerPromise;
+  };
+
+  return {
+    id: SETTINGS_SECTION_ID,
+    label: "Skills",
+    read: async (context) => ({
+      rows: (await getController(context)).read(context.scope, context.ctx),
+    }),
+    apply: async (request) =>
+      (await getController(request)).apply(
+        request.scope,
+        request.fieldKey,
+        request.action,
+        request.ctx,
+      ),
+  };
+}
+
+/** Register scoped skill availability settings and prompt overrides. */
+export default function skillSettings(pi: ExtensionAPI, options: SkillSettingsOptions = {}): void {
+  registerSettings(pi, createSkillSettingsModule(options));
+
+  pi.on("before_agent_start", (event, ctx) => {
+    const systemPrompt = applyPromptOverrides({
+      options: event.systemPromptOptions,
+      systemPrompt: event.systemPrompt,
+      cwd: ctx.cwd,
+      projectTrusted: ctx.isProjectTrusted(),
+      homeDir: options.homeDir,
+    });
+    return systemPrompt === undefined ? undefined : { systemPrompt };
+  });
+}

package/src/skill-shortcut.ts

@@ -0,0 +1,123 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { fuzzyFilter } from "@earendil-works/pi-tui";
+
+/**
+ * Extension: `$` as a shortcut prefix for skills.
+ *
+ * - `$agent-browser` expands to `/skill:agent-browser`
+ * - Autocomplete triggers on `$` showing only skill names
+ * - Works anywhere in the prompt (after space or at start)
+ */
+
+const DELIMITERS = new Set([" ", "\t", "\n"]);
+
+/** Find the `$token` at the cursor, or null if not in one. */
+function extractDollarPrefix(textBeforeCursor: string): string | null {
+  // Walk backwards to find the start of the current token
+  for (let i = textBeforeCursor.length - 1; i >= 0; i--) {
+    const char = textBeforeCursor[i];
+    if (char && DELIMITERS.has(char)) {
+      // Hit a delimiter — the token starts at i+1
+      const token = textBeforeCursor.slice(i + 1);
+      return token.startsWith("$") ? token : null;
+    }
+  }
+  // Reached start of line
+  return textBeforeCursor.startsWith("$") ? textBeforeCursor : null;
+}
+
+// ── Extension entry point ─────────────────────────────────────────
+
+/**
+ * Register `$skill-name` → `/skill:skill-name` expansion and autocomplete.
+ *
+ * ## Behavior gotchas
+ *
+ * - Installed skill names are snapshotted at `session_start` via
+ *   `pi.getCommands()`; after adding or removing skills, use `/reload` or
+ *   start a new session before testing expansion behavior.
+ * - Outside `$...` tokens, autocomplete must delegate back to the current
+ *   provider so built-in completion and file completion continue to work.
+ *
+ * ## Testing
+ *
+ * If behavior changes, test both:
+ * - expansion inside `$...` tokens
+ * - normal autocomplete everywhere else
+ */
+export default function (pi: ExtensionAPI) {
+  let skillNames: string[] = [];
+  let skillCommands: { name: string; description?: string }[] = [];
+
+  pi.on("session_start", (_event, ctx) => {
+    const commands = pi.getCommands();
+    skillCommands = commands
+      .filter((c) => c.source === "skill")
+      .map((c) => ({
+        name: c.name.replace(/^skill:/, ""),
+        description: c.description,
+      }));
+    skillNames = skillCommands.map((c) => c.name);
+
+    // Stack skill autocomplete on top of the built-in provider.
+    // addAutocompleteProvider takes a wrapper callback: (current) => provider.
+    ctx.ui.addAutocompleteProvider((current) => ({
+      triggerCharacters: ["$"],
+      async getSuggestions(lines, cursorLine, cursorCol, options) {
+        const textBeforeCursor = (lines[cursorLine] || "").slice(0, cursorCol);
+        const dollarPrefix = extractDollarPrefix(textBeforeCursor);
+
+        if (!dollarPrefix || dollarPrefix.includes(" ")) {
+          return current.getSuggestions(lines, cursorLine, cursorCol, options);
+        }
+
+        const query = dollarPrefix.slice(1);
+        const items = skillCommands.map((c) => ({
+          name: c.name,
+          description: c.description,
+        }));
+        const filtered = fuzzyFilter(items, query, (i) => i.name).map((i) => ({
+          value: i.name,
+          label: i.name,
+          ...(i.description && { description: i.description }),
+        }));
+        return filtered.length
+          ? { items: filtered, prefix: dollarPrefix }
+          : current.getSuggestions(lines, cursorLine, cursorCol, options);
+      },
+      // biome-ignore lint/complexity/useMaxParams: AutocompleteProvider interface
+      applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
+        if (prefix.startsWith("$")) {
+          const line = lines[cursorLine] || "";
+          const before = line.slice(0, cursorCol - prefix.length);
+          const after = line.slice(cursorCol);
+          const newLine = `${before}$${item.value} ${after}`;
+          return {
+            lines: [...lines.slice(0, cursorLine), newLine, ...lines.slice(cursorLine + 1)],
+            cursorLine,
+            cursorCol: before.length + 1 + item.value.length + 1,
+          };
+        }
+        return current.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
+      },
+      shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
+        return current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ?? true;
+      },
+    }));
+  });
+
+  // Transform $skill-name → /skill:skill-name before agent processing
+  pi.on("input", (event) => {
+    const text = event.text.trim();
+
+    // Find all $skill-name tokens and replace them
+    const transformed = text.replace(/(?:^|(?<=\s))\$([a-z0-9][-a-z0-9]*)/g, (_match, name) => {
+      return skillNames.includes(name) ? `/skill:${name}` : _match;
+    });
+
+    if (transformed !== text) {
+      return { action: "transform" as const, text: transformed };
+    }
+    return { action: "continue" as const };
+  });
+}