@mystilleef/pi-subagent 0.11.0 → 0.12.0

package/README.md

@@ -25,7 +25,7 @@ pi -e npm:@mystilleef/pi-subagent
 
 ## Features
 
-- **Asynchronous:** Agents run in the background.
+- **Asynchronous:** Agents always run in the background.
 - **Parallel:** Run many agents simultaneously.
 - **Isolated:** Each delegated task receives a separate context window.
 - **Nested:** `Subagents` can spawn other `subagents`.
@@ -108,9 +108,54 @@ YAML `frontmatter` and a Markdown system prompt body.
 
 ### Discovery locations
 
-- User-global agents: `~/.pi/agents/*.md`
+- User-global agents: `~/.pi/agent/agents/*.md`
 - Project-local agents: nearest `.pi/agents/*.md`
 
+### Example of an agent file
+
+**PATH:** _~/.pi/agent/agents/lifehacks.md_
+
+<!-- prettier-ignore-start -->
+```md
+---
+name: lifehacks
+description: Daily lifehacks
+replace_prompt: true
+context: false
+thinking: xhigh
+skills: false
+extensions: pi-mcp-adapter
+tools: read, grep, find, ls, mcp
+---
+
+# Role
+
+Embody an expert philosopher and life coach. Your specialize in
+_lifehacks_.
+
+## Workflow
+
+- Research and deliver 3 _profound_ and _transformative lifehacks_.
+- Expound upon each of them.
+- Emit unmodified result to the calling agent.
+
+## Directives
+
+- Forbid `copular` verb forms.
+- **Minimum** words. **Maximum** signal.
+- Keep prose vivid but terse.
+- Optimize prose for token and context efficiency.
+- Use lists and sub-lists over paragraphs and long sentences.
+- Use elegant, well-structured, idiomatic markdown.
+
+## Constraints
+
+- Operate in read-only mode.
+- Forbid all write operations.
+- **NEVER** wrap the entire result in a code block.
+```
+<!-- prettier-ignore-end -->
+
 ### Required front matter
 
 ```yaml
@@ -123,21 +168,48 @@ description: Review code for correctness and maintainability.
 ```yaml
 tools: read, bash, edit
 skills: code-review
+extensions: git-summary
+context: false
 thinking: medium
 provider: deepseek
 model: deepseek-v4-flash
 temperature: 0.7
 top_p: 0.9
