@mystilleef/pi-subagent 0.3.0

package/src/types.ts

@@ -0,0 +1,59 @@
+import type { Message } from "@earendil-works/pi-ai";
+import type { AgentScope } from "./agents.js";
+import type { TerminationMetadata } from "./termination.js";
+
+export interface UsageStats {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  cost: number;
+  contextTokens: number;
+  contextWindowTokens?: number;
+  turns: number;
+}
+
+export interface StreamingProgressToolCall {
+  id: string;
+  preview: string;
+}
+
+export interface StreamingProgress {
+  activityText?: string;
+  toolCalls: StreamingProgressToolCall[];
+  lastToolPreview?: string;
+}
+
+export interface SingleResult {
+  agent: string;
+  agentSource: "user" | "project" | "unknown";
+  task: string;
+  exitCode: number;
+  finalOutput: string;
+  stderr: string;
+  usage: UsageStats;
+  model?: string;
+  stopReason?: string;
+  errorMessage?: string;
+  durationMs?: number;
+  progress?: StreamingProgress;
+  messages?: Message[];
+  termination?: TerminationMetadata;
+}
+
+export interface SubagentDetails {
+  mode: "single";
+  agentScope: AgentScope;
+  projectAgentsDir: string | null;
+  results: SingleResult[];
+}
+
+export interface SubagentToolResult {
+  content: { type: "text"; text: string }[];
+  details: SubagentDetails;
+}
+
+export type OnUpdateCallback = (partial: {
+  content: { type: "text"; text: string }[];
+  details: SubagentDetails;
+}) => void;

package/src/ui.ts

