pi-open-agents 0.1.0

package/src/subagent/prompt.ts

@@ -0,0 +1,79 @@
+/**
+ * Child system prompt construction for subagents.
+ *
+ * Builds the system prompt that will be passed to the child pi process.
+ * Includes the agent body and optional skill injection.
+ */
+
+import type { AgentDefinition } from "../types.ts";
+import { escapeXml } from "../utils/format.ts";
+import { resolveSkills, type ResolveSkillsResult } from "./skills.ts";
+
+export interface BuildPromptOptions {
+  agent: AgentDefinition;
+  cwd: string;
+  agentDir?: string;
+}
+
+export interface BuildPromptResult {
+  prompt: string;
+  skills: ResolveSkillsResult;
+}
+
+/**
+ * Format resolved skills as an XML block for injection into the system prompt.
+ */
+function formatSkillsForPrompt(
+  skills: Array<{ name: string; description: string; location: string }>,
+): string {
+  if (skills.length === 0) return "";
+
+  const lines = [
+    "\n\nThe following skills provide specialized instructions for specific tasks.",
+    "Use the read tool to load a skill's file when the task matches its description.",
+    "When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md / dirname of the path) and use that absolute path in tool commands.",
+    "",
+    "<available_skills>",
+  ];
+
+  for (const skill of skills) {
+    lines.push("  <skill>");
+    lines.push(`    <name>${escapeXml(skill.name)}</name>`);
+    lines.push(`    <description>${escapeXml(skill.description)}</description>`);
+    lines.push(`    <location>${escapeXml(skill.location)}</location>`);
+    lines.push("  </skill>");
+  }
+
+  lines.push("</available_skills>");
+  return lines.join("\n");
+}
+
+/**
+ * Build the system prompt for a subagent.
+ *
+ * Starts with the agent body, appends skill injection if the agent has skills.
+ */
+export async function buildSubagentPrompt(options: BuildPromptOptions): Promise<BuildPromptResult> {
+  let prompt = options.agent.prompt;
+
+  let skillsResult: ResolveSkillsResult = {
+    resolved: [],
+    missing: [],
+    skippedPackages: [],
+    warnings: [],
+  };
+
+  if (options.agent.skills && options.agent.skills.length > 0) {
+    skillsResult = await resolveSkills(options.agent.skills, {
+      cwd: options.cwd,
+      agentDir: options.agentDir,
+    });
+
+    const injection = formatSkillsForPrompt(skillsResult.resolved);
+    if (injection) {
+      prompt = `${prompt}${injection}`;
+    }
+  }
+
+  return { prompt, skills: skillsResult };
+}

package/src/subagent/render.ts

