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

package/README.md

@@ -29,7 +29,7 @@ filter in `~/.pi/agent/settings.json` using the repository-relative path:
 ```
 
 From this package checkout, load the source directly with
-`pi -e ./src/index.ts`. Requires Node `>=22.19.0` and Pi `>=0.85.1`.
+`pi -e ./src/index.ts`. Requires Node `>=22.19.0` and Pi `>=0.99.0`.
 
 ## Configuration
 
@@ -164,7 +164,7 @@ example:
   "minimalSubagents": {
     "baseToolset": ["context_*"],
     "readToolset": ["read", "grep", "find", "ls"],
-    "modifyToolset": ["bash", "edit", "write", "lsp", "dap"]
+    "modifyToolset": ["bash", "edit", "write", "lsp_*", "dap_*"]
   }
 }
 ```
@@ -203,18 +203,26 @@ Pattern expansion happens when a Child Agent is created. `/reload` applies
 settings to future launches without changing existing Launch Contracts. If a tool
 in an existing contract later disappears, normal restoration dependency checks
 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
+not tool operations: granting a multifunction tool grants that tool's available
+operations, regardless of preset name.
+
+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
 
@@ -252,7 +260,11 @@ tools while the Launch Contract continues to record the originally granted
 capability names.
 
 `agent_message` reports whether a message was delivered through an active
-parent wait, queued for the recipient, or failed. `subagent_wait` can return an
+parent wait, queued for the recipient, or failed. A failed delivery and a
+partially failed `subagent_delete` return an error result (`isError: true`) that
+still carries the declared structured output, so the model sees an error while
+codemode scripts receive the `failures` or `error` data instead of a data-less
+rejection. `subagent_wait` can return an
 intermediate Wait Event containing a Coordination Message before the child turn
 settles. That event claims only its message, so later unconsumed messages and the
 terminal result retain automatic fallback. If the turn has already settled, one
@@ -315,6 +327,10 @@ process-local fork handoff is lost, recovery reads only the destination's
 selected branch and proceeds only when its canonical `parentSession` proves the
 source file; it never substitutes the source session's newer head.
 
+## Tool annotations
+
+The coordinator tools declare MCP-style `annotations`, which Pi reports through `pi.getAllTools()` for permission extensions and does not send to model providers. `subagent` is destructive and open-world because a Child Agent can use any tool it is granted. `agent_message` is not read-only but is non-destructive and closed-world. `subagent_cancel` is non-destructive and idempotent; `subagent_delete` is destructive and idempotent. `subagent_status` and `subagent_wait` are read-only (`subagent_wait` consumes queued deliveries, so it is not idempotent).
+
 ## Status and TUI
 
 In TUI mode, `/subagents` or `/subagents status` opens a large, centered,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-minimal-subagents",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "private": false,
   "description": "Persistent nested subagents with bounded delegation for Pi",
   "keywords": [
@@ -31,14 +31,14 @@
     "provenance": true
   },
   "dependencies": {
-    "@ian-pascoe/pi-utils": "^0.3.0",
+    "@ian-pascoe/pi-utils": "^0.3.1",
     "minimatch": "^10.2.6"
   },
   "peerDependencies": {
-    "@earendil-works/pi-agent-core": "*",
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
+    "@earendil-works/pi-agent-core": ">=0.99.0",
+    "@earendil-works/pi-ai": ">=0.99.0",
+    "@earendil-works/pi-coding-agent": ">=0.99.0",
+    "@earendil-works/pi-tui": ">=0.99.0",
     "typebox": "*"
   },
   "engines": {

package/src/minimal-subagents-child-resources.ts

@@ -1,6 +1,17 @@
-import { dirname } from "node:path";
-import * as piCodingAgent from "@earendil-works/pi-coding-agent";
-import { DefaultResourceLoader, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  createCodemodeExtension,
+  createMcpExtension,
+  createToolSearchExtension,
+  DefaultResourceLoader,
+  type ExtensionFactory,
+  getPackageDir,
+  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 +28,52 @@ 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. */
+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 {
+  const path = join(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 in Pi's order, so children match the root's built-in surface. */
 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 }] : [],
-  );
+  return [
+    ...llamaExtension(),
+    {
+      name: "codemode",
+      factory: createCodemodeExtension({ models: CHILD_CODEMODE_MODELS }),
+      builtin: true,
+      replaceable: true,
+    },
+    { name: "tool-search", factory: createToolSearchExtension(), builtin: true, replaceable: true },
+    { name: "mcp", factory: createMcpExtension(), builtin: true, replaceable: true },
+  ];
 }
 
 function createDefaultChildResourceLoaderOptions(

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

@@ -130,13 +130,31 @@ function structuredToolResult<TDetails extends CoordinatorToolResultDetails>(
   };
 }
 
