@mystilleef/pi-subagent 0.10.2 → 0.11.0

package/README.md

@@ -126,6 +126,8 @@ skills: code-review
 thinking: medium
 provider: deepseek
 model: deepseek-v4-flash
+temperature: 0.7
+top_p: 0.9
 ```
 
 ### Accepted thinking values

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mystilleef/pi-subagent",
-  "version": "0.10.2",
+  "version": "0.11.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.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",
     "@types/bun": "^1.3.14",
-    "@types/node": "^25.9.3",
-    "typebox": "^1.2.11",
+    "@types/node": "^26.0.1",
+    "typebox": "^1.3.0",
     "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";
@@ -25,6 +26,8 @@ export interface AgentConfig {
   thinking?: ThinkingLevel | undefined;
   model?: string | undefined;
   provider?: string | undefined;
+  temperature?: number | undefined;
+  topP?: number | undefined;
   systemPrompt: string;
   source: AgentSource;
   filePath: string;
@@ -82,6 +85,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,
@@ -109,21 +129,24 @@ function parseAgentConfig(
     thinking: rawThinking,
     model: rawModel,
     provider: rawProvider,
+    temperature: rawTemperature,
+    top_p: rawTopP,
   } = 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 (isNonStringOptional(rawTools)) return null;
+  if (isNonStringOptional(rawSkills)) 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 !== 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);
   return {
     name,
     description,
@@ -135,6 +158,8 @@ function parseAgentConfig(
     systemPrompt: body,
     source,
     filePath,
+    ...(temperature !== undefined && { temperature }),
+    ...(topP !== undefined && { topP }),
   };
 }
 

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,103 @@
+/**
+ * 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);
+}
+
+/**
+ * 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;
+  }
+}