@mystilleef/pi-subagent 0.10.2 → 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,19 +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.10.2",
+  "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.0",
-    "@earendil-works/pi-agent-core": "^0.79.4",
-    "@earendil-works/pi-ai": "^0.79.4",
-    "@earendil-works/pi-coding-agent": "^0.79.4",
-    "@earendil-works/pi-tui": "^0.79.4",
+    "@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": "^25.9.3",
-    "typebox": "^1.2.11",
+    "@types/node": "^26.1.0",
+    "typebox": "^1.3.4",
     "typescript": "^6.0.3"
   }
 }

package/src/agent/agents.ts

@@ -2,6 +2,7 @@ import type { Dirent } from "node:fs";
 import * as fsPromises from "node:fs/promises";
 import * as path from "node:path";
 import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { isValidSamplingValue } from "../shared/sampling.js";
 
 export type AgentSource = "user" | "project";
 export type AgentScope = AgentSource | "both";
@@ -20,11 +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;
@@ -68,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();
@@ -82,6 +103,23 @@ function parseOptionalString(raw: unknown): string | undefined {
   return normalized.length > 0 ? normalized : undefined;
 }
 
+function isNonStringOptional(raw: unknown): boolean {
+  return raw != null && typeof raw !== "string";
+}
+
+function parseSamplingValue(
+  raw: unknown,
+  field: string,
+  agentName: string,
+): number | undefined {
+  if (raw === undefined) return undefined;
+  if (isValidSamplingValue(raw)) return raw;
+  console.warn(
+    `Warning: Agent '${agentName}' has invalid '${field}' value: ${raw}`,
+  );
+  return undefined;
+}
+
 function parseAgentConfig(
   content: string,
   source: AgentSource,
@@ -104,26 +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 (rawTools != null && typeof rawTools !== "string") return null;
-  if (rawSkills != null && typeof rawSkills !== "string") return null;
-  if (rawThinking != null && typeof rawThinking !== "string") return null;
-  if (rawModel != null && typeof rawModel !== "string") return null;
-  if (rawProvider != null && typeof rawProvider !== "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 (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 = Object.hasOwn(frontmatter, "skills")
-    ? (parseCommaList(rawSkills) ?? [])
-    : undefined;
+  const skills =
+    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,
@@ -135,6 +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/complete-extension.ts

@@ -0,0 +1,36 @@
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+export const completeParams = Type.Object({
+  outcome: Type.String({
+    description:
+      "A short, single-sentence summary of the task outcome. Keep it concise, brief, and under 100 characters.",
+    minLength: 1,
+    pattern: "^[\\s\\S]*\\S[\\s\\S]*$",
+  }),
+});
+
+export const completeTool = defineTool({
+  name: "complete",
+  label: "Complete",
+  description:
+    "Complete the task and report the structured outcome. Call this as your final action.",
+  promptSnippet: "Complete the task and report the structured outcome.",
+  promptGuidelines: [
+    "Call complete as your final action to report the outcome after completing the task.",
+  ],
+  parameters: completeParams,
+  async execute(_toolCallId, params) {
+    return {
+      content: [{ type: "text", text: params.outcome }],
+      details: {
+        outcome: params.outcome,
+      },
+      terminate: true,
+    };
+  },
+});
+
+export default function (pi: ExtensionAPI) {
+  pi.registerTool(completeTool);
+}

package/src/child/complete-outcome.ts

@@ -0,0 +1,35 @@
+import type { Message } from "@earendil-works/pi-ai";
+import { Value } from "typebox/value";
+import { completeParams } from "./complete-extension.js";
+
+export function getOutcomeString(source: unknown): string | undefined {
+  if (Value.Check(completeParams, source)) {
+    return source.outcome.trim();
+  }
+  return undefined;
+}
+
+/**
+ * Extracts the latest valid outcome from complete tool call arguments in messages.
+ *
+ * Reads from call arguments (message_end) rather than tool results (tool_result_end)
+ * because tool_result_end is unreliable when terminate: true causes pi to exit before
+ * delivering it. Call arguments are always delivered via message_end.
+ */
+export function getLatestOutcomeFromMessages(
+  messages: Message[] | undefined,
+): string | undefined {
+  if (!messages?.length) return undefined;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (msg?.role !== "assistant" || !Array.isArray(msg.content)) continue;
+    for (let j = msg.content.length - 1; j >= 0; j--) {
+      const part = msg.content[j];
+      if (part?.type !== "toolCall") continue;
+      if (part.name !== "complete" || !part.id) continue;
+      const outcome = getOutcomeString(part.arguments);
+      if (outcome) return outcome;
+    }
+  }
+  return undefined;
+}

package/src/child/model-resolution.ts

@@ -0,0 +1,81 @@
+/**
+ * Model and thinking level resolution for subagent child processes.
+ * Handles provider/model selection and thinking level clamping.
+ */
+
+import {
+  clampThinkingLevel,
+  getSupportedThinkingLevels,
+  type ModelThinkingLevel,
+} from "@earendil-works/pi-ai";
+import { getModel } from "@earendil-works/pi-ai/compat";
+import type { ThinkingLevel } from "../agent/agents.js";
+
+export type ChildModelSettings = {
+  provider?: string | undefined;
+  id?: string | undefined;
+};
+
+/**
+ * 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.
+ */
+export function resolveThinkingLevel(
+  requested: ThinkingLevel,
+  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`;
+  if (model.reasoning === false) {
+    return { level: "off", warning: mkWarning("off") };
+  }
+  if (!model.thinkingLevelMap) return { level: requested };
+  const supported = getSupportedThinkingLevels(model);
+  if (supported.length === 0) return { level: requested };
+  const clamped = clampThinkingLevel(
+    model,
+    requested as ModelThinkingLevel,
+  ) as ThinkingLevel;
+  if (clamped === requested) return { level: requested };
+  return { level: clamped, warning: mkWarning(clamped) };
+}
+
+/**
+ * Resolves effective child model settings by merging agent config with parent settings.
+ * Agent-specific settings take precedence over parent settings.
+ */
+export function resolveEffectiveChildModelSettings(
+  agent: { provider?: string | undefined; model?: string | undefined },
+  parentModel: ChildModelSettings | undefined,
+): ChildModelSettings {
+  return {
+    provider: agent.provider ?? parentModel?.provider,
+    id:
+      agent.model ??
+      (agent.provider === undefined ? parentModel?.id : undefined),
+  };
+}
+
+/**
+ * Builds a display string for the model and thinking level.
+ * Returns undefined if no parts are available.
+ */
+export function buildModelDisplay(
+  effectiveModel: ChildModelSettings,
+  thinking: ThinkingLevel,
+): string | undefined {
+  const parts: string[] = [];
+  if (effectiveModel.provider) {
+    parts.push(effectiveModel.provider);
+  }
+  if (effectiveModel.id) {
+    parts.push(effectiveModel.id);
+  }
+  if (thinking) {
+    parts.push(thinking);
+  }
+  return parts.length > 0 ? parts.join(" ･ ") : undefined;
+}

package/src/child/process-utils.ts

@@ -0,0 +1,114 @@
+/**
+ * Utility functions for child process management.
+ * Handles byte-limited string appending, UTF-8 truncation, and context window resolution.
+ */
+
+import * as fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Message } from "@earendil-works/pi-ai";
+import { getModel } from "@earendil-works/pi-ai/compat";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+function resolveExtensionPath(baseName: string, dir?: string): string {
+  const resolvedDir = dir ?? __dirname;
+  const ext = __filename.endsWith(".ts") ? ".ts" : ".js";
+  const primary = path.join(resolvedDir, `${baseName}${ext}`);
+  if (fs.existsSync(primary)) return primary;
+  const altExt = ext === ".ts" ? ".js" : ".ts";
+  const fallback = path.join(resolvedDir, `${baseName}${altExt}`);
+  if (fs.existsSync(fallback)) return fallback;
+  throw new Error(`${baseName} not found at ${primary} or ${fallback}`);
+}
+
+/**
+ * Resolves the absolute path to the complete-extension file.
+ * 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 resolveCompleteExtensionPath(dir?: string): string {
+  return resolveExtensionPath("complete-extension", dir);
+}
+
+/**
+ * Resolves the absolute path to the sampling-extension file.
+ * 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 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.
+ */
+export function appendWithByteLimit(
+  current: string,
+  data: string | Buffer,
+  max: number,
+): string {
+  const currentBytes = Buffer.from(current, "utf-8");
+  if (currentBytes.length >= max) return current;
+  const incomingBytes = Buffer.isBuffer(data)
+    ? data
+    : Buffer.from(data, "utf-8");
+  const combined = Buffer.concat([currentBytes, incomingBytes]);
+  if (combined.length <= max) return combined.toString("utf-8");
+  return truncateValidUtf8(combined, max);
+}
+
+/**
+ * Truncates a buffer to the specified byte limit while preserving valid UTF-8 sequences.
+ * Returns an empty string if no valid truncation point is found.
+ */
+export function truncateValidUtf8(buffer: Buffer, max: number): string {
+  let end = Math.min(max, buffer.length);
+  while (end > 0) {
+    const candidate = buffer.subarray(0, end).toString("utf-8");
+    if (!candidate.endsWith("�")) return candidate;
+    end -= 1;
+  }
+  return "";
+}
+
+/**
+ * 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.
+ *
+ * Rationale: Subagent usage reporting needs context window awareness to provide
+ * meaningful "context full" indicators to the parent.
+ */
+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;
+  }
+}