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

package/README.md

@@ -206,15 +206,23 @@ still apply; the saved grant is not silently rewritten. Toolsets configure names
 not tool operations: granting `lsp`, `dap`, or another multifunction tool grants
 that tool's available operations, regardless of preset name.
 
-Child Agents load Pi's built-in `codemode`, `tool-search`, and `mcp` extensions
-unless settings disable them (`-builtin:<name>`); each child connects its own MCP
-servers. A tool's exposure still decides whether it is declared or reachable only
+Child Agents load Pi's built-in `llama.cpp`, `codemode`, `tool-search`, and `mcp`
+extensions unless settings disable them (`-builtin:<name>`); each child connects
+its own MCP servers. Pi does not export the llama.cpp factory, so children load it
+from Pi's installed `dist/extensions/llama/index.js`; when that file is absent, a
+llama.cpp launch model is reported as a missing dependency. Child `codemode`
+scripts get no `models` API, so they cannot call models outside the Launch
+Contract. A tool's exposure still decides whether it is declared or reachable only
 through `codemode` or `tool_search`. Granted `codemode`- or `deferred`-exposed
 tools are callable but not declared, so a child that needs them also needs
 `codemode` or `tool_search` in its grant. Ungranted tools are unreachable in the
 child. MCP tools are checked at launch only by name, because children register
 them after connecting; a tool whose server disappeared fails when called. Closing
-a child runtime shuts its extensions down, closing its MCP connections.
+a child runtime shuts its extensions down, closing its MCP connections. A reopened
+child re-declares the tools it last declared itself, including tools loaded
+through `tool_search`; as in Pi, a tool that registers only after the child opens,
+such as an MCP tool, is not re-declared. Declarations inherited from the parent's
+context are not restored.
 
 ## Capabilities and persistence
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-minimal-subagents",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "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-child-resources.ts

@@ -1,6 +1,14 @@
-import { dirname } from "node:path";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
 import * as piCodingAgent from "@earendil-works/pi-coding-agent";