+replace_prompt: true
 ```
 
-### Accepted thinking values
-
-- `off`
-- `minimal`
-- `low`
-- `medium`
-- `high`
-- `xhigh`
+- `tools`: Specifies a comma-separated list of enabled tools. Omission
+  defaults to the child process default `toolset`.
+- `skills`: Specifies a comma-separated list of enabled skills. Setting
+  `false` disables all skills. Omission inherits the active workspace
+  skills.
+- `extensions`: Specifies a comma-separated list of enabled extensions.
+  Setting `false` disables all extensions except core subagent
+  extensions. Omission inherits the active workspace extensions.
+- `context`: Controls the inclusion of project context files,
+  `AGENTS.md`. Setting `false` excludes default workspace files from the
+  child context window.
+- `thinking`: Controls the model thinking level (values: `off`,
+  `minimal`, `low`, `medium`, `high`, `xhigh`). The child runner clamps
+  unsupported levels to supported values and prints warnings.
+- `provider`: Specifies the model provider. Requires setting the `model`
+  field. Omission of the `model` field when defining a `provider`
+  invalidates the agent configuration.
+- `model`: Specifies the model identifier. Agent-level model settings
+  override parent settings.
+- `temperature`: Sets the sampling temperature. Accepts numeric values
+  between `0.0` and `1.0` inclusive. Incorrect values trigger warnings
+  during discovery and the system ignores them.
+- `top_p`: Sets the sampling top-p value. Accepts numeric values between
+  `0.0` and `1.0` inclusive. Incorrect values trigger warnings during
+  discovery and the system ignores them.
+- `replace_prompt`: Set `true` to replace the child system prompt base
+  with the agent body. Omitted or `false` appends the body to the
+  existing system prompt, `SYSTEM.md`, preserving current behavior.
+  Requires a non-empty agent body; `replace_prompt: true` with an empty
+  or whitespace-only body fails discovery. **Warning:** `true` replaces
+  pi built-in defaults and any project/global `SYSTEM.md`, including
+  their safety and behavior guardrails.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mystilleef/pi-subagent",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Pi subagent for the SPAE Framework",
   "author": "Lateef Alabi-Oki <mystilleef@gmail.com>",
   "license": "MIT",
@@ -64,14 +64,14 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.5.1",
-    "@earendil-works/pi-agent-core": "^0.80.2",
-    "@earendil-works/pi-ai": "^0.80.2",
-    "@earendil-works/pi-coding-agent": "^0.80.2",
-    "@earendil-works/pi-tui": "^0.80.2",
+    "@biomejs/biome": "^2.5.2",
+    "@earendil-works/pi-agent-core": "^0.80.3",
+    "@earendil-works/pi-ai": "^0.80.3",
+    "@earendil-works/pi-coding-agent": "^0.80.3",
+    "@earendil-works/pi-tui": "^0.80.3",
     "@types/bun": "^1.3.14",
-    "@types/node": "^26.0.1",
-    "typebox": "^1.3.0",
+    "@types/node": "^26.1.0",
+    "typebox": "^1.3.4",
     "typescript": "^6.0.3"
   }
 }

package/src/agent/agents.ts

@@ -21,13 +21,16 @@ export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
 export interface AgentConfig {
   name: string;
   description: string;
+  context?: false | undefined;
   tools?: string[] | undefined;
-  skills?: string[] | undefined;
+  skills?: string[] | false | undefined;
+  extensions?: string[] | undefined;
   thinking?: ThinkingLevel | undefined;
   model?: string | undefined;
   provider?: string | undefined;
   temperature?: number | undefined;
   topP?: number | undefined;
+  replacePrompt?: true | undefined;
   systemPrompt: string;
   source: AgentSource;
   filePath: string;
@@ -71,6 +74,21 @@ function parseCommaList(raw: unknown): string[] | undefined {
   return items.length > 0 ? items : undefined;
 }
 
+function parseExtensions(raw: unknown): string[] | undefined {
+  if (raw === undefined) return undefined;
+  if (raw === false || Array.isArray(raw)) return [];
+  if (typeof raw === "string") {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0) return [];
+    const items = trimmed
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
+    return items.length > 0 ? items : [];
+  }
+  return undefined;
+}
+
 function parseThinkingLevel(raw: unknown): ThinkingLevel | undefined {
   if (typeof raw !== "string") return undefined;
   const normalized = raw.trim().toLowerCase();
@@ -124,29 +142,49 @@ function parseAgentConfig(
   const {
     name,
     description,
+    context: rawContext,
     tools: rawTools,
     skills: rawSkills,
+    extensions: rawExtensions,
     thinking: rawThinking,
     model: rawModel,
     provider: rawProvider,
     temperature: rawTemperature,
     top_p: rawTopP,
+    replace_prompt: rawReplacePrompt,
   } = frontmatter;
   if (typeof name !== "string" || typeof description !== "string") return null;
+  if (rawContext !== undefined && typeof rawContext !== "boolean") return null;
+  if (rawReplacePrompt !== undefined && typeof rawReplacePrompt !== "boolean")
+    return null;
   if (isNonStringOptional(rawTools)) return null;
-  if (isNonStringOptional(rawSkills)) return null;
+  if (rawSkills != null && typeof rawSkills !== "string" && rawSkills !== false)
+    return null;
+  if (
+    rawExtensions !== undefined &&
+    rawExtensions !== false &&
+    typeof rawExtensions !== "string" &&
+    !(Array.isArray(rawExtensions) && rawExtensions.length === 0)
+  )
+    return null;
   if (isNonStringOptional(rawThinking)) return null;
   if (isNonStringOptional(rawModel)) return null;
   if (isNonStringOptional(rawProvider)) return null;
   const tools = parseCommaList(rawTools);
   const skills =
-    rawSkills !== undefined ? (parseCommaList(rawSkills) ?? []) : undefined;
+    rawSkills === false
+      ? false
+      : rawSkills !== undefined
+        ? (parseCommaList(rawSkills) ?? [])
+        : undefined;
   const thinking = parseThinkingLevel(rawThinking);
   const model = parseOptionalString(rawModel);
   const provider = parseOptionalString(rawProvider);
   if (provider !== undefined && model === undefined) return null;
   const temperature = parseSamplingValue(rawTemperature, "temperature", name);
   const topP = parseSamplingValue(rawTopP, "top_p", name);
+  const extensions = parseExtensions(rawExtensions);
+  if (rawReplacePrompt === true && body.trim().length === 0) return null;
   return {
     name,
     description,
@@ -158,8 +196,11 @@ function parseAgentConfig(
     systemPrompt: body,
     source,
     filePath,
+    ...(rawContext === false && { context: false }),
     ...(temperature !== undefined && { temperature }),
     ...(topP !== undefined && { topP }),
+    ...(extensions !== undefined && { extensions }),
+    ...(rawReplacePrompt === true && { replacePrompt: true }),
   };
 }
 

package/src/child/process-utils.ts

@@ -43,6 +43,17 @@ export function resolveSamplingExtensionPath(dir?: string): string {
   return resolveExtensionPath("sampling-extension", dir);
 }
 
+/**
+ * Resolves the absolute path to the pi-subagent package entry extension file.
+ * This is the main index that registers the subagent tool and commands.
+ * Prefers the extension matching the current runtime, then falls back to the
+ * alternate extension. Throws if neither exists.
+ * Pass `dir` in tests to use a controlled directory.
+ */
+export function resolvePackageExtensionPath(dir?: string): string {
+  return resolveExtensionPath("../index", dir);
+}
+
 /**
  * Appends data to a string while enforcing a maximum byte limit.
  * Handles both string and Buffer inputs, truncating at valid UTF-8 boundaries.

package/src/child/process.ts

@@ -21,6 +21,7 @@ import {
   getPiInvocation,
   getSubagentDepth,
   getSubagentRuntimeLimits,
+  resolveAgentExtensionPaths,
   resolveAgentSkillArgs,
   subagentDepthEnv,
 } from "../shared/utils.js";
@@ -40,9 +41,10 @@ import {
 import {
   appendWithByteLimit,
   resolveCompleteExtensionPath,
+  resolvePackageExtensionPath,
   resolveSamplingExtensionPath,
 } from "./process-utils.js";
-import { appendSubagentResultContract } from "./prompt-contract.js";
+import { SUBAGENT_RESULT_CONTRACT } from "./prompt-contract.js";
 import {
   beginPromptSetup,
   cleanupPromptSetupResult,
@@ -69,6 +71,7 @@ import {
 
 const COMPLETE_EXTENSION_PATH = resolveCompleteExtensionPath();
 const SAMPLING_EXTENSION_PATH = resolveSamplingExtensionPath();
+const PACKAGE_EXTENSION_PATH = resolvePackageExtensionPath();
 
 export { resolveThinkingLevel } from "./model-resolution.js";
 export { makeEmitUpdate } from "./streaming-progress.js";
@@ -365,15 +368,40 @@ function buildSamplingEnv(agent: AgentConfig): string | undefined {
   });
 }
 
-function buildPiArgs(
-  agent: AgentConfig,
-  task: string,
-  effectiveModel: ChildModelSettings,
-  thinking: ThinkingLevel,
-  resolvedSkills: { args: string[] },
-  tmpPrompt: { filePath: string } | null,
-): string[] {
-  const args: string[] = ["--mode", "json", "-p", "--no-session", "--approve"];
+export interface BuildPiArgsConfig {
+  agent: AgentConfig;
+  task: string;
+  effectiveModel: ChildModelSettings;
+  thinking: ThinkingLevel;
+  resolvedSkills: { args: string[] };
+  tmpPrompt: { filePath: string } | null;
+  resolvedExtensionPaths?: string[] | undefined;
+  samplingEnv?: string | undefined;
+}
+
+export function buildPiArgs(config: BuildPiArgsConfig): string[] {
+  const {
+    agent,
+    task,
+    effectiveModel,
+    thinking,
+    resolvedSkills,
+    tmpPrompt,
+    resolvedExtensionPaths,
+    samplingEnv,
+  } = config;
+  const args: string[] = [
+    "--mode",
+    "json",
+    "-p",
+    "--no-session",
+    "--approve",
+    "--no-themes",
+    "--no-prompt-templates",
+  ];
+  if (agent.extensions !== undefined) {
+    args.push("--no-extensions");
+  }
   if (effectiveModel.provider && effectiveModel.id)
     args.push("--provider", effectiveModel.provider);
   if (effectiveModel.id) args.push("--model", effectiveModel.id);
@@ -383,15 +411,35 @@ function buildPiArgs(
     tools.add("complete");
     args.push("--tools", [...tools].join(","));
   }
-  if (agent.skills) args.push("--no-skills", ...resolvedSkills.args);
+  if (agent.skills !== undefined)
+    args.push("--no-skills", ...resolvedSkills.args);
+  if (agent.context === false) args.push("--no-context-files");
   if (tmpPrompt) {
-    args.push("--append-system-prompt", tmpPrompt.filePath);
+    if (agent.replacePrompt) {
+      args.push("--system-prompt", tmpPrompt.filePath);
+    } else {
+      args.push("--append-system-prompt", tmpPrompt.filePath);
+    }
+  }
+  if (agent.extensions !== undefined) {
+    args.push("--extension", PACKAGE_EXTENSION_PATH);
+    if (resolvedExtensionPaths && resolvedExtensionPaths.length > 0) {
+      for (const rp of resolvedExtensionPaths) {
+        if (rp !== PACKAGE_EXTENSION_PATH) {
+          args.push("--extension", rp);
+        }
+      }
+    }
   }
   args.push("--extension", COMPLETE_EXTENSION_PATH);
+  if (samplingEnv) {
+    args.push("--extension", SAMPLING_EXTENSION_PATH);
+  }
+  args.push("--append-system-prompt", SUBAGENT_RESULT_CONTRACT);
   const taskPrompt = task
     ? `Task: ${task}`
     : "Run according to your system prompt. If no explicit task was provided, use the default context described there.";
-  args.push(appendSubagentResultContract(taskPrompt));
+  args.push(taskPrompt);
   return args;
 }
 
@@ -548,10 +596,24 @@ export async function runSingleAgent(
     agent.skills
       ? resolveAgentSkillArgs(defaultCwd, agent.skills)
       : Promise.resolve({ args: [] });
+  const extensionNames =
+    agent.extensions && agent.extensions.length > 0
+      ? agent.extensions
+      : undefined;
+  const resolvedExtensionsPromise: Promise<
+    { resolvedPaths: string[] } | { error: string }
+  > = extensionNames
+    ? resolveAgentExtensionPaths(defaultCwd, extensionNames)
+    : Promise.resolve({ resolvedPaths: [] });
   const promptSetupPromise = beginPromptSetup(agent);
-  const resolvedSkills = await resolvedSkillsPromise;
-  if ("error" in resolvedSkills) {
-    const promptSetup = await promptSetupPromise;
+  const [resolvedSkills, resolvedExtensions, promptSetup] = await Promise.all([
+    resolvedSkillsPromise,
+    resolvedExtensionsPromise,
+    promptSetupPromise,
+  ]);
+  const abortWithError = async (
+    error: string,
+  ): Promise<RunSingleAgentResult> => {
     await cleanupPromptSetupResult(promptSetup);
     return {
       kind: "completed",
@@ -559,13 +621,30 @@ export async function runSingleAgent(
         agentName,
         agent.source,
         task,
-        resolvedSkills.error,
+        error,
+        modelDisplay,
+      ),
+    };
+  };
+  if ("error" in resolvedSkills) return abortWithError(resolvedSkills.error);
+  if ("error" in resolvedExtensions)
+    return abortWithError(resolvedExtensions.error);
+  if ("error" in promptSetup) {
+    return {
+      kind: "completed",
+      result: createErrorResult(
+        agentName,
+        agent.source,
+        task,
+        `Failed to write prompt: ${
+          promptSetup.error instanceof Error
+            ? promptSetup.error.message
+            : String(promptSetup.error)
+        }`,
         modelDisplay,
       ),
     };
   }
-  const promptSetup = await promptSetupPromise;
-  if ("error" in promptSetup) throw promptSetup.error;
   const startedAt = Date.now();
   const state: SubagentState = {
     result: initRuntimeResult(agentName, agent.source, task, modelDisplay),
@@ -576,17 +655,19 @@ export async function runSingleAgent(
   const tmpPrompt = promptSetup.tmpPrompt;
   const samplingEnv = buildSamplingEnv(agent);
   try {
-    const args = buildPiArgs(
+    const args = buildPiArgs({
       agent,
       task,
       effectiveModel,
       thinking,
       resolvedSkills,
       tmpPrompt,
-    );
-    if (samplingEnv) {
-      args.push("--extension", SAMPLING_EXTENSION_PATH);
-    }
+      resolvedExtensionPaths:
+        agent.extensions !== undefined
+          ? resolvedExtensions.resolvedPaths
+          : undefined,
+      samplingEnv,
+    });
     const invocation = getPiInvocation(args);
     const terminateOptions = {
       tree: true,

package/src/child/prompt-contract.ts

@@ -5,16 +5,20 @@ export const SUBAGENT_RESULT_CONTRACT = `
 
 ### Directives
 