@@ -0,0 +1,218 @@
+import type { Message } from "@earendil-works/pi-ai";
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
+import {
+  Box,
+  type Component,
+  Markdown,
+  type MarkdownTheme,
+  Text,
+} from "@earendil-works/pi-tui";
+import type { AgentScope } from "./agents.js";
+import {
+  extractSemanticToolTarget,
+  normalizeSummaryValue,
+} from "./normalize.js";
+import { hasSubagentFailed } from "./result-details.js";
+import type { SubagentDetails, UsageStats } from "./types.js";
+
+/**
+ * Background theme keys for subagent tool status.
+ */
+export type ThemeBg = "toolPendingBg" | "toolSuccessBg" | "toolErrorBg";
+
+/**
+ * Abstraction for theme-aware text formatting.
+ */
+export type SubagentTheme = {
+  fg: (color: ThemeColor, text: string) => string;
+  bg: (color: ThemeBg, text: string) => string;
+  bold: (text: string) => string;
+};
+
+/**
+ * Formats token counts into human-readable strings (e.g., "1.2k", "1.5M").
+ */
+export function formatTokens(count: number): string {
+  if (count < 1000) return count.toString();
+  if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
+  if (count < 1000000) return `${Math.round(count / 1000)}k`;
+  return `${(count / 1000000).toFixed(1)}M`;
+}
+
+/**
+ * Formats cumulative usage statistics for compact UI display.
+ */
+export function formatUsageStats(
+  usage: UsageStats,
+  model?: string,
+  compact?: boolean,
+): string {
+  const parts: string[] = [];
+  if (usage.turns)
+    parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
+  if (usage.input || usage.output) {
+    const tokens: string[] = [];
+    if (usage.input) tokens.push(`↑${formatTokens(usage.input)}`);
+    if (usage.output) tokens.push(`↓${formatTokens(usage.output)}`);
+    parts.push(tokens.join(" "));
+  }
+  if (!compact && (usage.cacheRead || usage.cacheWrite)) {
+    const cache: string[] = [];
+    if (usage.cacheRead) cache.push(`R${formatTokens(usage.cacheRead)}`);
+    if (usage.cacheWrite) cache.push(`W${formatTokens(usage.cacheWrite)}`);
+    parts.push(`cache:${cache.join("/")}`);
+  }
+  if (!compact && usage.contextTokens && usage.contextTokens > 0)
+    parts.push(`ctx:${formatTokens(usage.contextTokens)}`);
+  if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
+  if (model) parts.push(model);
+  return parts.join(" · ");
+}
+
+/**
+ * Formats millisecond durations into human-readable time strings.
+ */
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return `${Math.floor(ms)}ms`;
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+  const minutes = Math.floor(ms / 60000);
+  const seconds = Math.floor((ms % 60000) / 1000);
+  return `${minutes}m ${seconds.toString().padStart(2, "0")}s`;
+}
+
+/**
+ * Formats the footer for subagent result cards, including model, context, turns, and cost.
+ */
+export function formatResultFooter(
+  usage: UsageStats,
+  model?: string,
+  durationMs?: number,
+): string {
+  const parts: string[] = [];
+  if (model) parts.push(model);
+  if (usage.contextTokens && usage.contextTokens > 0)
+    parts.push(`ctx:${formatTokens(usage.contextTokens)}`);
+  if (usage.turns)
+    parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
+  if (typeof durationMs === "number") parts.push(formatDuration(durationMs));
+  if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
+  return `\n${parts.join(" · ")}`;
+}
+
+/**
+ * Formats a tool call for the UI, optionally extracting a semantic target for clarity.
+ */
+export function formatToolCall(
+  toolName: string,
+  args: Record<string, unknown>,
+  themeFg: (color: ThemeColor, text: string) => string,
+  forceJson = false,
+): string {
+  const target = normalizeSummaryValue(
+    extractSemanticToolTarget(toolName, args, forceJson),
+  );
+  if (!target) return themeFg("accent", toolName);
+  return themeFg("accent", toolName) + themeFg("dim", ` ${target}`);
+}
+
+/**
+ * Extracts the final text response from an array of assistant messages.
+ */
+export function getFinalOutput(messages: Message[]): string {
+  const lastAsst = messages.findLast((m) => m.role === "assistant");
+  const lastText = lastAsst?.content.findLast((p) => p.type === "text");
+  return lastText?.type === "text" ? lastText.text : "";
+}
+
+/**
+ * Removes the "Outcome:" line from subagent output to avoid redundancy in result cards.
+ */
+function stripOutcomeLineForResultUi(output: string): string {
+  const stripped = output.replace(/^\s*Outcome:[^\r\n]*(?:\r?\n|$)/gim, "");
+  return stripped.trim() ? stripped : output;
+}
+
+/**
+ * Maps subagent theme colors to Markdown rendering components.
+ */
+function makeMarkdownTheme(theme: SubagentTheme): MarkdownTheme {
+  const fg = (c: ThemeColor) => (text: string) => theme.fg(c, text);
+  return {
+    heading: fg("mdHeading"),
+    link: fg("mdLink"),
+    linkUrl: fg("mdLinkUrl"),
+    code: fg("mdCode"),
+    codeBlock: fg("mdCodeBlock"),
+    codeBlockBorder: fg("mdCodeBlockBorder"),
+    quote: fg("mdQuote"),
+    quoteBorder: fg("mdQuoteBorder"),
+    hr: fg("mdHr"),
+    listBullet: fg("mdListBullet"),
+    bold: (text) => theme.bold(text),
+    italic: (text) => `\x1b[3m${text}\x1b[23m`,
+    strikethrough: (text) => `\x1b[9m${text}\x1b[29m`,
+    underline: (text) => `\x1b[4m${text}\x1b[24m`,
+  };
+}
+
+/**
+ * Renders the pending subagent call UI component.
+ */
+export function renderSubagentCall(
+  args: { agent?: string; task?: string; agentScope?: AgentScope },
+  theme: SubagentTheme,
+): Text {
+  const scope: AgentScope = args.agentScope ?? "both";
+  const agentName = args.agent || "...";
+  const target = extractSemanticToolTarget("subagent", args);
+  let text =
+    theme.fg("toolTitle", theme.bold("subagent ")) +
+    theme.fg("accent", agentName) +
+    theme.fg("muted", ` [${scope}]`);
+  text += `\n  ${theme.fg("dim", target)}`;
+  return new Text(text, 0, 0, (line) => theme.bg("toolPendingBg", line));
+}
+
+/**
+ * Renders the subagent result box.
+ *
+ * Invariants:
+ * - Red background indicates failure (exit code, error reason, or message error).
+ * - Green background indicates success.
+ * - Trims redundant "Outcome:" lines from the body.
+ * - Displays usage stats and duration in the footer.
+ */
+export function renderSubagentResult(
+  result: { content: { type: string; text?: string }[]; details?: unknown },
+  theme: SubagentTheme,
+  _display?: { isPartial?: boolean },
+  bodyOverride?: string,
+): Component {
+  const details = result.details as SubagentDetails | undefined;
+  const r = details?.results?.[0];
+  if (!r) {
+    const text = result.content[0];
+    return new Text(
+      text?.type === "text" ? (text.text ?? "(no output)") : "(no output)",
+      0,
+      0,
+    );
+  }
+  const failed = hasSubagentFailed(r);
+  const finalOutput = r.finalOutput ?? getFinalOutput(r.messages ?? []);
+  const bg = failed ? "toolErrorBg" : "toolSuccessBg";
+  const box = new Box(1, 1, (line) => theme.bg(bg, line));
+  const bodyText = stripOutcomeLineForResultUi(bodyOverride ?? finalOutput);
+  if (bodyText) {
+    box.addChild(
+      new Markdown(bodyText, 0, 0, makeMarkdownTheme(theme), {
+        color: (text) => theme.fg("toolOutput", text),
+      }),
+    );
+  } else {
+    box.addChild(new Text(theme.fg("muted", "(no output)"), 0, 0));
+  }
+  const usageStr = formatResultFooter(r.usage, r.model, r.durationMs);
+  if (usageStr) box.addChild(new Text(theme.fg("dim", usageStr), 0, 0));
+  return box;
+}

