@ian-pascoe/pi-termctrl 0.0.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-termctrl",
-  "version": "0.0.0",
+  "version": "0.1.1",
   "private": false,
   "description": "Interactive Terminals, Background jobs, and a /ps panel for Pi.",
   "keywords": [
@@ -33,10 +33,6 @@
     "access": "public",
     "provenance": true
   },
-  "scripts": {
-    "test": "vitest run --config ../../vitest.config.ts --root .",
-    "typecheck": "tsc --noEmit -p tsconfig.json"
-  },
   "dependencies": {
     "@kitlangton/terminal-control": "^1.2.1"
   },
@@ -55,5 +51,9 @@
     "skills": [
       "./skills"
     ]
+  },
+  "scripts": {
+    "test": "vitest run --config ../../vitest.config.ts --root .",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
   }
-}
+}

package/skills/pi-termctrl/SKILL.md

@@ -2,6 +2,7 @@
 name: pi-termctrl
 description: Configure or diagnose Pi Termctrl when Terminal tools are missing, the bash replacement conflicts with another extension, Background jobs misbehave, or termctrl settings need changing.
 license: MIT
+disable-model-invocation: true
 ---
 
 # Pi Termctrl

package/src/pi-termctrl-extension.ts

@@ -129,7 +129,7 @@ class PiTermctrlController {
     const commandPrefix = settingsManager.getShellCommandPrefix();
     if (this.binary.kind === "missing") {
       context.ui.notify(
-        `Pi Termctrl: Terminal tools are unavailable: ${this.binary.reason}`,
+        `Pi Termctrl: Terminal tools are unavailable: ${this.binary.reason}\nRun /skill:pi-termctrl to diagnose.`,
         "warning",
       );
       if (settings.replaceBash) this.registerManagementTools();

package/src/termctrl-registry.ts

@@ -7,6 +7,7 @@ import type {
   TerminalLaunchRequest,
 } from "./terminal-driver.js";
 import { isDriverGone } from "./terminal-driver.js";
+import { TROUBLESHOOTING_HINT } from "./troubleshooting-skill.js";
 import type { TerminalViewport } from "./pi-termctrl-settings.js";
 
 /** The `globalThis` key every registry version shares. Its value always satisfies {@link RegistrySlot}. */
@@ -379,7 +380,7 @@ export class TermctrlRegistry {
         cwd: request.cwd,
         viewport: request.viewport,
       };
-      let slot = await this.ensureDriver();
+      let slot = await this.startDriver();
       let handle: TerminalHandle;
       try {
         handle = await slot.driver.launch(launch);
@@ -387,7 +388,7 @@ export class TermctrlRegistry {
         const error = cause instanceof Error ? cause : new Error(String(cause));
         if (!isDriverGone(error)) throw error;
         this.driverDied(slot.generation);
-        slot = await this.ensureDriver();
+        slot = await this.startDriver();
         handle = await slot.driver.launch(launch);
       }
       const entry: TerminalEntry = {
@@ -420,6 +421,16 @@ export class TermctrlRegistry {
     }
   }
 
+  /** Ensure a driver, pointing the agent at the troubleshooting Skill when none can start. */
+  private async startDriver(): Promise<DriverSlot> {
+    try {
+      return await this.ensureDriver();
+    } catch (cause) {
+      const error = cause instanceof Error ? cause : new Error(String(cause));
+      throw new Error(`${error.message}\n\n${TROUBLESHOOTING_HINT}`, { cause });
+    }
+  }
+
   private async ensureDriver(): Promise<DriverSlot> {
     if (this.state.driver !== undefined) return this.state.driver;
     if (this.state.driverStarting !== undefined) return this.state.driverStarting;

package/src/terminal-tools.ts

@@ -21,6 +21,7 @@ import { describeExitStatus } from "./exit-notification.js";
 import { termctrlTemporaryDirectory } from "./termctrl-driver.js";
 import type { TerminalViewport } from "./pi-termctrl-settings.js";
 import type { TerminalExit, TerminalSnapshot } from "./terminal-driver.js";
+import { TROUBLESHOOTING_HINT } from "./troubleshooting-skill.js";
 
 /** Screen quiet period that settles a Terminal. */
 export const QUIET_MS = 250;
@@ -480,7 +481,10 @@ async function driveTerminal<T>(
   } catch (cause) {
     const error = cause instanceof Error ? cause : new Error(String(cause));
     if (registry.reportTerminalError(entry, error)) {
-      throw new Error(`${entry.id} was lost because the termctrl driver exited`, { cause });
+      throw new Error(
+        `${entry.id} was lost because the termctrl driver exited\n\n${TROUBLESHOOTING_HINT}`,
+        { cause },
+      );
     }
     throw error;
   } finally {

package/src/troubleshooting-skill.ts

@@ -0,0 +1,9 @@
+import { fileURLToPath } from "node:url";
+
+/** Absolute path of this package's user-invoked troubleshooting Skill. */
+export const TROUBLESHOOTING_SKILL_PATH = fileURLToPath(
+  new URL("../skills/pi-termctrl/SKILL.md", import.meta.url),
+);
+
+/** Model-facing pointer appended to failures this package's Skill diagnoses. */
+export const TROUBLESHOOTING_HINT = `For diagnosis, read the pi-termctrl troubleshooting Skill at ${TROUBLESHOOTING_SKILL_PATH}.`;