pi-subagents-lite 0.2.0

package/src/result-viewer.ts

@@ -0,0 +1,218 @@
+/**
+ * result-viewer.ts — TUI scrollable markdown viewer for agent results.
+ *
+ * Used by the /agents > running agents menu to display agent results
+ * in a bordered, scrollable panel with keyboard navigation.
+ * Renders markdown so headings, code blocks, lists, etc. are styled.
+ */
+
+import {
+  Container,
+  type Component,
+  getKeybindings,
+  Markdown,
+  Spacer,
+  Text,
+  type MarkdownTheme,
+} from "@earendil-works/pi-tui";
+import { DynamicBorder } from "@earendil-works/pi-coding-agent";
+
+// Theme type from ctx.ui.custom() callback
+type Theme = any;
+
+/* ------------------------------------------------------------------ */
+/*  Types                                                              */
+/* ------------------------------------------------------------------ */
+
+export interface ResultViewerCallbacks {
+  onClose: () => void;
+}
+
+/* ------------------------------------------------------------------ */
+/*  ResultViewer                                                       */
+/* ------------------------------------------------------------------ */
+
+const PAGE_SIZE = 14;
+
+/**
+ * Build a MarkdownTheme from the TUI theme instance.
+ */
+function buildMarkdownTheme(theme: Theme): MarkdownTheme {
+  return {
+    heading: (text: string) => theme.fg("accent", theme.bold(text)),
+    link: (text: string) => theme.fg("accent", text),
+    linkUrl: (text: string) => theme.fg("muted", text),
+    code: (text: string) => theme.fg("accent", text),
+    codeBlock: (text: string) => text,
+    codeBlockBorder: (text: string) => theme.fg("muted", text),
+    quote: (text: string) => theme.fg("muted", text),
+    quoteBorder: (text: string) => theme.fg("muted", text),
+    hr: (text: string) => theme.fg("muted", text),
+    listBullet: (text: string) => theme.fg("accent", text),
+    bold: (text: string) => theme.bold(text),
+    italic: (text: string) => (theme.italic ? theme.italic(text) : text),
+    strikethrough: (text: string) => text,
+    underline: (text: string) => text,
+  };
+}
+
+/**
+ * A scrollable markdown viewer with bordered frame.
+ *
+ * Rendering:
+ *   - Top border
+ *   - Title bar with agent info
+ *   - Separator
+ *   - Paginated markdown content
+ *   - Scroll position indicator (when scrollable)
+ *   - Key hints footer
+ *   - Bottom border
+ *
+ * Key bindings: up/down/pageup/pagedown/g/G/escape
+ */
+export class ResultViewer extends Container implements Component {
+  private markdown: Markdown;
+  private renderedLines: string[];
+  private viewport: Container;
+  private scrollOffset: number;
+  private theme: Theme;
+  private callbacks: ResultViewerCallbacks;
+
+  constructor(
+    title: string,
+    text: string,
+    callbacks: ResultViewerCallbacks,
+    theme: Theme,
+  ) {
+    super();
+
+    this.callbacks = callbacks;
+    this.theme = theme;
+    this.scrollOffset = 0;
+
+    // Build markdown renderer (pre-render to get total lines)
+    const mdTheme = buildMarkdownTheme(theme);
+    this.markdown = new Markdown(text, 0, 0, mdTheme);
+    // Pre-render at a reasonable width to get line count
+    this.renderedLines = this.markdown.render(78);
+
+    // Build UI
+    this.addChild(new DynamicBorder());
+    this.addChild(new Spacer(1));
+
+    // Title bar
+    this.addChild(
+      new Text(this.theme.fg("accent", theme.bold(` ${title}`)), 0, 0),
+    );
+    this.addChild(new Spacer(1));
+
+    // Separator
+    this.addChild(
+      new Text(this.theme.fg("muted", "─".repeat(78)), 0, 0),
+    );
+    this.addChild(new Spacer(1));
+
+    // Scrollable viewport
+    this.viewport = new Container();
+    this.addChild(this.viewport);
+
+    // Bottom spacer + key hints + border
+    this.addChild(new Spacer(1));
+    const hints = this.theme.fg(
+      "muted",
+      "  ↑↓ navigate · PgUp/PgDn · g/G top/bottom · Esc close",
+    );
+    this.addChild(new Text(hints, 0, 0));
+    this.addChild(new Spacer(1));
+    this.addChild(new DynamicBorder());
+
+    this.updateViewport();
+  }
+
+  handleInput(keyData: string): void {
+    const kb = getKeybindings();
+
+    // Up
+    if (kb.matches(keyData, "tui.select.up")) {
+      if (this.scrollOffset > 0) {
+        this.scrollOffset--;
+        this.updateViewport();
+      }
+      return;
+    }
+
+    // Down
+    if (kb.matches(keyData, "tui.select.down")) {
+      if (this.scrollOffset < this.renderedLines.length - 1) {
+        this.scrollOffset++;
+        this.updateViewport();
+      }
+      return;
+    }
+
+    // PageUp
+    if (kb.matches(keyData, "tui.select.pageUp")) {
+      this.scrollOffset = Math.max(0, this.scrollOffset - PAGE_SIZE);
+      this.updateViewport();
+      return;
+    }
+
+    // PageDown
+    if (kb.matches(keyData, "tui.select.pageDown")) {
+      this.scrollOffset = Math.min(
+        this.renderedLines.length - 1,
+        this.scrollOffset + PAGE_SIZE,
+      );
+      this.updateViewport();
+      return;
+    }
+
+    // 'g' — jump to top
+    if (keyData === "g") {
+      this.scrollOffset = 0;
+      this.updateViewport();
+      return;
+    }
+
+    // 'G' — jump to bottom
+    if (keyData === "G") {
+      this.scrollOffset = this.renderedLines.length - 1;
+      this.updateViewport();
+      return;
+    }
+
+    // Escape / Ctrl+C — close
+    if (kb.matches(keyData, "tui.select.cancel")) {
+      this.callbacks.onClose();
+      return;
+    }
+  }
+
+  invalidate(): void {}
+
+  private updateViewport(): void {
+    this.viewport.clear();
+
+    const visibleLines = Math.min(
+      PAGE_SIZE,
+      this.renderedLines.length - this.scrollOffset,
+    );
+    for (let i = 0; i < visibleLines; i++) {
+      const lineIdx = this.scrollOffset + i;
+      const line = this.renderedLines[lineIdx] ?? "";
+      this.viewport.addChild(new Text(line, 0, 0));
+    }
+
+    // Scroll position indicator
+    if (this.renderedLines.length > PAGE_SIZE) {
+      const pct = Math.round(
+        (this.scrollOffset / this.renderedLines.length) * 100,
+      );
+      const indicator = this.theme.fg(
+        "muted",
+        `  (${this.scrollOffset + 1}/${this.renderedLines.length} · ${pct}%)`,
+      );
+      this.viewport.addChild(new Text(indicator, 0, 0));
+    }
+  }
+}