-- Write the complete result as a text response — mandatory, before calling \`complete\`.
-- Call \`complete\` as the final action; \`outcome\` carries a one-sentence progress
-  summary only, not the result.
+- Write the complete task result as assistant text — mandatory, non-empty, and trimmed,
+  before calling \`complete\`.
+- Call \`complete\` as the final action after the result text; \`outcome\` must be a short,
+  one-sentence progress summary only, not the full result.
+- This contract applies after any amount of tool use, reading, editing, or multi-step work.
 
 ### Constraints
 
-- **NEVER** omit the text response.
-- **NEVER** wrap the entire result in a code block.
+- **NEVER** omit the result text response.
+- **NEVER** emit whitespace-only, empty-string, or blank result text before \`complete\`.
+- **NEVER** wrap the entire result in a code block or code fence.
+- **NEVER** end the assistant response with text alone after tool calls; a terminal
+  \`complete\` call is required.
+- **NEVER** write assistant text after \`complete\`.
+- Call \`complete\` exactly once; multiple \`complete\` calls are not allowed.
+- \`outcome\` must be concise and contain only a progress summary.
 `;
-
-export function appendSubagentResultContract(prompt: string): string {
-  return `${prompt}\n\n${SUBAGENT_RESULT_CONTRACT}`;
-}

