pi-skillful 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,25 @@ This project follows the spirit of [Keep a Changelog](https://keepachangelog.com
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-09
+
+### Fixed
+
+- Read the current theme when rendering session-toggle borders and fit the complete border at very narrow widths. Extend editor composition coverage for paste, padding, indicators, and disposal.
+
+### Changed
+
+- Update skill visibility and session toggles through Pi's structured prompt API instead of replacing the rendered system prompt. Preserve unrelated sections and deliberate full-prompt overrides.
+- Update the shared Pi development and contract-test baseline to 1.1.0; require Node.js >=22.19.0 to match the host runtime. Pi remains a host-supplied peer dependency.
+- Share install telemetry mechanics through `@mocito/install-telemetry` while preserving Pi-specific settings and state paths.
+
+### Fixed
+
+- Apply visibility settings to Pi 1.1.0's wrapped skills section, including when file readers are hidden behind codemode.
+- Keep frontmatter and earlier extensions' visibility restrictions when session toggle slots are active.
+- Restore hidden-skill startup colors on Pi 1.x while preserving theme changes, expanded resource paths, and reloads.
+- Let `enableInstallTelemetry: false` override an enabled `PI_TELEMETRY` environment flag.
+
 ## [0.4.0] - 2026-07-28
 
 ### Added

package/CONTRIBUTING.md

@@ -33,6 +33,14 @@ pi -e /path/to/pi-mono/packages/pi-skillful
 
 ## Pull request checklist
 
+For prompt changes, also run the shared real-session contracts from the monorepo root:
+
+```bash
+node --import tsx --test tests/structured-prompts.test.mjs
+```
+
+These load both Skillful and Scout through Pi's SDK, inspect serialized provider requests and session history, and exercise the toggle editor wrapper. They use disposable profiles, synthetic credentials, temporary reference directories, and mocked provider responses; they do not use a live model or existing user settings. Coverage includes extension load order, explicit prompt overrides, hidden skill invocation, codemode, reload, resume, fork/tree navigation, and providers that collapse system updates.
+
 Before opening a pull request:
 
 - Run `npm run check`.
@@ -52,3 +60,9 @@ Before opening a pull request:
 ## Code of conduct
 
 This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).
+## Pi 1.1.0 terminal audit
+
+From the monorepo root, run `node --import tsx --test tests/tui-contracts.test.mjs`
+alongside the package tests. `tests/TUI_AUDIT.md` records coverage, known host
+limitations, and the disposable-profile physical-terminal acceptance procedure.
+The startup patch remains isolated; no unreleased cursor API is required.

package/README.md

@@ -102,6 +102,19 @@ Configured slots appear on the prompt editor's top border as `N skill-name`. Pro
 
 On app startup, non-hidden skills are active and hidden skills are inactive. Within a running Pi process, `/new` preserves the current toggle state for the new session. Resuming, forking, cloning, reloading, or restarting Pi resets toggle state from settings. Inline `/skill:name` invocation remains explicit and works even when that skill is inactive. Skills bundled in Pi packages are never modified by these toggles.
 
+### Prompt updates and extension composition
+
+Toggle-border colors follow the current theme without another toggle or reload.
+At very narrow widths, the complete border is clipped to the available columns.
+
+Visibility and toggles use Pi's structured `systemPromptOptions.skills` API (Pi 1.1.0 or newer), not text replacement of the full system prompt. Pi records skill-list changes in the session transcript, alongside independent updates from other extensions such as Scout.
+
+An active slot can lift a restriction from `skillful.hiddenSkills`, but does not clear `disable-model-invocation` frontmatter or a restriction applied by an earlier prompt handler. Later handlers see the updated list and can apply their own policy. Package-bundled skills remain outside Skillful's visibility controls and toggle slots.
+
+A deliberate full-prompt override from another extension (`systemPrompt` or `forceSystemPrompt`) takes precedence. Skillful updates the structured skill list but does not rewrite that override; its author controls any skill descriptions embedded in the replacement text. Explicit skill invocation remains available.
+
+Structured changes let Pi update individual prompt sections. Providers that cannot accept mid-conversation system changes may still need a full prompt checkpoint; cache savings are not guaranteed.
+
 ## Installation
 
 Install from npm:
