@mystilleef/pi-subagent 0.11.0 → 0.12.1

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,49 @@ 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`, `max`). `xhigh` and `max`
+  are model-specific, opt-in levels. 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.
 
 ---
 
@@ -210,7 +283,7 @@ decimal, `Infinity`, and non-numeric values fall back to defaults.
 
 **Missing agent:**
 
-- Confirm the file lives under `~/.pi/agents/` or the nearest
+- Confirm the file lives under `~/.pi/agent/agents/` or the nearest
   `.pi/agents/`.
 - Confirm `frontmatter` includes `name` and `description`.
 - Confirm `/run` uses the `name` value, not the filename.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mystilleef/pi-subagent",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "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.7",
+    "@earendil-works/pi-agent-core": "^0.84.0",
+    "@earendil-works/pi-ai": "^0.84.0",
+    "@earendil-works/pi-coding-agent": "^0.84.0",
+    "@earendil-works/pi-tui": "^0.84.0",
     "@types/bun": "^1.3.14",
-    "@types/node": "^26.0.1",
-    "typebox": "^1.3.0",
-    "typescript": "^6.0.3"
+    "@types/node": "^26.1.2",
+    "typebox": "^1.3.11",
+    "typescript": "^7.0.2"
   }
 }

package/src/agent/agents.ts

@@ -14,6 +14,7 @@ const THINKING_LEVELS = [
   "medium",
   "high",
   "xhigh",
+  "max",
 ] as const;
 
 export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
@@ -21,13 +22,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 +75,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 +143,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 +197,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/model-resolution.ts

@@ -4,8 +4,10 @@
  */
 
 import {
+  type Api,
   clampThinkingLevel,
   getSupportedThinkingLevels,
+  type Model,
   type ModelThinkingLevel,
 } from "@earendil-works/pi-ai";
 import { getModel } from "@earendil-works/pi-ai/compat";
@@ -17,22 +19,87 @@ export type ChildModelSettings = {
 };
 
 /**
- * Resolves the effective thinking level for a model, clamping to supported levels.
- * Returns a warning message if the requested level differs from the effective level.
+ * Minimal live-registry seam consumed by thinking-level resolution.
+ * Accepts the public {@link ModelRegistry} from the host extension context
+ * or any test double that provides the same lookup contract.
  */
-export function resolveThinkingLevel(
+export interface ModelRegistry {
+  find(provider: string, modelId: string): Model<Api> | undefined;
+}
+
+export interface ResolveThinkingLevelOptions {
+  registry?: ModelRegistry | undefined;
+}
+
+export interface ResolvedThinkingLevel {
+  level: ThinkingLevel;
+  warning?: string | undefined;
+  diagnostic?: string | undefined;
+}
+
+const FALLBACK_LEVEL: ThinkingLevel = "off";
+
+function formatProviderModelLabel(
+  provider: string | undefined,
+  modelId: string | undefined,
+): string {
+  const providerLabel = provider ?? "unknown";
+  const modelLabel = modelId ?? "unknown";
+  return `(provider: ${providerLabel}, model: ${modelLabel})`;
+}
+
+function formatUnsupportedWarning(
   requested: ThinkingLevel,
+  effective: ThinkingLevel,
+  provider: string | undefined,
+  modelId: string | undefined,
+): string {
+  return `Thinking level "${requested}" is not supported; using "${effective}" instead ${formatProviderModelLabel(provider, modelId)}`;
+}
+
+function formatUnconfirmedWarning(
+  requested: ThinkingLevel,
+  provider: string | undefined,
+  modelId: string | undefined,
+): string {
+  return `Thinking level "${requested}" support could not be confirmed; requesting as-is ${formatProviderModelLabel(provider, modelId)}`;
+}
+
+function resolveModel(
   provider: string,
   modelId: string,
-): { level: ThinkingLevel; warning?: string } {
-  const model = getModel(provider as never, modelId as never);
-  if (!model) return { level: requested };
-  const mkWarning = (effective: ThinkingLevel) =>
-    `Thinking level "${requested}" not supported by model "${provider}/${modelId}"; using "${effective}" instead`;
+  registry: ModelRegistry | undefined,
+): { model: Model<Api> | undefined; diagnostic: string | undefined } {
+  if (registry) {
+    const live = registry.find(provider, modelId);
+    if (live) return { model: live, diagnostic: undefined };
+  }
+  const diagnostic = registry
+    ? undefined
+    : "Live model registry unavailable; falling back to static catalog.";
+  const staticModel = getModel(provider as never, modelId as never) as
+    | Model<Api>
+    | undefined;
+  return { model: staticModel, diagnostic };
+}
+
+function resolveForModel(
+  requested: ThinkingLevel,
+  provider: string | undefined,
+  modelId: string | undefined,
+  model: Model<Api>,
+): ResolvedThinkingLevel {
   if (model.reasoning === false) {
-    return { level: "off", warning: mkWarning("off") };
+    return {
+      level: FALLBACK_LEVEL,
+      warning: formatUnsupportedWarning(
+        requested,
+        FALLBACK_LEVEL,
+        provider,
+        modelId,
+      ),
+    };
   }
-  if (!model.thinkingLevelMap) return { level: requested };
   const supported = getSupportedThinkingLevels(model);
   if (supported.length === 0) return { level: requested };
   const clamped = clampThinkingLevel(
@@ -40,7 +107,54 @@ export function resolveThinkingLevel(
     requested as ModelThinkingLevel,
   ) as ThinkingLevel;
   if (clamped === requested) return { level: requested };
-  return { level: clamped, warning: mkWarning(clamped) };
+  return {
+    level: clamped,
+    warning: formatUnsupportedWarning(requested, clamped, provider, modelId),
+  };
+}
+
+/**
+ * Resolves the effective thinking level for a model, preferring the live
+ * registry over the static catalog. Confirmed matches (live or static) clamp
+ * unsupported levels with the standard unsupported-level warning. Unconfirmed
+ * misses—missing provider or model identifiers, missing/unavailable registries,
+ * and live or static catalog misses—preserve the requested level for display
+ * while warning that support could not be confirmed. Requested `off` always
+ * stays warning-free in unconfirmed paths. Registry diagnostics are returned
+ * separately and never included in the user-facing warning.
+ */
+export function resolveThinkingLevel(
+  requested: ThinkingLevel,
+  provider: string | undefined,
+  modelId: string | undefined,
+  options?: ResolveThinkingLevelOptions,
+): ResolvedThinkingLevel {
+  if (!provider || !modelId) {
+    if (requested === FALLBACK_LEVEL) return { level: FALLBACK_LEVEL };
+    return {
+      level: requested,
+      warning: formatUnconfirmedWarning(requested, provider, modelId),
+    };
+  }
+  const { model, diagnostic } = resolveModel(
+    provider,
+    modelId,
+    options?.registry,
+  );
+  if (!model) {
+    if (requested === FALLBACK_LEVEL) {
+      return diagnostic
+        ? { level: FALLBACK_LEVEL, diagnostic }
+        : { level: FALLBACK_LEVEL };
+    }
+    return {
+      level: requested,
+      warning: formatUnconfirmedWarning(requested, provider, modelId),
+      diagnostic,
+    };
+  }
+  const result = resolveForModel(requested, provider, modelId, model);
+  return diagnostic ? { ...result, diagnostic } : result;
 }
 
 /**

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.
@@ -79,7 +90,7 @@ export function truncateValidUtf8(buffer: Buffer, max: number): string {
 /**
  * Resolves the context window size in tokens for a given message.
  * Returns undefined if the message doesn't have valid provider/model info
- * or if the model lookup fails.
+ * or the model isn't in the built-in catalog.
  *
  * Rationale: Subagent usage reporting needs context window awareness to provide
  * meaningful "context full" indicators to the parent.
@@ -88,16 +99,11 @@ export function resolveContextWindowTokens(msg: Message): number | undefined {
   const m = msg as unknown as Record<string, unknown>;
   if (typeof m["provider"] !== "string" || typeof m["model"] !== "string")
     return;
-  try {
-    const contextWindow = getModel(
-      m["provider"] as never,
-      m["model"] as never,
-    )?.contextWindow;
-    return Number.isFinite(contextWindow) && contextWindow > 0
-      ? contextWindow
-      : undefined;
-  } catch {
-    /* model lookup failures return undefined to skip context window tracking */
-    return;
-  }
+  const contextWindow = getModel(
+    m["provider"] as never,
+    m["model"] as never,
+  )?.contextWindow;
+  return Number.isFinite(contextWindow) && contextWindow > 0
+    ? contextWindow
+    : undefined;
 }