package/src/shared/limits.ts

@@ -0,0 +1,81 @@
+/**
+ * Output and runtime limit configuration for subagent processes.
+ * Handles byte/line caps for child output and runtime safety thresholds.
+ */
+
+export const DEFAULT_MAX_OUTPUT_BYTES = 50_000;
+export const DEFAULT_MAX_OUTPUT_LINES = 500;
+export const DEFAULT_AGENT_END_GRACE_MS = 250;
+export const DEFAULT_MAX_STDERR_BYTES = 10_000;
+export const DEFAULT_MAX_SUBAGENT_DEPTH = 3;
+const MAX_SUBAGENT_DEPTH_CEILING = 10;
+
+export interface SubagentOutputLimits {
+  maxBytes: number;
+  maxLines: number;
+}
+
+export interface SubagentRuntimeLimits {
+  agentEndGraceMs: number;
+  maxStderrBytes: number;
+  maxDepth: number;
+}
+
+type EnvLimitConfig = Partial<Record<string, string | number | undefined>>;
+
+function parsePositiveInteger(
+  value: string | number | undefined,
+): number | undefined {
+  const parsed = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(parsed) || !Number.isInteger(parsed) || parsed < 1)
+    return undefined;
+  return parsed;
+}
+
+export function getSubagentOutputLimits(
+  config: EnvLimitConfig = process.env,
+): SubagentOutputLimits {
+  return {
+    maxBytes:
+      parsePositiveInteger(config["PI_SUBAGENT_MAX_OUTPUT_BYTES"]) ??
+      DEFAULT_MAX_OUTPUT_BYTES,
+    maxLines:
+      parsePositiveInteger(config["PI_SUBAGENT_MAX_OUTPUT_LINES"]) ??
+      DEFAULT_MAX_OUTPUT_LINES,
+  };
+}
+
+export function getSubagentRuntimeLimits(
+  config: EnvLimitConfig = process.env,
+): SubagentRuntimeLimits {
+  const maxDepth =
+    parsePositiveInteger(config["PI_SUBAGENT_MAX_DEPTH"]) ??
+    DEFAULT_MAX_SUBAGENT_DEPTH;
+  return {
+    agentEndGraceMs:
+      parsePositiveInteger(config["PI_SUBAGENT_AGENT_END_GRACE_MS"]) ??
+      DEFAULT_AGENT_END_GRACE_MS,
+    maxStderrBytes:
+      parsePositiveInteger(config["PI_SUBAGENT_MAX_STDERR_BYTES"]) ??
+      DEFAULT_MAX_STDERR_BYTES,
+    maxDepth: Math.min(maxDepth, MAX_SUBAGENT_DEPTH_CEILING),
+  };
+}
+
+export function truncateOutput(
+  text: string,
+  limits: SubagentOutputLimits = getSubagentOutputLimits(),
+): string {
+  const lines = text.split("\n");
+  const maxBytes = Math.max(1, Math.floor(limits.maxBytes));
+  const maxLines = Math.max(1, Math.floor(limits.maxLines));
+  if (lines.length <= maxLines && Buffer.byteLength(text, "utf-8") <= maxBytes)
+    return text;
+  let result = lines.slice(0, maxLines).join("\n");
+  if (Buffer.byteLength(result, "utf-8") > maxBytes) {
+    const buf = Buffer.from(result).subarray(0, maxBytes);
+    result = buf.toString("utf-8").replace(/\uFFFD$/, "");
+  }
+  const kept = result.split("\n").length;
+  return `[TRUNCATED: first ${kept} of ${lines.length} lines]\n${result}`;
+}