@@ -148,7 +161,7 @@ This package is source-distributed. Pi loads the TypeScript extensions directly
 
 Requirements:
 
-- Node.js >= 20.6.0
+- Node.js >= 22.19.0
 - npm for local development commands
 
 Common commands:

package/SECURITY.md

@@ -21,6 +21,8 @@ The maintainer will acknowledge reports as soon as practical and coordinate disc
 
 `pi-skillful` is a Pi package. Pi extensions execute with the same permissions as the local user running Pi. Users should review installed Pi packages and only install packages from sources they trust.
 
+At startup, `@mocito/install-telemetry` sends a best-effort install/update ping to the configured telemetry endpoint once per package version unless CI, Pi offline/telemetry settings, or `enableInstallTelemetry: false` disables it. It contains only the package name/version and parsed platform/runtime/architecture; it does not include prompts, paths, configuration values, credentials, or provider responses.
+
 ### Progressive skill loading and trust boundary
 
 `pi-skillful` extends Pi's skill discovery to ancestor directories above the git repository root, loading `.agents/skills/` from every parent directory up to the filesystem root (excluding `~/.agents/skills/`, which Pi already loads globally).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-skillful",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Pi package with skill invocation and visibility improvements.",
   "type": "module",
   "exports": {
@@ -45,9 +45,9 @@
     "@earendil-works/pi-tui": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.80.10",
-    "@earendil-works/pi-tui": "^0.80.10",
-    "@types/node": "^26.1.1",
+    "@earendil-works/pi-coding-agent": "1.1.0",
+    "@earendil-works/pi-tui": "1.1.0",
+    "@types/node": "^26.6.3",
     "typescript": "^7.0.2"
   },
   "scripts": {
@@ -60,6 +60,9 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=20.6.0"
+    "node": ">=22.19.0"
+  },
+  "dependencies": {
+    "@mocito/install-telemetry": "0.1.1"
   }
 }

package/src/extensions/session-skill-toggles.ts

@@ -3,7 +3,6 @@ import {
   type AppKeybinding,
   type ExtensionAPI,
   type KeybindingsManager,
-  type Skill,
   type Theme,
 } from "@earendil-works/pi-coding-agent";
 import type { AutocompleteProvider, EditorComponent, EditorTheme, Focusable, KeyId, TUI } from "@earendil-works/pi-tui";
@@ -16,7 +15,6 @@ import {
   type SkillToggleModifier,
   type SkillToggleSlot,
 } from "../config.js";
-import { replaceSkillsSection } from "../skill-prompt.js";
 import { isTopLevelSkill, listLoadedSkills } from "../skills.js";
 
 const STORE_KEY = Symbol.for("pi-skillful.sessionSkillTogglesStore");
@@ -40,7 +38,7 @@ interface SessionToggleState {
   installedEditor: boolean;
   previousEditorFactory: SkillfulEditorFactory | undefined;
   activeTui: TUI | undefined;
-  theme: Theme | undefined;
+  theme: (() => Theme) | undefined;
   notify: (message: string, type?: "info" | "warning" | "error") => void;
 }
 
@@ -79,7 +77,7 @@ export default function sessionSkillToggles(pi: ExtensionAPI) {
       installedEditor: false,
       previousEditorFactory: undefined,
       activeTui: undefined,
-      theme: ctx.ui.theme,
+      theme: () => ctx.ui.theme,
       notify: ctx.ui.notify.bind(ctx.ui),
     };
 