package/src/skill-loader.ts

@@ -0,0 +1,104 @@
+/**
+ * skill-loader.ts — Preload named skills.
+ *
+ * Roots, in precedence order:
+ *   - <cwd>/.pi/skills           (project, Pi's standard)
+ *   - <cwd>/.agents/skills       (project, cross-tool Agent Skills spec — https://agentskills.io)
+ *   - getAgentDir()/skills       (user, default ~/.pi/agent/skills — Pi's standard)
+ *   - ~/.agents/skills           (user, cross-tool Agent Skills spec)
+ *   - ~/.pi/skills               (legacy global, pre-Pi)
+ *
+ * Layout per root:
+ *   - <root>/<name>.md            (flat file at the top level)
+ *   - <root>/.../<name>/SKILL.md  (directory skill, may be nested — Pi's standard)
+ *
+ * Recursion skips dotfile entries and node_modules. A directory that itself contains
+ * SKILL.md is a skill — we don't descend into it (Pi: skills don't nest).
+ *
+ * Symlinks are rejected for security (deviation from Pi, which follows them).
+ *
+ * Changed from upstream: imports from ./utils.js instead of ./memory.js.
+ */
+
+import type { Dirent } from "node:fs";
+import { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { isSymlink, isUnsafeName, safeReadFile } from "./utils.js";
+
+export interface PreloadedSkill {
+  name: string;
+  content: string;
+}
+
+export function preloadSkills(skillNames: string[], cwd: string): PreloadedSkill[] {
+  return skillNames.map((name) => ({ name, content: loadSkillContent(name, cwd) }));
+}
+
+function loadSkillContent(name: string, cwd: string): string {
+  if (isUnsafeName(name)) {
+    return `(Skill "${name}" skipped: name contains path traversal characters)`;
+  }
+  const roots = [
+    join(cwd, ".pi", "skills"), // project — Pi standard
+    join(cwd, ".agents", "skills"), // project — Agent Skills spec
+    join(getAgentDir(), "skills"), // user — Pi standard
+    join(homedir(), ".agents", "skills"), // user — Agent Skills spec
+    join(homedir(), ".pi", "skills"), // legacy global, pre-Pi
+  ];
+  for (const root of roots) {
+    const content = findInRoot(root, name);
+    if (content !== undefined) return content;
+  }
+  return `(Skill "${name}" not found in .pi/skills/, .agents/skills/, or global skill locations)`;
+}
+
+function findInRoot(root: string, name: string): string | undefined {
+  if (isSymlink(root)) return undefined; // reject symlinked roots entirely
+  const flat = safeReadFile(join(root, `${name}.md`))?.trim();
+  if (flat !== undefined) return flat;
+  return findSkillDirectory(root, name);
+}
+
+/** BFS under `root` for a directory named `name` containing `SKILL.md`. Pi-conforming filters. */
+function findSkillDirectory(root: string, name: string): string | undefined {
+  if (!existsSync(root)) return undefined;
+  const queue: string[] = [root];
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (current === undefined) continue;
+
+    let entries: Dirent[];
+    try {
+      entries = readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    // Deterministic byte-order traversal — locale-independent.
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+
+      // Symlinked dirs already filtered by entry.isDirectory() — Dirent uses lstat semantics.
+      const path = join(current, entry.name);
+      const skillMd = join(path, "SKILL.md");
+      const isSkillDir = existsSync(skillMd);
+
+      if (isSkillDir) {
+        if (entry.name === name) {
+          const content = safeReadFile(skillMd)?.trim();
+          if (content !== undefined) return content;
+        }
+        continue; // Pi rule: skills don't nest — don't descend into a skill dir
+      }
+
+      queue.push(path);
+    }
+  }
+  return undefined;
+}