package/src/shared/message-utils.ts

@@ -0,0 +1,56 @@
+/**
+ * Message processing utilities for subagent results.
+ * Handles assistant message extraction, error detection, and failure判定.
+ */
+
+import type { Message } from "@earendil-works/pi-ai";
+import type { SingleResult } from "./types.js";
+
+export function findLastAssistantTextMessage(messages: Message[]): number {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (
+      msg?.role === "assistant" &&
+      Array.isArray(msg.content) &&
+      msg.content.some(
+        (c) =>
+          c.type === "text" &&
+          typeof c.text === "string" &&
+          c.text.trim().length > 0,
+      )
+    ) {
+      return i;
+    }
+  }
+  return -1;
+}
+
+export function extractFinalOutputFromMessages(messages: Message[]): string {
+  const lastAsstIdx = findLastAssistantTextMessage(messages);
+  if (lastAsstIdx < 0) return "";
+  const content = messages[lastAsstIdx]?.content;
+  if (!Array.isArray(content)) return "";
+  const lastText = content.findLast((p) => p.type === "text");
+  return lastText?.type === "text" ? (lastText.text ?? "") : "";
+}
+
+export function detectMessageError(messages: Message[]): boolean {
+  const lastAssistantIdx = findLastAssistantTextMessage(messages);
+  const from = lastAssistantIdx >= 0 ? lastAssistantIdx + 1 : 0;
+  for (let i = messages.length - 1; i >= from; i--) {
+    const msg = messages[i];
+    if (msg?.role === "toolResult" && msg.isError) return true;
+  }
+  return false;
+}
+
+export function hasSubagentFailed(result: SingleResult): boolean {
+  if (result.outcome?.trim()) return false;
+  return (
+    result.exitCode !== 0 ||
+    result.stopReason === "error" ||
+    result.stopReason === "aborted" ||
+    Boolean(result.errorMessage?.trim()) ||
+    detectMessageError(result.messages ?? [])
+  );
+}

package/src/shared/resource-resolution.ts