package/src/utils.ts

@@ -0,0 +1,165 @@
+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,
+  withFileMutationQueue,
+} from "@earendil-works/pi-coding-agent";
+
+export const DEFAULT_MAX_OUTPUT_BYTES = 50_000;
+export const DEFAULT_MAX_OUTPUT_LINES = 500;
+
+export interface SubagentOutputLimits {
+  maxBytes: number;
+  maxLines: number;
+}
+
+type OutputLimitConfig = 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) || parsed < 1) return undefined;
+  return Math.floor(parsed);
+}
+
+export function getSubagentOutputLimits(
+  config: OutputLimitConfig = 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 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}`;
+}
+
+export async function writePromptToTempFile(
+  agentName: string,
+  prompt: string,
+): Promise<{ dir: string; filePath: string }> {
+  const tmpDir = await fs.promises.mkdtemp(
+    path.join(os.tmpdir(), "pi-subagent-"),
+  );
+  const safeName = agentName.replace(/[^\w.-]+/g, "_");
+  const filePath = path.join(tmpDir, `prompt-${safeName}.md`);
+  await withFileMutationQueue(filePath, async () => {
+    await fs.promises.writeFile(filePath, prompt, {
+      encoding: "utf-8",
+      mode: 0o600,
+    });
+  });
+  return { dir: tmpDir, filePath };
+}
+
+export function getPiInvocation(args: string[]): {
+  command: string;
+  args: string[];
+} {
+  const currentScript = process.argv[1];
+  if (currentScript && fs.existsSync(currentScript)) {
+    return { command: process.execPath, args: [currentScript, ...args] };
+  }
+  const execName = path.basename(process.execPath).toLowerCase();
+  const isGenericRuntime = /^(node|bun)(\.exe)?$/.test(execName);
+  if (!isGenericRuntime) {
+    return { command: process.execPath, args };
+  }
+  return { command: "pi", args };
+}
+
+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 loader = new DefaultResourceLoader({
+    cwd,
+    agentDir: getAgentDir(),
+    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}.`,
+    };
+  }
+  return {
+    args: requested.flatMap((name) => [
+      "--skill",
+      skillMap.get(name)?.filePath ?? name,
+    ]),
+  };
+}
+
+export function getSubagentDepth(): number {
+  const d = Number(process.env.PI_SUBAGENT_DEPTH ?? "0");
+  if (!Number.isFinite(d) || d < 0) return 0;
+  return Math.floor(d);
+}
+
+export function subagentDepthEnv(): Record<string, string> {
+  return { PI_SUBAGENT_DEPTH: String(getSubagentDepth() + 1) };
+}
+
+export function detectMessageError(messages: Message[]): boolean {
+  let lastAssistantIdx = -1;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (
+      msg?.role === "assistant" &&
+      msg.content.some((c) => c.type === "text" && c.text.trim().length > 0)
+    ) {
+      lastAssistantIdx = i;
+      break;
+    }
+  }
+  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;
+}

package/tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+    "types": ["bun"],
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}