@@ -90,13 +88,13 @@ export default function sessionSkillToggles(pi: ExtensionAPI) {
   pi.on("before_agent_start", (event) => {
     if (state.slots.length === 0 || !event.systemPromptOptions.skills?.length) return;
 
-    const updatedSkills: Skill[] = event.systemPromptOptions.skills.map((skill) =>
-      isTopLevelSkill(skill) ? { ...skill, disableModelInvocation: !isSkillActive(normalizeSkillName(skill.name)) } : skill,
+    // Active slots lift only Skillful's own restriction, never frontmatter or
+    // restrictions already applied by another prompt handler.
+    event.systemPromptOptions.skills = event.systemPromptOptions.skills.map((skill) =>
+      isTopLevelSkill(skill) && !isSkillActive(normalizeSkillName(skill.name))
+        ? { ...skill, disableModelInvocation: true }
+        : skill,
     );
-
-    const systemPrompt = replaceSkillsSection(event.systemPrompt, updatedSkills);
-    if (!systemPrompt) return;
-    return { systemPrompt };
   });
 
   pi.on("session_shutdown", (event, ctx) => {
@@ -373,7 +371,7 @@ function renderToggleBorder(width: number, borderColor: (text: string) => string
   const fittedContent = truncateToWidth(renderToggleSegments(available), available, "");
   const used = BORDER_PREFIX_WIDTH + visibleWidth(fittedContent) + BORDER_SUFFIX_WIDTH;
   const fill = borderColor("─".repeat(Math.max(0, width - used)));
-  return `${borderColor(BORDER_PREFIX)}${fittedContent}${BORDER_SUFFIX}${fill}`;
+  return truncateToWidth(`${borderColor(BORDER_PREFIX)}${fittedContent}${BORDER_SUFFIX}${fill}`, width, "");
 }
 
 function renderToggleSegments(availableWidth: number): string {
@@ -396,5 +394,5 @@ function renderToggleSegments(availableWidth: number): string {
 }
 
 function stateThemeFg(color: "accent" | "muted", text: string): string {
-  return state.theme?.fg(color, text) ?? text;
+  return state.theme?.().fg(color, text) ?? text;
 }

package/src/extensions/skill-visibility.ts

@@ -1,3 +1,4 @@
+import { stripVTControlCharacters } from "node:util";
 import {
   DynamicBorder,
   getSettingsListTheme,
@@ -19,20 +20,23 @@ import {
   writeProjectSkillfulOverride,
   writeToggleSlots,
 } from "../config.js";
-import { replaceSkillsSection } from "../skill-prompt.js";
 import { isTopLevelSkill, listLoadedSkills, type LoadedSkillInfo } from "../skills.js";
 import { hasActiveSessionSkillToggles, refreshSessionSkillToggles } from "./session-skill-toggles.js";
 const SCOPES: SkillfulScope[] = ["global", "project"];
 const STORE_KEY = Symbol.for("pi-skillful.skillVisibilityStore");
-const STARTUP_PATCH_KEY = Symbol.for("pi-skillful.startupPatchV3");
+// Install the new component contract even after reloading a V3-patched process.
+const STARTUP_PATCH_KEY = Symbol.for("pi-skillful.startupPatchV4");
 
 interface SkillVisibilityStore {
   hiddenSkillsByCwd: Map<string, Set<string>>;
   theme: Theme | null;
+  getTheme?: () => Theme;
 }
 
 interface ExpandableTextLike {
-  getCollapsedText: () => string;
+  getCollapsedText?: () => string;
+  build?: () => string;
+  invalidate?: () => void;
   setText: (text: string) => void;
 }
 
@@ -43,6 +47,7 @@ interface BoxLike {
 interface InteractiveModeLike {
   loadedResourcesContainer?: BoxLike;
   showLoadedResources?: (options?: unknown) => void;
+  getStartupExpansionState?: () => boolean;
   session?: { resourceLoader?: { getSkills: () => { skills: Skill[]; diagnostics: unknown[] } } };
   sessionManager?: { getCwd?: () => string };
 }
@@ -84,6 +89,7 @@ export default function skillVisibility(pi: ExtensionAPI) {
 
   pi.on("session_start", async (_event, ctx) => {
     store.theme = ctx.ui.theme;
+    store.getTheme = () => ctx.ui.theme;
     await refreshHiddenSkillCache(ctx.cwd, ctx.isProjectTrusted());
   });
 
@@ -93,12 +99,9 @@ export default function skillVisibility(pi: ExtensionAPI) {
     const hidden = await refreshHiddenSkillCache(ctx.cwd, ctx.isProjectTrusted());
     if (hidden.size === 0 || !event.systemPromptOptions.skills?.length) return;
 
-    const filteredSkills: Skill[] = event.systemPromptOptions.skills.map((skill) =>
+    event.systemPromptOptions.skills = event.systemPromptOptions.skills.map((skill) =>
       isTopLevelSkill(skill) && hidden.has(skill.name) ? { ...skill, disableModelInvocation: true } : skill,
     );
-    const systemPrompt = replaceSkillsSection(event.systemPrompt, filteredSkills);
-    if (!systemPrompt) return;
-    return { systemPrompt };
   });
 
   pi.registerCommand("skillful", {
@@ -184,7 +187,6 @@ export function installStartupSkillListPatch(
       return result;
     };
 
-    const childrenBefore = this.loadedResourcesContainer?.children.length ?? 0;
     try {
       original.call(this, options);
     } finally {
@@ -193,16 +195,36 @@ export function installStartupSkillListPatch(
 
     if (rawSkillNames.length === 0 || !cwd || !this.loadedResourcesContainer) return;
 
-    const hidden = store.hiddenSkillsByCwd.get(cwd) ?? new Set<string>();
-    const children = this.loadedResourcesContainer.children;
-    for (let index = childrenBefore; index < children.length; index++) {
-      const child = children[index] as ExpandableTextLike | undefined;
+    const colorized = () => buildColorizedSkillList(
+      rawSkillNames,
+      store.hiddenSkillsByCwd.get(cwd) ?? new Set<string>(),
+      store.getTheme?.() ?? store.theme,
+    );
+    const collapsedText = buildColorizedSkillList(rawSkillNames, new Set(), null);
+    // Pi clears and rebuilds this container, including during /reload.
+    for (const entry of this.loadedResourcesContainer.children) {
+      const child = entry as ExpandableTextLike | undefined;
+      if (child && typeof child.build === "function") {
+        // Pi 1.x closes over expansion state in ThemedText.build instead of
+        // exposing getCollapsedText. Decorate only the compact skill list;
+        // leave expanded paths and other sections to Pi. Rebuild colors on
+        // invalidation so theme changes never retain captured ANSI strings.
+        const build = child.build;
+        if (!stripVTControlCharacters(build.call(child)).startsWith("[Skills]\n")) continue;
+        child.build = () => {
+          const text = build.call(child);
+          return stripVTControlCharacters(text) === collapsedText ? colorized() : text;
+        };
+        child.invalidate?.();
+        break;
+      }
       if (!child || typeof child.getCollapsedText !== "function") continue;
       if (!child.getCollapsedText().includes("[Skills]")) continue;
 
-      const colorized = buildColorizedSkillList(rawSkillNames, hidden, store.theme);
-      child.getCollapsedText = () => colorized;
-      child.setText(colorized);
+      // Retain the older Pi component contract without collapsing an
+      // initially expanded resource listing.
+      child.getCollapsedText = colorized;
+      if (!this.getStartupExpansionState?.()) child.setText(colorized());
       break;
     }
   };

package/src/install-telemetry.ts

@@ -1,12 +1,11 @@
 import { readFileSync } from "node:fs";
-import { mkdir, writeFile } from "node:fs/promises";
-import { fileURLToPath } from "node:url";
 import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { reportInstallTelemetry as report } from "@mocito/install-telemetry";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 const PACKAGE_NAME = "pi-skillful";
-const INSTALL_TELEMETRY_URL = "https://mocito.dev/api/report-install";
-const INSTALL_TELEMETRY_TIMEOUT_MS = 5000;
+const INSTALL_TELEMETRY_ENDPOINT = "https://mocito.dev/api/report-install";
 const CI_ENVIRONMENT_VARIABLES = [
   "APPVEYOR",
   "BITBUCKET_BUILD_NUMBER",
@@ -24,10 +23,6 @@ const CI_ENVIRONMENT_VARIABLES = [
   "VERCEL",
 ];
 
-interface InstallTelemetryState {
-  lastReportedVersion?: string;
-}
-
 interface PiSettingsDocument {
   enableInstallTelemetry?: unknown;
 }
@@ -51,18 +46,15 @@ function isPresentEnvFlag(value: string | undefined): boolean {
   return normalized !== "0" && normalized !== "false" && normalized !== "no";
 }
 
-function isCiEnvironment(): boolean {
-  if (isTruthyEnvFlag(process.env.CI)) return true;
-  return CI_ENVIRONMENT_VARIABLES.some((name) => isPresentEnvFlag(process.env[name]));
-}
-
-function isInstallTelemetryEnabled(): boolean {
-  if (isCiEnvironment()) return false;
-  if (isTruthyEnvFlag(process.env.PI_OFFLINE)) return false;
-  if (process.env.PI_TELEMETRY !== undefined) return isTruthyEnvFlag(process.env.PI_TELEMETRY);
+export function isInstallTelemetryEnabled(env: NodeJS.ProcessEnv = process.env, settingsPath = join(getAgentDir(), "settings.json")): boolean {
+  if (isTruthyEnvFlag(env.CI)) return false;
+  if (CI_ENVIRONMENT_VARIABLES.some((name) => isPresentEnvFlag(env[name]))) return false;
+  if (isTruthyEnvFlag(env.PI_OFFLINE)) return false;
 
-  const settings = readJsonFile(join(getAgentDir(), "settings.json")) as PiSettingsDocument;
-  return settings.enableInstallTelemetry !== false;
+  const settings = readJsonFile(settingsPath) as PiSettingsDocument;
+  if (settings.enableInstallTelemetry === false) return false;
+  if (env.PI_TELEMETRY !== undefined) return isTruthyEnvFlag(env.PI_TELEMETRY);
+  return true;
 }
 
 function getPackageVersion(): string {
@@ -70,35 +62,16 @@ function getPackageVersion(): string {
   return typeof packageJson.version === "string" && packageJson.version.length > 0 ? packageJson.version : "0.0.0";
 }
 
-function getInstallTelemetryUserAgent(version: string): string {
-  const runtimeVersions = process.versions as NodeJS.ProcessVersions & { bun?: string };
-  const runtime = runtimeVersions.bun ? `bun/${runtimeVersions.bun}` : `node/${process.version}`;
-  return `${PACKAGE_NAME}/${version} (${process.platform}; ${runtime}; ${process.arch})`;
-}
-
-async function reportInstallTelemetryAsync(): Promise<void> {
+export function reportInstallTelemetry(): void {
   try {
-    if (!isInstallTelemetryEnabled()) return;
-
-    const version = getPackageVersion();
-    const extensionsDir = join(getAgentDir(), "extensions");
-    const statePath = join(extensionsDir, "skillful-install.json");
-    const state = readJsonFile(statePath) as InstallTelemetryState;
-    if (state.lastReportedVersion === version) return;
-
-    await mkdir(extensionsDir, { recursive: true });
-    await writeFile(statePath, `${JSON.stringify({ lastReportedVersion: version }, null, 2)}\n`, "utf8");
-
-    const params = new URLSearchParams({ tool: PACKAGE_NAME, version });
-    await fetch(`${INSTALL_TELEMETRY_URL}?${params.toString()}`, {
-      headers: { "User-Agent": getInstallTelemetryUserAgent(version) },
-      signal: AbortSignal.timeout(INSTALL_TELEMETRY_TIMEOUT_MS),
-    });
+    void report({
+      endpoint: INSTALL_TELEMETRY_ENDPOINT,
+      tool: PACKAGE_NAME,
+      version: getPackageVersion(),
+      statePath: join(getAgentDir(), "extensions", "skillful-install.json"),
+      enabled: isInstallTelemetryEnabled(),
+    }).catch(() => undefined);
   } catch {
-    // Best-effort telemetry: ignore settings, filesystem, and network failures.
+    // Best-effort telemetry: ignore local policy and filesystem failures.
   }
 }
-
-export function reportInstallTelemetry(): void {
-  void reportInstallTelemetryAsync();
-}

package/src/skill-prompt.ts

@@ -1,8 +0,0 @@
-import { formatSkillsForPrompt, type Skill } from "@earendil-works/pi-coding-agent";
-
-export const SKILLS_SECTION_PATTERN = /\n\nThe following skills provide specialized instructions for specific tasks\.[\s\S]*?<\/available_skills>/;
-
-export function replaceSkillsSection(systemPrompt: string, skills: Skill[]): string | undefined {
-  const next = systemPrompt.replace(SKILLS_SECTION_PATTERN, formatSkillsForPrompt(skills));
-  return next === systemPrompt ? undefined : next;
-}