@ian-pascoe/pi-minimal-subagents 0.10.0 → 0.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-minimal-subagents",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "private": false,
   "description": "Persistent nested subagents with bounded delegation for Pi",
   "keywords": [

package/skills/pi-minimal-subagents/SKILL.md

@@ -2,6 +2,7 @@
 name: pi-minimal-subagents
 description: Configure or diagnose Pi Minimal Subagents for Subagent Access, missing Coordinator Tools, spawn, capability, delivery, wait, restore, reload, or fork failures.
 license: MIT
+disable-model-invocation: true
 ---
 
 # Pi Minimal Subagents

package/src/minimal-subagents-coordinator.ts

@@ -34,6 +34,7 @@ import {
   type DeliveryLedger,
   type DeliveryLedgerTransition,
 } from "./minimal-subagents-delivery-ledger.js";
+import { withTroubleshootingHint } from "./troubleshooting-skill.js";
 import { addCoordinatorMessageEnvelope } from "./minimal-subagents-message-envelope.js";
 import { unavailableAgent } from "./minimal-subagents-sessions.js";
 import { createRegistryEvent } from "./minimal-subagents-registry.js";
@@ -264,7 +265,9 @@ export class MinimalSubagentsCoordinator {
       const requiredMissing = missingDependencies.filter((name) => !optionalMissing.has(name));
       if (requiredMissing.length > 0) {
         throw new Error(
-          `Minimal subagents launch dependencies unavailable: ${requiredMissing.join(", ")}`,
+          withTroubleshootingHint(
+            `Minimal subagents launch dependencies unavailable: ${requiredMissing.join(", ")}`,
+          ),
         );
       }
       if (optionalMissing.size > 0) {
@@ -381,7 +384,7 @@ export class MinimalSubagentsCoordinator {
         agent_id: targetId,
         message_id: messageId,
         disposition: "failed",
-        error: deliveryError,
+        error: withTroubleshootingHint(deliveryError),
       };
     }
   }
@@ -925,7 +928,7 @@ export class MinimalSubagentsCoordinator {
         turn_id: turnId,
         status: "failed",
         output: "",
-        error: error instanceof Error ? error.message : String(error),
+        error: withTroubleshootingHint(error instanceof Error ? error.message : String(error)),
       });
     }
   }
@@ -1366,7 +1369,7 @@ export class MinimalSubagentsCoordinator {
             turn_id: turnId,
             status: "failed",
             output: "",
-            error: cause instanceof Error ? cause.message : String(cause),
+            error: withTroubleshootingHint(cause instanceof Error ? cause.message : String(cause)),
           });
         }
       });
@@ -1634,12 +1637,16 @@ export class MinimalSubagentsCoordinator {
     const agent = this.requireAgent(agentId);
     if (agent.availability === "unavailable") {
       throw new Error(
-        agent.unavailable_reason ?? `Minimal subagents ${operation}: ${agentId} is unavailable`,
+        withTroubleshootingHint(
+          agent.unavailable_reason ?? `Minimal subagents ${operation}: ${agentId} is unavailable`,
+        ),
       );
     }
     if (agent.clone_error || !agent.session_file) {
       throw new Error(
-        `Minimal subagents ${operation}: ${agent.clone_error ?? `${agentId} has no child session`}`,
+        withTroubleshootingHint(
+          `Minimal subagents ${operation}: ${agent.clone_error ?? `${agentId} has no child session`}`,
+        ),
       );
     }
     return agent;

package/src/minimal-subagents-extension.ts

@@ -62,6 +62,7 @@ import {
   type RuntimeToolAdapter,
   unavailableAgent,
 } from "./minimal-subagents-sessions.js";
+import { withTroubleshootingHint } from "./troubleshooting-skill.js";
 import { shutdownMinimalSubagentsSession } from "./minimal-subagents-shutdown.js";
 import { writeMinimalSubagentsEnabled } from "./minimal-subagents-settings-writer.js";
 import {
@@ -164,7 +165,10 @@ export function reachableToolNames(
 }
 
 function rootCallerSnapshot(pi: ExtensionAPI, context: ExtensionContext): CallerSnapshot {
-  if (!context.model) throw new Error("Minimal subagents spawn: root has no effective model");
+  if (!context.model)
+    throw new Error(
+      withTroubleshootingHint("Minimal subagents spawn: root has no effective model"),
+    );
   return {
     messages: currentConversationMessages(context),
     model: `${context.model.provider}/${context.model.id}`,

package/src/minimal-subagents-tools.ts

@@ -10,6 +10,7 @@ import {
   type ToolRenderResultOptions,
 } from "@earendil-works/pi-coding-agent";
 import type { MinimalSubagentsCoordinator } from "./minimal-subagents-coordinator.js";
+import { withTroubleshootingHint } from "./troubleshooting-skill.js";
 import type { MinimalSubagentsModelRole } from "./minimal-subagents-config.js";
 import {
   renderCoordinatorToolCall,
@@ -135,7 +136,7 @@ function failedStructuredOperation(prefix: string, result: DeleteResult): never
     maxBytes: DEFAULT_MAX_BYTES,
     maxLines: DEFAULT_MAX_LINES,
   });
-  throw new Error(`${prefix}: ${truncated.content}`);
+  throw new Error(withTroubleshootingHint(`${prefix}: ${truncated.content}`));
 }
 
 function callerSourceTurnId(

package/src/troubleshooting-skill.ts

@@ -0,0 +1,14 @@
+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-minimal-subagents/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-minimal-subagents troubleshooting Skill at ${TROUBLESHOOTING_SKILL_PATH}.`;
+
+/** Append the troubleshooting Skill pointer to a model-facing configuration or runtime failure. */
+export function withTroubleshootingHint(message: string): string {
+  return `${message}\n\n${TROUBLESHOOTING_HINT}`;
+}