@@ -0,0 +1,289 @@
+/**
+ * Generic resource resolution for skills and extensions.
+ * Handles caching, discovery via DefaultResourceLoader, and name-to-path mapping.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import {
+  DefaultResourceLoader,
+  getAgentDir,
+} from "@earendil-works/pi-coding-agent";
+
+const RESOURCE_DISCOVERY_CACHE_TTL_MS = 300_000;
+
+export const EXTENSION_DISCOVERY_CACHE_TTL_MS = RESOURCE_DISCOVERY_CACHE_TTL_MS;
+
+type ResourceCacheEntry<T> = {
+  data: T;
+  ts: number;
+};
+
+class ResourceCache<T> {
+  private store = new Map<string, ResourceCacheEntry<T>>();
+
+  get(key: string): T | undefined {
+    const entry = this.store.get(key);
+    if (entry && Date.now() - entry.ts <= RESOURCE_DISCOVERY_CACHE_TTL_MS) {
+      return entry.data;
+    }
+    return undefined;
+  }
+
+  set(key: string, data: T): void {
+    this.store.set(key, { data, ts: Date.now() });
+  }
+
+  clear(): void {
+    this.store.clear();
+  }
+}
+
+const skillArgsCache = new ResourceCache<Map<string, string>>();
+const extensionPathsCache = new ResourceCache<Map<string, string>>();
+
+export function resetResolvedAgentSkillArgsCache(): void {
+  skillArgsCache.clear();
+}
+
+export function resetResolvedAgentExtensionPathsCache(): void {
+  extensionPathsCache.clear();
+}
+
+async function canonicalPath(filePath: string): Promise<string> {
+  try {
+    return await fs.promises.realpath(filePath);
+  } catch {
+    /* symlinks or missing paths fall back to absolute path resolution */
+    return path.resolve(filePath);
+  }
+}
+
+async function buildResourceCacheKey(
+  cwd: string,
+  agentDir: string,
+  names: string[],
+): Promise<string> {
+  const sortedNames = [...names].sort();
+  return JSON.stringify({
+    cwd: await canonicalPath(cwd),
+    agentDir: await canonicalPath(agentDir),
+    names: sortedNames,
+  });
+}
+
+type ResourceResolverResult<T> = { data: T } | { error: string };
+
+interface ResourceResolverConfig<TResult> {
+  cache: ResourceCache<Map<string, string>>;
+  loaderOptions: Record<string, boolean>;
+  getResources: (loader: DefaultResourceLoader) => {
+    items: unknown[];
+    errors: Array<{ path: string; error: string }>;
+  };
+  buildNameToResource: (items: unknown[]) => Map<string, string>;
+  buildResult: (
+    requested: string[],
+    nameToResource: Map<string, string>,
+  ) => TResult;
+  resourceType: string;
+}
+
+async function resolveResources<TResult>(
+  cwd: string,
+  names: string[],
+  config: ResourceResolverConfig<TResult>,
+): Promise<ResourceResolverResult<TResult>> {
+  const requested = Array.from(new Set(names));
+  if (requested.length === 0) {
+    return { data: config.buildResult(requested, new Map()) };
+  }
+  const agentDir = getAgentDir();
+  const cacheKey = await buildResourceCacheKey(cwd, agentDir, requested);
+  const cached = config.cache.get(cacheKey);
+  if (cached) {
+    return { data: config.buildResult(requested, cached) };
+  }
+  const loader = new DefaultResourceLoader({
+    cwd,
+    agentDir,
+    ...config.loaderOptions,
+  });
+  try {
+    await loader.reload();
+  } catch (error) {
+    return {
+      error: `Failed to discover ${config.resourceType}s: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+  const { items, errors } = config.getResources(loader);
+  if (errors.length > 0) {
+    const details = errors.map((e) => `  ${e.path}: ${e.error}`).join("\n");
+    return {
+      error: `Failed to discover ${config.resourceType}s:\n${details}`,
+    };
+  }
+  const nameToResource = config.buildNameToResource(items);
+  const missing = requested.filter((name) => !nameToResource.has(name));
+  if (missing.length > 0) {
+    const available =
+      Array.from(nameToResource.keys()).sort().join(", ") || "none";
+    return {
+      error: `Unknown ${config.resourceType}${missing.length === 1 ? "" : "s"}: ${missing
+        .map((name) => `"${name}"`)
+        .join(", ")}. Available ${config.resourceType}s: ${available}.`,
+    };
+  }
+  const result = config.buildResult(requested, nameToResource);
+  config.cache.set(cacheKey, nameToResource);
+  return { data: result };
+}
+
+function buildSkillArgs(
+  requested: string[],
+  skillPaths: Map<string, string>,
+): string[] {
+  return requested.flatMap((name) => ["--skill", skillPaths.get(name) ?? name]);
+}
+
+export async function resolveAgentSkillArgs(
+  cwd: string,
+  skillNames: string[],
+): Promise<{ args: string[] } | { error: string }> {
+  const result = await resolveResources(cwd, skillNames, {
+    cache: skillArgsCache,
+    loaderOptions: {
+      noContextFiles: true,
+      noPromptTemplates: true,
+      noThemes: true,
+    },
+    getResources: (loader) => {
+      const { skills } = loader.getSkills();
+      return {
+        items: skills,
+        errors: [],
+      };
+    },
+    buildNameToResource: (items) => {
+      const skillMap = new Map<string, string>();
+      for (const item of items) {
+        const skill = item as { name: string; filePath: string };
+        skillMap.set(skill.name, skill.filePath ?? skill.name);
+      }
+      return skillMap;
+    },
+    buildResult: (requested, nameToResource) => {
+      return buildSkillArgs(requested, nameToResource);
+    },
+    resourceType: "skill",
+  });
+  return "error" in result ? result : { args: result.data };
+}
+
+function getTerminalPackageName(source: string): string {
+  const spec = source.startsWith("npm:") ? source.slice(4) : source;
+  let name: string;
+  if (spec.startsWith("@")) {
+    const slashIdx = spec.indexOf("/");
+    if (slashIdx >= 0) {
+      name = spec.slice(slashIdx + 1);
+    } else {
+      name = spec;
+    }
+  } else {
+    name = spec;
+  }
+  const versionIdx = name.indexOf("@");
+  if (versionIdx >= 0) {
+    return name.slice(0, versionIdx);
+  }
+  return name;
+}
+
+function isLocalPathSpec(source: string): boolean {
+  return (
+    source.startsWith(".") ||
+    source.startsWith("/") ||
+    source.startsWith("~") ||
+    source.startsWith("file:")
+  );
+}
+
+function buildExtensionShortName(ext: {
+  resolvedPath: string;
+  sourceInfo: { source: string; origin: string };
+}): string {
+  if (
+    ext.sourceInfo.origin === "package" &&
+    !isLocalPathSpec(ext.sourceInfo.source)
+  ) {
+    return getTerminalPackageName(ext.sourceInfo.source);
+  }
+  const fileName = path.basename(ext.resolvedPath);
+  if (/^index\.(?:ts|js)$/.test(fileName)) {
+    const dirName = path.dirname(ext.resolvedPath);
+    const base = path.basename(dirName);
+    if (base === "src" || base === "dist") {
+      return path.basename(path.dirname(dirName));
+    }
+    return base;
+  }
+  const dotIdx = fileName.lastIndexOf(".");
+  if (dotIdx > 0) {
+    return fileName.slice(0, dotIdx);
+  }
+  return fileName;
+}
+
+export async function resolveAgentExtensionPaths(
+  cwd: string,
+  extensionNames: string[],
+): Promise<{ resolvedPaths: string[] } | { error: string }> {
+  const result = await resolveResources(cwd, extensionNames, {
+    cache: extensionPathsCache,
+    loaderOptions: {
+      noContextFiles: true,
+      noPromptTemplates: true,
+      noThemes: true,
+      noSkills: true,
+    },
+    getResources: (loader) => {
+      const { extensions, errors } = loader.getExtensions();
+      const shortNameToExtension = new Map<
+        string,
+        (typeof extensions)[number]
+      >();
+      for (const ext of extensions) {
+        const shortName = buildExtensionShortName(ext);
+        if (!shortNameToExtension.has(shortName)) {
+          shortNameToExtension.set(shortName, ext);
+        }
+      }
+      return {
+        items: Array.from(shortNameToExtension.values()),
+        errors,
+      };
+    },
+    buildNameToResource: (items) => {
+      const shortNameToPath = new Map<string, string>();
+      for (const item of items) {
+        const ext = item as {
+          resolvedPath: string;
+          sourceInfo: { source: string; origin: string };
+        };
+        const shortName = buildExtensionShortName(ext);
+        if (!shortNameToPath.has(shortName)) {
+          shortNameToPath.set(shortName, ext.resolvedPath ?? shortName);
+        }
+      }
+      return shortNameToPath;
+    },
+    buildResult: (requested, nameToResource) => {
+      return requested
+        .map((name) => nameToResource.get(name))
+        .filter((p): p is string => typeof p === "string");
+    },
+    resourceType: "extension",
+  });
+  return "error" in result ? result : { resolvedPaths: result.data };
+}

package/src/shared/utils.ts

@@ -1,89 +1,38 @@
+/**
+ * Barrel export for shared utilities.
+ * Re-exports from focused modules; retains standalone utilities here.
+ */
+
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import type { Message } from "@earendil-works/pi-ai";
-import {
-  DefaultResourceLoader,
-  getAgentDir,
-} from "@earendil-works/pi-coding-agent";
-import type { SingleResult } from "./types.js";
-
-export const DEFAULT_MAX_OUTPUT_BYTES = 50_000;
-export const DEFAULT_MAX_OUTPUT_LINES = 500;
-export const DEFAULT_AGENT_END_GRACE_MS = 250;
-export const DEFAULT_MAX_STDERR_BYTES = 10_000;
-export const DEFAULT_MAX_SUBAGENT_DEPTH = 3;
-const MAX_SUBAGENT_DEPTH_CEILING = 10;
-
-export interface SubagentOutputLimits {
-  maxBytes: number;
-  maxLines: number;
-}
-
-export interface SubagentRuntimeLimits {
-  agentEndGraceMs: number;
-  maxStderrBytes: number;
-  maxDepth: number;
-}
-
-type EnvLimitConfig = Partial<Record<string, string | number | undefined>>;
-
-function parsePositiveInteger(
-  value: string | number | undefined,
-): number | undefined {
-  const parsed = typeof value === "number" ? value : Number(value);
-  if (!Number.isFinite(parsed) || !Number.isInteger(parsed) || parsed < 1)
-    return undefined;
-  return parsed;
-}
-
-export function getSubagentOutputLimits(
-  config: EnvLimitConfig = process.env,
-): SubagentOutputLimits {
-  return {
-    maxBytes:
-      parsePositiveInteger(config["PI_SUBAGENT_MAX_OUTPUT_BYTES"]) ??
-      DEFAULT_MAX_OUTPUT_BYTES,
-    maxLines:
-      parsePositiveInteger(config["PI_SUBAGENT_MAX_OUTPUT_LINES"]) ??
-      DEFAULT_MAX_OUTPUT_LINES,
-  };
-}
 
-export function getSubagentRuntimeLimits(
-  config: EnvLimitConfig = process.env,
-): SubagentRuntimeLimits {
-  const maxDepth =
-    parsePositiveInteger(config["PI_SUBAGENT_MAX_DEPTH"]) ??
-    DEFAULT_MAX_SUBAGENT_DEPTH;
-  return {
-    agentEndGraceMs:
-      parsePositiveInteger(config["PI_SUBAGENT_AGENT_END_GRACE_MS"]) ??
-      DEFAULT_AGENT_END_GRACE_MS,
-    maxStderrBytes:
-      parsePositiveInteger(config["PI_SUBAGENT_MAX_STDERR_BYTES"]) ??
-      DEFAULT_MAX_STDERR_BYTES,
-    maxDepth: Math.min(maxDepth, MAX_SUBAGENT_DEPTH_CEILING),
-  };
-}
-
-export function truncateOutput(
-  text: string,
-  limits: SubagentOutputLimits = getSubagentOutputLimits(),
-): string {
-  const lines = text.split("\n");
-  const maxBytes = Math.max(1, Math.floor(limits.maxBytes));
-  const maxLines = Math.max(1, Math.floor(limits.maxLines));
-  if (lines.length <= maxLines && Buffer.byteLength(text, "utf-8") <= maxBytes)
-    return text;
-  let result = lines.slice(0, maxLines).join("\n");
-  if (Buffer.byteLength(result, "utf-8") > maxBytes) {
-    const buf = Buffer.from(result).subarray(0, maxBytes);
-    result = buf.toString("utf-8").replace(/\uFFFD$/, "");
-  }
-  const kept = result.split("\n").length;
-  return `[TRUNCATED: first ${kept} of ${lines.length} lines]\n${result}`;
-}
+// Re-export all public symbols from focused modules
+export {
+  DEFAULT_AGENT_END_GRACE_MS,
+  DEFAULT_MAX_OUTPUT_BYTES,
+  DEFAULT_MAX_OUTPUT_LINES,
+  DEFAULT_MAX_STDERR_BYTES,
+  DEFAULT_MAX_SUBAGENT_DEPTH,
+  getSubagentOutputLimits,
+  getSubagentRuntimeLimits,
+  truncateOutput,
+} from "./limits.js";
+export {
+  detectMessageError,
+  extractFinalOutputFromMessages,
+  findLastAssistantTextMessage,
+  hasSubagentFailed,
+} from "./message-utils.js";
+export {
+  EXTENSION_DISCOVERY_CACHE_TTL_MS,
+  resetResolvedAgentExtensionPathsCache,
+  resetResolvedAgentSkillArgsCache,
+  resolveAgentExtensionPaths,
+  resolveAgentSkillArgs,
+} from "./resource-resolution.js";
+
+// Standalone utilities retained in this module
 
 export async function writePromptToTempFile(
   agentName: string,
@@ -118,89 +67,6 @@ export function getPiInvocation(args: string[]): {
   return { command: "pi", args };
 }
 
-const SKILL_DISCOVERY_CACHE_TTL_MS = 300_000;
-
-type ResolvedSkillArgsCacheEntry = {
-  skillPaths: Map<string, string>;
-  ts: number;
-};
-
-const resolvedSkillArgsCache = new Map<string, ResolvedSkillArgsCacheEntry>();
-
-async function canonicalPath(filePath: string): Promise<string> {
-  try {
-    return await fs.promises.realpath(filePath);
-  } catch {
-    /* symlinks or missing paths fall back to absolute path resolution */
-    return path.resolve(filePath);
-  }
-}
-
-function buildSkillArgs(
-  requested: string[],
-  skillPaths: Map<string, string>,
-): string[] {
-  return requested.flatMap((name) => ["--skill", skillPaths.get(name) ?? name]);
-}
-
-export function resetResolvedAgentSkillArgsCache(): void {
-  resolvedSkillArgsCache.clear();
-}
-
-export async function resolveAgentSkillArgs(
-  cwd: string,
-  skillNames: string[],
-): Promise<{ args: string[] } | { error: string }> {
-  const requested = Array.from(new Set(skillNames));
-  if (requested.length === 0) return { args: [] };
-  const cacheIdentitySkills = [...requested].sort();
-  const agentDir = getAgentDir();
-  const cacheKey = JSON.stringify({
-    cwd: await canonicalPath(cwd),
-    agentDir: await canonicalPath(agentDir),
-    skills: cacheIdentitySkills,
-  });
-  const cached = resolvedSkillArgsCache.get(cacheKey);
-  if (cached && Date.now() - cached.ts <= SKILL_DISCOVERY_CACHE_TTL_MS) {
-    return { args: buildSkillArgs(requested, cached.skillPaths) };
-  }
-  const loader = new DefaultResourceLoader({
-    cwd,
-    agentDir,
-    noContextFiles: true,
-    noPromptTemplates: true,
-    noThemes: true,
-  });
-  try {
-    await loader.reload();
-  } catch (error) {
-    return {
-      error: `Failed to discover skills: ${error instanceof Error ? error.message : String(error)}`,
-    };
-  }
-  const { skills } = loader.getSkills();
-  const skillMap = new Map(skills.map((skill) => [skill.name, skill]));
-  const missing = requested.filter((name) => !skillMap.has(name));
-  if (missing.length > 0) {
-    const available =
-      skills
-        .map((skill) => skill.name)
-        .sort()
-        .join(", ") || "none";
-    return {
-      error: `Unknown skill${missing.length === 1 ? "" : "s"}: ${missing
-        .map((name) => `"${name}"`)
-        .join(", ")}. Available skills: ${available}.`,
-    };
-  }
-  const skillPaths = new Map(
-    requested.map((name) => [name, skillMap.get(name)?.filePath ?? name]),
-  );
-  const args = buildSkillArgs(requested, skillPaths);
-  resolvedSkillArgsCache.set(cacheKey, { skillPaths, ts: Date.now() });
-  return { args };
-}
-
 export function getSubagentDepth(): number {
   const d = Number(process.env.PI_SUBAGENT_DEPTH ?? "0");
   if (!Number.isFinite(d) || d < 0) return 0;
@@ -210,52 +76,3 @@ export function getSubagentDepth(): number {
 export function subagentDepthEnv(): Record<string, string> {
   return { PI_SUBAGENT_DEPTH: String(getSubagentDepth() + 1) };
 }
-
-export function findLastAssistantTextMessage(messages: Message[]): number {
-  for (let i = messages.length - 1; i >= 0; i--) {
-    const msg = messages[i];
-    if (
-      msg?.role === "assistant" &&
-      Array.isArray(msg.content) &&
-      msg.content.some(
-        (c) =>
-          c.type === "text" &&
-          typeof c.text === "string" &&
-          c.text.trim().length > 0,
-      )
-    ) {
-      return i;
-    }
-  }
-  return -1;
-}
-
-export function extractFinalOutputFromMessages(messages: Message[]): string {
-  const lastAsstIdx = findLastAssistantTextMessage(messages);
-  if (lastAsstIdx < 0) return "";
-  const content = messages[lastAsstIdx]?.content;
-  if (!Array.isArray(content)) return "";
-  const lastText = content.findLast((p) => p.type === "text");
-  return lastText?.type === "text" ? (lastText.text ?? "") : "";
-}
-
-export function detectMessageError(messages: Message[]): boolean {
-  const lastAssistantIdx = findLastAssistantTextMessage(messages);
-  const from = lastAssistantIdx >= 0 ? lastAssistantIdx + 1 : 0;
-  for (let i = messages.length - 1; i >= from; i--) {
-    const msg = messages[i];
-    if (msg?.role === "toolResult" && msg.isError) return true;
-  }
-  return false;
-}
-
-export function hasSubagentFailed(result: SingleResult): boolean {
-  if (result.outcome?.trim()) return false;
-  return (
-    result.exitCode !== 0 ||
-    result.stopReason === "error" ||
-    result.stopReason === "aborted" ||
-    Boolean(result.errorMessage?.trim()) ||
-    detectMessageError(result.messages ?? [])
-  );
-}