@@ -0,0 +1,251 @@
+/**
+ * TUI rendering for subagent results.
+ *
+ * Provides collapsed and expanded views showing:
+ * - Status line (✓/✗ agent — N tools · Xs)
+ * - Tool call list
+ * - Output summary (collapsed) or full output (expanded)
+ * - Usage stats
+ */
+
+import type { AgentProgress, AgentResult } from "./executor.ts";
+import { numberArg, preview, shortenPath, stringArg, formatTokens } from "../utils/format.ts";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface RenderOptions {
+  expanded: boolean;
+  suppressOutput?: boolean;
+  suppressUsage?: boolean;
+  expandHint?: string;
+}
+
+export type ResultLineKind = "status" | "tool" | "hint" | "usage" | "output" | "blank";
+
+export interface ResultLine {
+  text: string;
+  kind: ResultLineKind;
+  singleLine: boolean;
+  tool?: {
+    name: string;
+    args: Record<string, unknown>;
+    status: "running" | "done" | "error";
+  };
+}
+
+export type ContextUsageSeverity = "dim" | "warning" | "error";
+
+const TOOL_LOG_LIMIT = 20;
+
+// ─── Usage Formatting ────────────────────────────────────────────────────────
+
+export function contextUsageSeverity(usage: {
+  contextTokens?: number;
+  contextWindow?: number;
+}): ContextUsageSeverity {
+  if (!usage.contextWindow || usage.contextWindow <= 0) return "dim";
+  const percent = (usage.contextTokens ?? 0) / usage.contextWindow;
+  if (percent >= 0.9) return "error";
+  if (percent >= 0.7) return "warning";
+  return "dim";
+}
+
+function elapsedSeconds(ms: number): number {
+  return Math.round(ms / 1000);
+}
+
+export function formatUsage(progress: AgentProgress): string {
+  const usage = progress.usage;
+  const parts: string[] = [];
+
+  if (usage.contextWindow && usage.contextWindow > 0) {
+    const percent = ((usage.contextTokens / usage.contextWindow) * 100).toFixed(1);
+    parts.push(`${percent}%/${formatTokens(usage.contextWindow)}`);
+  }
+
+  parts.push(`↑${formatTokens(usage.input)}`);
+  parts.push(`↓${formatTokens(usage.output)}`);
+  parts.push(`R${formatTokens(usage.cacheRead)}`);
+  if (usage.cacheWrite) parts.push(`W${formatTokens(usage.cacheWrite)}`);
+  parts.push(`$${usage.cost.toFixed(3)}`);
+
+  return parts.join(" ");
+}
+
+// ─── Tool Title Formatting ───────────────────────────────────────────────────
+
+function pathArg(args: Record<string, unknown>, fallback?: string): string {
+  return shortenPath(args.path ?? args.file_path) ?? fallback ?? "...";
+}
+
+function lineRange(args: Record<string, unknown>): string {
+  if (args.offset === undefined && args.limit === undefined) return "";
+  const startLine = numberArg(args, "offset") ?? 1;
+  const limit = numberArg(args, "limit");
+  const endLine = limit !== undefined ? startLine + limit - 1 : undefined;
+  return `:${startLine}${endLine !== undefined ? `-${endLine}` : ""}`;
+}
+
+function limitSuffix(args: Record<string, unknown>): string {
+  const limit = numberArg(args, "limit");
+  return limit !== undefined ? ` (limit ${limit})` : "";
+}
+
+function formatToolTitle(name: string, args: Record<string, unknown>): string {
+  switch (name) {
+    case "read":
+      return `read ${pathArg(args)}${lineRange(args)}`;
+    case "bash": {
+      const command = stringArg(args, "command") ?? "";
+      const timeout = numberArg(args, "timeout");
+      return `$ ${command}${timeout !== undefined ? ` (timeout ${timeout}s)` : ""}`;
+    }
+    case "edit":
+      return `edit ${pathArg(args)}`;
+    case "write":
+      return `write ${pathArg(args)}`;
+    case "find": {
+      const pattern = stringArg(args, "pattern") ?? "";
+      return `find ${pattern} in ${pathArg(args, ".")}${limitSuffix(args)}`;
+    }
+    case "grep": {
+      const pattern = stringArg(args, "pattern") ?? "";
+      const glob = stringArg(args, "glob");
+      const globSuffix = glob ? ` (${glob})` : "";
+      const limit = numberArg(args, "limit");
+      const limitText = limit !== undefined ? ` limit ${limit}` : "";
+      return `grep /${pattern}/ in ${pathArg(args, ".")}${globSuffix}${limitText}`;
+    }
+    case "ls":
+      return `ls ${pathArg(args, ".")}${limitSuffix(args)}`;
+    case "webfetch": {
+      const url = stringArg(args, "url") ?? "";
+      const mode = stringArg(args, "mode");
+      return `webfetch ${url}${mode ? ` (${mode})` : ""}`.trimEnd();
+    }
+    case "subagent": {
+      const agent = stringArg(args, "agent");
+      const task = stringArg(args, "task");
+      const taskPreview = task ? ` ${JSON.stringify(preview(task, 60))}` : "";
+      return `${name} ${agent ?? ""}${taskPreview}`.trimEnd();
+    }
+    default: {
+      const values = Object.values(args).filter((v) => typeof v === "string") as string[];
+      return `${name}${values.length > 0 ? ` ${JSON.stringify(preview(values[0], 80))}` : ""}`;
+    }
+  }
+}
+
+// ─── Line Formatting ─────────────────────────────────────────────────────────
+
+function indent(text: string, spaces: number): string {
+  const prefix = " ".repeat(spaces);
+  return text
+    .split("\n")
+    .map((line) => `${prefix}${line}`)
+    .join("\n");
+}
+
+function summaryText(markdown: string): string {
+  return markdown.split("\n").slice(0, 20).join("\n");
+}
+
+function formatToolLineItems(
+  progress: AgentProgress,
+  options: RenderOptions,
+): ResultLine[] {
+  const lines: ResultLine[] = [];
+  const hiddenCount = options.expanded ? 0 : Math.max(0, progress.tools.length - TOOL_LOG_LIMIT);
+  const visibleTools = progress.tools.slice(hiddenCount);
+
+  if (hiddenCount > 0) {
+    const expandHint = options.expandHint ?? "to expand";
+    lines.push({
+      text: `  ... (${hiddenCount} earlier tool calls, ${expandHint})`,
+      kind: "hint",
+      singleLine: true,
+    });
+  }
+
+  for (const tool of visibleTools) {
+    lines.push({
+      text: `${tool.status === "running" ? "▸" : " "} ${formatToolTitle(tool.name, tool.args)}`,
+      kind: "tool",
+      singleLine: true,
+      tool: { name: tool.name, args: tool.args, status: tool.status },
+    });
+    if ((options.expanded || progress.status === "running") && tool.nested) {
+      for (const line of formatResultLines(tool.nested, {
+        expanded: false,
+        suppressOutput: true,
+      })) {
+        lines.push({ ...line, text: indent(line.text, 2) });
+      }
+    }
+  }
+
+  return lines;
+}
+
+export function formatSubagentCall(args: {
+  agent?: string;
+  task?: string;
+}, options: Partial<RenderOptions> = {}): string {
+  if (options.expanded) return `subagent ${args.agent ?? "..."}\n${args.task ?? "..."}`;
+  return `subagent ${args.agent ?? "..."} ${preview(args.task ?? "...", 60)}`;
+}
+
+export function formatResultLines(
+  progress: AgentProgress,
+  options: RenderOptions,
+): ResultLine[] {
+  const icon = progress.status === "error" ? "✗" : progress.status === "done" ? "✓" : "▸";
+  const sessionBadge = progress.session?.effective === "fork" ? " [fork]" : "";
+  const statusLine = `${icon} ${progress.agent}${sessionBadge}${progress.model ? ` (${progress.model})` : ""} — ${progress.tools.length} tools · ${elapsedSeconds(progress.elapsedMs)}s`;
+  const toolLines = formatToolLineItems(progress, options);
+  const usage = formatUsage(progress);
+
+  const lines: ResultLine[] = [
+    { text: "", kind: "blank", singleLine: false },
+    { text: statusLine, kind: "status", singleLine: false },
+    ...(progress.session?.warning
+      ? [{ text: `session: ${progress.session.warning}`, kind: "hint" as const, singleLine: true }]
+      : []),
+    ...toolLines,
+  ];
+
+  if (progress.status === "running" || options.suppressOutput) {
+    if (!options.suppressUsage) {
+      lines.push({ text: "", kind: "blank", singleLine: false });
+      lines.push({ text: usage, kind: "usage", singleLine: false });
+    }
+    return lines;
+  }
+
+  const output = options.expanded
+    ? progress.output || "(no output)"
+    : summaryText(progress.output) || "(no output)";
+
+  lines.push({ text: "", kind: "blank", singleLine: false });
+  lines.push({ text: output, kind: "output", singleLine: false });
+
+  if (!options.expanded) {
+    const totalLines = (progress.output || "").split("\n").length;
+    if (totalLines > 20) {
+      const hidden = totalLines - 20;
+      const expandHint = options.expandHint ?? "to expand";
+      lines.push({
+        text: `... (${hidden} more lines, ${expandHint})`,
+        kind: "hint",
+        singleLine: true,
+      });
+    }
+  }
+
+  if (!options.suppressUsage) {
+    lines.push({ text: "", kind: "blank", singleLine: false });
+    lines.push({ text: usage, kind: "usage", singleLine: false });
+  }
+
+  return lines;
+}