-import { DefaultResourceLoader, SettingsManager } from "@earendil-works/pi-coding-agent";
+import {
+  DefaultResourceLoader,
+  type ExtensionFactory,
+  SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
 import { canonicalPath } from "./minimal-subagents-paths.js";
 import type { ProjectContextMode } from "./minimal-subagents-types.js";
 
@@ -17,19 +25,58 @@ type InlineExtension = NonNullable<
   ConstructorParameters<typeof DefaultResourceLoader>[0]["extensionFactories"]
 >[number];
 
-/** Pi's exported built-in extensions (Pi 0.99+); older hosts have none, so neither do children. */
+// SAFETY: Older Pi hosts lack these exports; the namespace yields undefined rather than failing.
+const sdk = piCodingAgent as Partial<typeof piCodingAgent>;
+
+const ExtensionModuleSchema = Type.Object({
+  default: Type.Function([Type.Unknown()], Type.Unknown()),
+});
+
+/** Built-in extension name, and the provider ID it registers. */
+const LLAMA = "llama.cpp";
+
+/** Pi ships a file-backed llama.cpp factory but does not export it; undefined when it is absent. */
+function piLlamaExtensionPath(): string | undefined {
+  if (!sdk.getPackageDir) return undefined;
+  const path = join(sdk.getPackageDir(), "dist", "extensions", "llama", "index.js");
+  return existsSync(path) ? path : undefined;
+}
+
+function llamaExtension(): InlineExtension[] {
+  const path = piLlamaExtensionPath();
+  if (!path) return [];
+  const factory: ExtensionFactory = async (pi) => {
+    const module: unknown = await import(pathToFileURL(path).href);
+    if (!Value.Check(ExtensionModuleSchema, module))
+      throw new Error(`Pi's built-in llama.cpp file has no extension factory (${path})`);
+    await module.default(pi);
+  };
+  return [{ name: LLAMA, factory, builtin: true }];
+}
+
+/** Whether a child can register a provider the root has; llama.cpp needs Pi's unexported factory. */
+export function childProviderAvailable(provider: string): boolean {
+  return provider !== LLAMA || piLlamaExtensionPath() !== undefined;
+}
+
+/** Child scripts must not call models outside their Launch Contract. */
+export const CHILD_CODEMODE_MODELS = false;
+
+/** Pi's built-in extensions (Pi 0.99+) in Pi's order; older hosts have none, so neither do children. */
 export function childBuiltinExtensions(): InlineExtension[] {
-  // SAFETY: Older Pi hosts lack these exports; the namespace yields undefined rather than failing.
-  const sdk = piCodingAgent as Partial<typeof piCodingAgent>;
-  return (
-    [
-      ["codemode", sdk.createCodemodeExtension],
-      ["tool-search", sdk.createToolSearchExtension],
-      ["mcp", sdk.createMcpExtension],
-    ] as const
-  ).flatMap(([name, create]) =>
-    create ? [{ name, factory: create(), builtin: true, replaceable: true }] : [],
-  );
+  const createCodemode = sdk.createCodemodeExtension;
+  return [
+    ...llamaExtension(),
+    ...(
+      [
+        ["codemode", createCodemode && (() => createCodemode({ models: CHILD_CODEMODE_MODELS }))],
+        ["tool-search", sdk.createToolSearchExtension],
+        ["mcp", sdk.createMcpExtension],
+      ] as const
+    ).flatMap(([name, create]) =>
+      create ? [{ name, factory: create(), builtin: true, replaceable: true }] : [],
+    ),
+  ];
 }
 
 function createDefaultChildResourceLoaderOptions(

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-sessions.ts

@@ -3,7 +3,7 @@ import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { unlink } from "node:fs/promises";
 import { resolve } from "node:path";
 import type { AgentMessage, ThinkingLevel } from "@earendil-works/pi-agent-core";
-import type { Model, Usage } from "@earendil-works/pi-ai";
+import { getCurrentSystemMessage, type Model, type Usage } from "@earendil-works/pi-ai";
 import { clampThinkingLevel } from "@earendil-works/pi-ai/compat";
 import {
   AgentSession,
@@ -34,7 +34,11 @@ import {
   DEFAULT_MAX_SUBAGENT_DEPTH,
   getSubagentDepth,
 } from "./minimal-subagents-capabilities.js";
-import { createChildResourceLoader } from "./minimal-subagents-child-resources.js";
+import {
+  CHILD_CODEMODE_MODELS,
+  childProviderAvailable,
+  createChildResourceLoader,
+} from "./minimal-subagents-child-resources.js";
 import {
   CHILD_IDENTITY_ENTRY_TYPE,
   FORK_CLONE_ENTRY_TYPE,
@@ -164,6 +168,20 @@ function installChildToolCapabilityPolicy(
   session.setActiveToolsByName(session.getActiveToolNames().filter((name) => !isScriptOnly(name)));
 }
 
+/**
+ * Passing `tools` skips Pi's transcript restore, so re-declare the tools a reopened child last
+ * declared itself (such as through `tool_search`); the capability policy still clamps them.
+ * Declarations inherited from the parent predate the child and are not restored.
+ */
+function restoreChildDeclaredTools(session: AgentSession, agent: PersistedAgent): void {
+  const { messages } = session.sessionManager.buildSessionContext();
+  const createdAt = Date.parse(agent.created_at);
+  if (!messages.some((message) => message.role === "system" && message.timestamp >= createdAt))
+    return;
+  const declared = getCurrentSystemMessage(messages);
+  if (declared) session.setActiveToolsByName((declared.toolsAdded ?? []).map(({ name }) => name));
+}
+
 /** Moves one verified child session file to trash and reports command unavailability. */
 export interface SessionFileTrashCapability {
   moveSessionFile(sessionFile: string): Promise<Error | undefined>;
@@ -201,6 +219,8 @@ export interface PiAgentSessionFactoryOptions {
       agentDir: string;
       extensions: readonly Pick<Extension, "path" | "resolvedPath" | "sourceInfo" | "hidden">[];
       flagValues: ReadonlyMap<string, boolean | string>;
+      /** Whether child codemode scripts get the `models` API, so observers can reproduce it. */
+      codemodeModels: boolean;
     },
   ) => ChildSessionObserver | undefined;
 }
@@ -1109,9 +1129,12 @@ export class PiAgentSessionFactory implements AgentSessionFactory {
     requireEligibleModel: boolean,
   ): Promise<string[]> {
     const missing: string[] = [];
-    if (!this.modelById.has(agent.launch_contract.model)) missing.push(agent.launch_contract.model);
+    const model = this.modelById.get(agent.launch_contract.model);
+    if (!model) missing.push(agent.launch_contract.model);
     else if (requireEligibleModel && !this.eligibleModelIds.has(agent.launch_contract.model)) {
       missing.push(agent.launch_contract.model);
+    } else if (!childProviderAvailable(model.provider)) {
+      missing.push(agent.launch_contract.model);
     }
     const discoveredTools = await this.discoverChildToolNames(agent);
     for (const toolName of agent.launch_contract.ordinary_tools) {
@@ -1217,6 +1240,7 @@ export class PiAgentSessionFactory implements AgentSessionFactory {
       throw new Error(`Minimal subagents child tool loading failed: ${missingTools.join(", ")}`);
     }
     installChildToolCapabilityPolicy(session, allowedToolNames, runtimeToolAdapters);
+    restoreChildDeclaredTools(session, agent);
     await session.bindExtensions({ mode: "print" });
     const registeredNames = new Set(session.getAllTools().map((tool) => tool.name));
     const missingCoordinatorTools = coordinatorTools
@@ -1244,6 +1268,7 @@ export class PiAgentSessionFactory implements AgentSessionFactory {
             hidden,
           })),
         flagValues: new Map(resourceLoader.getExtensions().runtime.flagValues),
+        codemodeModels: CHILD_CODEMODE_MODELS,
       }),
     );
   }

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}`;
+}