@mystilleef/pi-subagent 0.10.2 → 0.12.0

package/src/progress/result-details.ts

@@ -79,6 +79,47 @@ function redactSensitiveDebugMessages(messages: unknown): unknown {
   return messages.map(redactSensitiveDebugValue);
 }
 
+function sanitizeProgressObject(
+  progress: SingleResult["progress"],
+  _includeDebugMessages: boolean,
+): StreamingProgress | undefined {
+  if (!progress) return undefined;
+  const {
+    activityText,
+    activeToolActivity,
+    lastToolPreview,
+    toolResultCompleted,
+    ...progBase
+  } = progress;
+  return {
+    toolCalls: progBase.toolCalls.map((tc) => ({
+      id: tc.id,
+      preview: tc.preview,
+    })),
+    ...(activityText !== undefined && { activityText }),
+    ...(activeToolActivity !== undefined && { activeToolActivity }),
+    ...(lastToolPreview !== undefined && { lastToolPreview }),
+    ...(toolResultCompleted !== undefined && { toolResultCompleted }),
+  };
+}
+
+function sanitizeTerminationObject(
+  termination: TerminationMetadata | undefined,
+  includeMessages: boolean,
+  includeDebugMessages: boolean,
+): TerminationMetadata | undefined {
+  if (!includeMessages || !includeDebugMessages || !termination)
+    return undefined;
+  const { cancelReason, terminationSignal, fallbackCause, ...termBase } =
+    termination;
+  return {
+    ...termBase,
+    ...(cancelReason !== undefined && { cancelReason }),
+    ...(terminationSignal !== undefined && { terminationSignal }),
+    ...(fallbackCause !== undefined && { fallbackCause }),
+  };
+}
+
 export function sanitizeResultDetails(
   result: SingleResult,
   includeDebugMessages: boolean,
@@ -88,37 +129,6 @@ export function sanitizeResultDetails(
     includeDebugMessages && (options?.includeMessages ?? true);
   const { messages, termination, progress, stderr, usage, ...core } = result;
   const { contextWindowTokens, ...usageBase } = usage;
-  let progressValue: StreamingProgress | undefined;
-  if (progress) {
-    const {
-      activityText,
-      activeToolActivity,
-      lastToolPreview,
-      toolResultCompleted,
-      ...progBase
-    } = progress;
-    progressValue = {
-      toolCalls: progBase.toolCalls.map((tc) => ({
-        id: tc.id,
-        preview: tc.preview,
-      })),
-      ...(activityText !== undefined && { activityText }),
-      ...(activeToolActivity !== undefined && { activeToolActivity }),
-      ...(lastToolPreview !== undefined && { lastToolPreview }),
-      ...(toolResultCompleted !== undefined && { toolResultCompleted }),
-    };
-  }
-  let terminationValue: TerminationMetadata | undefined;
-  if (includeMessages && includeDebugMessages && termination) {
-    const { cancelReason, terminationSignal, fallbackCause, ...termBase } =
-      termination;
-    terminationValue = {
-      ...termBase,
-      ...(cancelReason !== undefined && { cancelReason }),
-      ...(terminationSignal !== undefined && { terminationSignal }),
-      ...(fallbackCause !== undefined && { fallbackCause }),
-    };
-  }
   const sanitized: SingleResult = {
     ...core,
     stderr: includeDebugMessages ? stderr : "",
@@ -127,6 +137,7 @@ export function sanitizeResultDetails(
       ...(contextWindowTokens !== undefined && { contextWindowTokens }),
     },
   };
+  const progressValue = sanitizeProgressObject(progress, includeDebugMessages);
   if (progressValue !== undefined) sanitized.progress = progressValue;
   if (includeMessages) {
     sanitized.messages = options?.recentMessages
@@ -135,6 +146,11 @@ export function sanitizeResultDetails(
         ? [...messages]
         : undefined;
   }
+  const terminationValue = sanitizeTerminationObject(
+    termination,
+    includeMessages,
+    includeDebugMessages,
+  );
   if (terminationValue !== undefined) sanitized.termination = terminationValue;
   return sanitized;
 }
@@ -224,19 +240,12 @@ export function patchProgressFromDetails(
   patchProgressState(requestId, patch);
 }
 
-function getSubagentText(result: SubagentToolResult): string {
-  return (result.content[0] as { text?: string })?.text ?? "";
-}
-
-export function getResultDisplayText(result: SubagentToolResult): string {
-  return (
-    getLatestResult(result.details)?.finalOutput ?? getSubagentText(result)
-  );
-}
-
 export function getFeedbackSummaryText(result: SubagentToolResult): string {
-  const rawFinalOutput = getLatestResult(result.details)?.finalOutput;
-  if (rawFinalOutput?.trim())
-    return summarizeFeedbackUiFinalOutput(rawFinalOutput);
-  return getSubagentText(result).trim() || "(no output)";
+  const latestResult = getLatestResult(result.details);
+  const rawFinalOutput = latestResult?.finalOutput ?? "";
+  const outcome = latestResult?.outcome;
+  if (!outcome?.trim() && !rawFinalOutput.trim()) {
+    return "(no output)";
+  }
+  return summarizeFeedbackUiFinalOutput(rawFinalOutput, outcome);
 }

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/sampling.ts

@@ -0,0 +1,56 @@
+export interface SamplingParams {
+  temperature?: number | undefined;
+  topP?: number | undefined;
+}
+
+export function isValidSamplingValue(value: unknown): value is number {
+  return (
+    typeof value === "number" &&
+    Number.isFinite(value) &&
+    value >= 0.0 &&
+    value <= 1.0
+  );
+}
+
+/**
+ * Parses a JSON-encoded sampling parameters string.
+ * Returns undefined for missing, malformed, or wholly invalid values.
+ */
+export function parseSamplingParams(
+  envVal?: string,
+): SamplingParams | undefined {
+  if (!envVal) return undefined;
+  try {
+    const parsed = JSON.parse(envVal);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+      return undefined;
+    const { temperature: rawTemperature, topP: rawTopP } = parsed as Record<
+      string,
+      unknown
+    >;
+    const result: SamplingParams = {};
+    if (isValidSamplingValue(rawTemperature))
+      result.temperature = rawTemperature;
+    if (isValidSamplingValue(rawTopP)) result.topP = rawTopP;
+    if (result.temperature !== undefined || result.topP !== undefined)
+      return result;
+  } catch {
+    /* malformed env value: run without sampling overrides */
+  }
+  return undefined;
+}
+
+/**
+ * Serializes sampling parameters into a JSON string for environment passing.
+ * Returns undefined when no valid parameters are present.
+ */
+export function serializeSamplingParams(
+  params: SamplingParams,
+): string | undefined {
+  if (params.temperature === undefined && params.topP === undefined)
+    return undefined;
+  const config: SamplingParams = {};
+  if (params.temperature !== undefined) config.temperature = params.temperature;
+  if (params.topP !== undefined) config.topP = params.topP;
+  return JSON.stringify(config);
+}

package/src/shared/types.ts

@@ -52,6 +52,7 @@ export interface SingleResult {
   messages?: Message[] | undefined;
   termination?: TerminationMetadata | undefined;
   thinkingWarning?: string | undefined;
+  outcome?: string | undefined;
 }
 
 export interface SubagentDetails {