package/src/subagent/skills.ts

@@ -0,0 +1,274 @@
+/**
+ * Per-agent skill resolution with wildcard support.
+ *
+ * Collects skills from multiple directories and resolves them against
+ * an agent's skill list (which may include wildcards like "lark-*").
+ */
+
+import {
+  DefaultPackageManager,
+  SettingsManager,
+  getAgentDir,
+  type ResolvedResource,
+} from "@earendil-works/pi-coding-agent";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { parseFrontmatter } from "../config/frontmatter.ts";
+
+export interface ResolvedSkill {
+  name: string;
+  description: string;
+  location: string;
+}
+
+export interface ResolveSkillsOptions {
+  cwd: string;
+  agentDir?: string;
+  globalDir?: string;
+  fs?: SkillResolverFs;
+  packageSkillFiles?: string[];
+}
+
+export interface ResolveSkillsResult {
+  resolved: ResolvedSkill[];
+  missing: string[];
+  skippedPackages: string[];
+  warnings: string[];
+}
+
+export interface SkillResolverFs {
+  exists(filePath: string): boolean;
+  readFile(filePath: string): string;
+  listFiles?(dir: string): string[];
+}
+
+// ─── Default FS ──────────────────────────────────────────────────────────────
+
+const defaultSkillFs: SkillResolverFs = {
+  exists(filePath) {
+    return fs.existsSync(filePath);
+  },
+  readFile(filePath) {
+    return fs.readFileSync(filePath, "utf-8");
+  },
+  listFiles(dir) {
+    try {
+      return fs
+        .readdirSync(dir, { withFileTypes: true })
+        .map((entry) => path.join(dir, entry.name))
+        .sort();
+    } catch {
+      return [];
+    }
+  },
+};
+
+function defaultGlobalSkillsDir(): string {
+  return path.join(os.homedir(), ".pi", "agent", "skills");
+}
+
+// ─── Skill File Reading ──────────────────────────────────────────────────────
+
+interface ReadSkillResult {
+  skill?: ResolvedSkill;
+  warning?: string;
+}
+
+function readSkill(filePath: string, fileSystem: SkillResolverFs): ReadSkillResult | undefined {
+  const content = fileSystem.readFile(filePath);
+  const { data } = parseFrontmatter(content);
+
+  const name = typeof data.name === "string" ? data.name.trim() : "";
+  const description = typeof data.description === "string" ? data.description.trim() : "";
+
+  if (!name) {
+    return { warning: `skill missing required field: name: ${filePath}` };
+  }
+  if (!description) return undefined;
+
+  return {
+    skill: { name, description, location: filePath },
+  };
+}
+
+// ─── Collection ──────────────────────────────────────────────────────────────
+
+interface CollectedSkills {
+  byName: Map<string, ResolvedSkill>;
+  warnings: string[];
+  skippedPackages: string[];
+}
+
+const collectedSkillsCache = new Map<string, Promise<CollectedSkills>>();
+
+function listSkillFilesInDir(dir: string, fileSystem: SkillResolverFs): string[] {
+  if (!fileSystem.listFiles) return [];
+  return fileSystem
+    .listFiles(dir)
+    .map((entry) => path.join(entry, "SKILL.md"))
+    .filter((filePath) => fileSystem.exists(filePath));
+}
+
+function addSkillFile(
+  filePath: string,
+  fileSystem: SkillResolverFs,
+  byName: Map<string, ResolvedSkill>,
+  warnings: string[],
+): void {
+  try {
+    const result = readSkill(filePath, fileSystem);
+    if (!result) return;
+    if (result.warning) warnings.push(result.warning);
+    if (result.skill && !byName.has(result.skill.name)) {
+      byName.set(result.skill.name, result.skill);
+    }
+  } catch (error) {
+    warnings.push(
+      `skill could not be read: ${filePath}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
+async function resolvePackageSkillFiles(
+  options: ResolveSkillsOptions,
+): Promise<{ files: string[]; skippedPackages: string[] }> {
+  if (options.packageSkillFiles) {
+    return { files: options.packageSkillFiles, skippedPackages: [] };
+  }
+  if (options.fs) {
+    return { files: [], skippedPackages: [] };
+  }
+
+  const skippedPackages: string[] = [];
+  const agentDir = options.agentDir ?? getAgentDir();
+  const settingsManager = SettingsManager.create(options.cwd, agentDir);
+  const packageManager = new DefaultPackageManager({
+    cwd: options.cwd,
+    agentDir,
+    settingsManager,
+  });
+  const resolvedPaths = await packageManager.resolve(async (source) => {
+    skippedPackages.push(source);
+    return "skip";
+  });
+
+  return {
+    files: resolvedPaths.skills
+      .filter((resource: ResolvedResource) => resource.enabled)
+      .map((resource: ResolvedResource) => resource.path),
+    skippedPackages,
+  };
+}
+
+async function collectSkills(options: ResolveSkillsOptions): Promise<CollectedSkills> {
+  const cwd = options.cwd;
+  const globalDir = options.globalDir ?? defaultGlobalSkillsDir();
+  const fileSystem = options.fs ?? defaultSkillFs;
+  const byName = new Map<string, ResolvedSkill>();
+  const warnings: string[] = [];
+
+  for (const dir of [
+    path.join(cwd, ".agents", "skills"),
+    path.join(cwd, ".pi", "skills"),
+    globalDir,
+    path.join(os.homedir(), ".agents", "skills"),
+  ]) {
+    for (const filePath of listSkillFilesInDir(dir, fileSystem)) {
+      addSkillFile(filePath, fileSystem, byName, warnings);
+    }
+  }
+
+  const packageSkills = await resolvePackageSkillFiles(options);
+  for (const filePath of packageSkills.files) {
+    addSkillFile(filePath, fileSystem, byName, warnings);
+  }
+
+  return { byName, warnings, skippedPackages: packageSkills.skippedPackages };
+}
+
+function skillsCacheKey(options: ResolveSkillsOptions): string | undefined {
+  if (options.fs) return undefined;
+  return JSON.stringify({
+    cwd: options.cwd,
+    agentDir: options.agentDir,
+    globalDir: options.globalDir ?? defaultGlobalSkillsDir(),
+    packageSkillFiles: options.packageSkillFiles,
+  });
+}
+
+async function getCollectedSkills(options: ResolveSkillsOptions): Promise<CollectedSkills> {
+  const cacheKey = skillsCacheKey(options);
+  if (!cacheKey) return collectSkills(options);
+
+  let cached = collectedSkillsCache.get(cacheKey);
+  if (!cached) {
+    cached = collectSkills(options);
+    collectedSkillsCache.set(cacheKey, cached);
+  }
+  return cached;
+}
+
+// ─── Wildcard Matching ───────────────────────────────────────────────────────
+
+function wildcardToRegex(pattern: string): RegExp {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+  return new RegExp(`^${escaped}$`);
+}
+
+function hasWildcard(pattern: string): boolean {
+  return pattern.includes("*");
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Resolve an agent's skill list into concrete skill definitions.
+ *
+ * Supports exact names and wildcards (e.g. "lark-*", "github").
+ */
+export async function resolveSkills(
+  skillNames: string[],
+  options: ResolveSkillsOptions,
+): Promise<ResolveSkillsResult> {
+  const requestedNames = skillNames.map((name) => name.trim()).filter(Boolean);
+  if (requestedNames.length === 0) {
+    return { resolved: [], missing: [], skippedPackages: [], warnings: [] };
+  }
+
+  const collected = await getCollectedSkills(options);
+  const resolved: ResolvedSkill[] = [];
+  const missing: string[] = [];
+  const seen = new Set<string>();
+
+  function addSkill(skill: ResolvedSkill): void {
+    if (seen.has(skill.name)) return;
+    seen.add(skill.name);
+    resolved.push(skill);
+  }
+
+  for (const requestedName of requestedNames) {
+    if (hasWildcard(requestedName)) {
+      const regex = wildcardToRegex(requestedName);
+      let matched = false;
+      for (const skill of collected.byName.values()) {
+        if (!regex.test(skill.name)) continue;
+        matched = true;
+        addSkill(skill);
+      }
+      if (!matched) missing.push(requestedName);
+      continue;
+    }
+
+    const skill = collected.byName.get(requestedName);
+    if (skill) addSkill(skill);
+    else missing.push(requestedName);
+  }
+
+  return {
+    resolved,
+    missing,
+    skippedPackages: collected.skippedPackages,
+    warnings: collected.warnings,
+  };
+}