-function failedStructuredOperation(prefix: string, result: DeleteResult): never {
-  const json = JSON.stringify(result);
-  const truncated = truncateHead(json, {
-    maxBytes: DEFAULT_MAX_BYTES,
-    maxLines: DEFAULT_MAX_LINES,
-  });
-  throw new Error(withTroubleshootingHint(`${prefix}: ${truncated.content}`));
+/**
+ * Report a failed operation that still carries declared output: the model sees an error and
+ * codemode scripts receive `structuredContent` instead of a data-less rejection.
+ */
+function failedStructuredToolResult<TDetails extends CoordinatorToolResultDetails>(
+  prefix: string,
+  result: TDetails,
+  options: { troubleshootingHint: boolean },
+): AgentToolResult<TDetails> & { isError: true } {
+  const success = structuredToolResult(result);
+  const text = `${prefix}:\n${textOf(success)}`;
+  return {
+    ...success,
+    content: [
+      {
+        type: "text" as const,
+        text: options.troubleshootingHint ? withTroubleshootingHint(text) : text,
+      },
+    ],
+    isError: true,
+  };
+}
+
+function textOf(result: AgentToolResult<unknown>): string {
+  return result.content.map((part) => (part.type === "text" ? part.text : "")).join("\n");
 }
 
 function callerSourceTurnId(
@@ -164,6 +182,12 @@ export function createCoordinatorToolDefinitions(
     promptSnippet: "Spawn a persistent child with a prefix-free root-child ID",
     promptGuidelines: modelRolePromptGuidelines,
     parameters: options.schemas.subagent,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true,
+    },
     async execute(_toolCallId, parameters, _signal, _onUpdate, context) {
       return runCoordinatorToolActivity(options, async () => {
         const result = await options.coordinator.spawn(
@@ -191,6 +215,12 @@ export function createCoordinatorToolDefinitions(
       "Send one mid-turn coordination message to a direct parent, direct sibling, or direct child. The result says whether it was delivered through an active wait, queued for the recipient, or failed.",
     promptSnippet: "Coordinate required mid-turn action with one adjacent agent",
     parameters: options.schemas.agent_message,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false,
+    },
     async execute(toolCallId, parameters) {
       return runCoordinatorToolActivity(options, async () => {
         const result = await options.coordinator.sendAgentMessage(
@@ -201,7 +231,12 @@ export function createCoordinatorToolDefinitions(
           },
           callerSourceTurnId(options.coordinator, options.callerId, toolCallId),
         );
-        return structuredToolResult(result);
+        return result.disposition === "failed"
+          ? failedStructuredToolResult("Minimal subagents message delivery failed", result, {
+              // The coordinator already appends the hint to `error`.
+              troubleshootingHint: false,
+            })
+          : structuredToolResult(result);
       });
     },
     ...createCoordinatorToolRendering("agent_message"),
@@ -214,6 +249,12 @@ export function createCoordinatorToolDefinitions(
       "Wait for one direct child's oldest observable turn, or select an exact retained turn_id. An active child may first return event=message; later unconsumed items still fall back automatically. An already settled turn returns event=turn once with queued messages in messages. Timeout returns event=timeout with detailed child status and never cancels the child.",
     promptSnippet: "Wait for one direct child's exact turn",
     parameters: options.schemas.subagent_wait,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false,
+    },
     async execute(_toolCallId, parameters, signal, onUpdate) {
       const startedAt = Date.now();
       const updateWaitingResult = () =>
@@ -262,6 +303,12 @@ export function createCoordinatorToolDefinitions(
       "List direct children when agent_id is omitted, or inspect one direct child's launch contract, result, usage, dependencies, and bounded recent activity including message text and reasoning.",
     promptSnippet: "Inspect direct child state",
     parameters: options.schemas.subagent_status,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
     async execute(_toolCallId, parameters) {
       return runCoordinatorToolActivity(options, () =>
         structuredToolResult(options.coordinator.status(options.callerId, parameters.agent_id)),
@@ -277,6 +324,12 @@ export function createCoordinatorToolDefinitions(
       "Abort active work for one direct child while preserving sessions for later continuation. Recursive cancellation includes its subtree and defaults to true.",
     promptSnippet: "Cancel active subagent turns without deleting sessions",
     parameters: options.schemas.subagent_cancel,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
     async execute(_toolCallId, parameters) {
       return runCoordinatorToolActivity(options, async () =>
         structuredToolResult(
@@ -298,6 +351,12 @@ export function createCoordinatorToolDefinitions(
       "Delete one direct child's persistent session and retain durable ID tombstones. Recursive deletion includes its subtree and defaults to true.",
     promptSnippet: "Delete subagent sessions and tombstone their IDs",
     parameters: options.schemas.subagent_delete,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
     async execute(_toolCallId, parameters) {
       return runCoordinatorToolActivity(options, async () => {
         const result = await options.coordinator.delete(
@@ -309,7 +368,9 @@ export function createCoordinatorToolDefinitions(
           options.onAttention?.(
             `Minimal subagents deletion partially failed for ${parameters.agent_id}`,
           );
-          failedStructuredOperation("Minimal subagents deletion partially failed", result);
+          return failedStructuredToolResult("Minimal subagents deletion partially failed", result, {
+            troubleshootingHint: true,
+          });
         }
         return structuredToolResult(result);
       });