package/src/types.ts

@@ -0,0 +1,96 @@
+/**
+ * types.ts — Type definitions for the subagent system.
+ *
+ * Trimmed from upstream: removed ScheduledSubagent, ScheduleStoreData,
+ * IsolationMode, MemoryScope, JoinMode.
+ * From AgentConfig: removed memory, isolation, inheritContext, runInBackground.
+ * From AgentRecord: removed groupId, joinMode, worktree, worktreeResult.
+ * From AgentInvocation: removed inheritContext, isolation.
+ */
+
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import type { LifetimeUsage } from "./usage.js";
+
+/** Thinking level for agent models. */
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+
+/** Agent type: any string name (built-in defaults or user-defined). */
+export type SubagentType = string;
+
+/** Unified agent configuration — used for both default and user-defined agents. */
+export interface AgentConfig {
+  name: string;
+  displayName?: string;
+  description: string;
+  builtinToolNames?: string[];
+  /** Tool denylist — these tools are removed even if `builtinToolNames` or extensions include them. */
+  disallowedTools?: string[];
+  /** true = inherit all, string[] = only listed, false = none */
+  extensions: true | string[] | false;
+  /** true = inherit all, string[] = only listed, false = none */
+  skills: true | string[] | false;
+  model?: string;
+  thinking?: ThinkingLevel;
+  maxTurns?: number;
+  systemPrompt: string;
+  /** Default for spawn: no extension tools. undefined = caller decides. */
+  isolated?: boolean;
+  /** true = this is an embedded default agent (informational) */
+  isDefault?: boolean;
+  /** false = agent is hidden from the registry */
+  enabled?: boolean;
+  /** Where this agent was loaded from */
+  source?: "default" | "project" | "global";
+}
+
+export interface AgentRecord {
+  id: string;
+  type: SubagentType;
+  description: string;
+  status: "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error";
+  result?: string;
+  error?: string;
+  toolUses: number;
+  startedAt: number;
+  completedAt?: number;
+  session?: AgentSession;
+  abortController?: AbortController;
+  promise?: Promise<string>;
+  /** Steering messages queued before the session was ready. */
+  pendingSteers?: string[];
+  /** The tool_use_id from the original Agent tool call. */
+  toolCallId?: string;
+  /** Path to the streaming output transcript file. */
+  outputFile?: string;
+  /** Cleanup function for the output file stream subscription. */
+  outputCleanup?: () => void;
+  /**
+   * Lifetime usage breakdown, accumulated via `message_end` events. Survives
+   * compaction. Total = input + output + cacheWrite (cacheRead deliberately
+   * excluded — see issue #38). Initialized to zeros at spawn.
+   */
+  lifetimeUsage: LifetimeUsage;
+  /** Final turn count (set on completion). Used by widget after activity cleanup. */
+  turnCount?: number;
+  /** Max turns limit (from invocation or default). */
+  maxTurns?: number;
+  /** Number of times this agent's session has compacted. Initialized to 0 at spawn. */
+  compactionCount: number;
+  /** Resolved spawn params, captured for UI display. Fixed at spawn time. */
+  invocation?: AgentInvocation;
+}
+
+export interface AgentInvocation {
+  /** Short display name, e.g. "haiku" — only set when different from parent. */
+  modelName?: string;
+  thinking?: ThinkingLevel;
+  maxTurns?: number;
+  isolated?: boolean;
+  runInBackground?: boolean;
+}
+
+export interface EnvInfo {
+  isGitRepo: boolean;
+  branch: string | null;
+  platform: string;
+}