@mystilleef/pi-subagent 0.5.0 → 0.7.0

package/README.md

@@ -151,7 +151,7 @@ executable automation.
 **Environment variables:**
 
 - `PI_SUBAGENT_DEPTH`: nested subagent depth guard. Nested calls stop at
-  depth `1`.
+  depth `2`.
 - `PI_SUBAGENT_MAX_OUTPUT_BYTES`: max returned output bytes. Default:
   `50000`.
 - `PI_SUBAGENT_MAX_OUTPUT_LINES`: max returned output lines. Default:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mystilleef/pi-subagent",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Pi subagent for the SPAE Framework",
   "author": "Lateef Alabi-Oki <mystilleef@gmail.com>",
   "license": "MIT",
@@ -47,12 +47,14 @@
     "access": "public"
   },
   "scripts": {
-    "verify": "bun fix && bun check && bun test",
-    "coverage": "bun fix && bun check && bun test --coverage",
-    "check": "biome check . && tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check --error-on-warnings .",
     "fix": "biome check --write --unsafe .",
-    "pack:smoke": "bun scripts/pack-smoke.ts",
     "migrate": "biome migrate --write",
+    "coverage": "bun test --coverage",
+    "check": "bun lint && bun typecheck",
+    "verify": "bun migrate && bun fix && bun typecheck && bun coverage",
+    "pack:smoke": "bun scripts/pack-smoke.ts",
     "release": "sh -c 'npm version \"$1\" -m \"chore(release): %s\" && git push --follow-tags' --"
   },
   "peerDependencies": {
@@ -63,14 +65,14 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.15",
-    "@earendil-works/pi-agent-core": "^0.75.4",
-    "@earendil-works/pi-ai": "^0.75.4",
-    "@earendil-works/pi-coding-agent": "^0.75.4",
-    "@earendil-works/pi-tui": "^0.75.4",
+    "@biomejs/biome": "^2.4.16",
+    "@earendil-works/pi-agent-core": "^0.78.0",
+    "@earendil-works/pi-ai": "^0.78.0",
+    "@earendil-works/pi-coding-agent": "^0.78.0",
+    "@earendil-works/pi-tui": "^0.78.0",
     "@types/bun": "^1.3.14",
     "@types/node": "^25.9.1",
-    "typebox": "^1.1.38",
+    "typebox": "^1.1.39",
     "typescript": "^6.0.3"
   }
 }

package/src/agent/agent-cache.ts

@@ -0,0 +1,258 @@
+import { createHash } from "node:crypto";
+import * as fsPromises from "node:fs/promises";
+import path from "node:path";
+import {
+  type AgentDiscoveryResult,
+  type AgentDiscoveryScopeResult,
+  type AgentScope,
+  type AgentSource,
+  discoverAgentsAsync,
+  emptyScopeResult,
+  getUserAgentsDir,
+  readMarkdownDirEntriesAsync,
+} from "./agents.js";
+
+interface AgentDiscoveryScopeSnapshot {
+  markdownFiles: string[];
+  fileHashes: Record<string, string | null>;
+}
+
+type AgentDiscoverySnapshots = Record<AgentSource, AgentDiscoveryScopeSnapshot>;
+
+export type AgentDiscoveryCacheEntry = AgentDiscoveryResult & {
+  ts: number;
+  snapshots?: AgentDiscoverySnapshots;
+};
+export type AgentDiscoveryCache = Map<string, AgentDiscoveryCacheEntry>;
+export const AGENT_DISCOVERY_CACHE_TTL_MS = 300_000;
+const sharedAgentDiscoveryCache: AgentDiscoveryCache = new Map();
+const AGENT_SOURCES = ["user", "project"] as const;
+
+interface CacheOperationContext {
+  cwd: string;
+  cache: AgentDiscoveryCache;
+  ts: number;
+  cacheTtlMs: number;
+}
+
+export function resetAgentDiscoveryCache(): void {
+  sharedAgentDiscoveryCache.clear();
+}
+
+function cacheKey(cwd: string, scope: AgentScope): string {
+  return `${path.resolve(cwd)}\0${scope}`;
+}
+
+function getFreshCacheEntry(
+  ctx: CacheOperationContext,
+  key: string,
+): AgentDiscoveryCacheEntry | undefined {
+  const entry = ctx.cache.get(key);
+  return entry && ctx.ts - entry.ts <= ctx.cacheTtlMs ? entry : undefined;
+}
+
+function emptySnapshot(): AgentDiscoveryScopeSnapshot {
+  return { markdownFiles: [], fileHashes: {} };
+}
+
+function cloneScopeSnapshot(
+  snapshot: AgentDiscoveryScopeSnapshot | undefined,
+): AgentDiscoveryScopeSnapshot {
+  if (!snapshot) return emptySnapshot();
+  return {
+    markdownFiles: [...snapshot.markdownFiles],
+    fileHashes: { ...snapshot.fileHashes },
+  };
+}
+
+function equalStringSets(a: string[], b: string[]): boolean {
+  if (a.length !== b.length) return false;
+  const set = new Set(a);
+  return b.every((value) => set.has(value));
+}
+
+function snapshotsEqual(
+  left: AgentDiscoveryScopeSnapshot,
+  right: AgentDiscoveryScopeSnapshot,
+): boolean {
+  if (!equalStringSets(left.markdownFiles, right.markdownFiles)) return false;
+  return left.markdownFiles.every(
+    (fileName) => left.fileHashes[fileName] === right.fileHashes[fileName],
+  );
+}
+
+function scopeAgentsMatchListing(
+  scopeResult: AgentDiscoveryScopeResult,
+  source: AgentSource,
+  dir: string | null,
+): boolean {
+  if (!dir)
+    return (
+      scopeResult.agents.length === 0 && scopeResult.markdownFiles.length === 0
+    );
+  const listedFiles = new Set(scopeResult.markdownFiles);
+  const resolvedDir = path.resolve(dir);
+  return scopeResult.agents.every((agent) => {
+    const fileName = path.basename(agent.filePath);
+    return (
+      agent.source === source &&
+      listedFiles.has(fileName) &&
+      path.resolve(path.dirname(agent.filePath)) === resolvedDir
+    );
+  });
+}
+
+async function hashMarkdownFileAsync(
+  dir: string,
+  fileName: string,
+): Promise<string | null> {
+  try {
+    return createHash("sha256")
+      .update(await fsPromises.readFile(path.join(dir, fileName)))
+      .digest("hex");
+  } catch {
+    return null;
+  }
+}
+
+async function buildScopeSnapshotAsync(
+  dir: string | null,
+): Promise<AgentDiscoveryScopeSnapshot> {
+  if (!dir) return emptySnapshot();
+  const entries = await readMarkdownDirEntriesAsync(dir);
+  const markdownFiles = entries.map((entry) => entry.name);
+  const hashPairs = await Promise.all(
+    markdownFiles.map(
+      async (fileName) =>
+        [fileName, await hashMarkdownFileAsync(dir, fileName)] as const,
+    ),
+  );
+  return { markdownFiles, fileHashes: Object.fromEntries(hashPairs) };
+}
+
+async function buildCacheSnapshotsAsync(
+  discovery: AgentDiscoveryResult,
+): Promise<AgentDiscoverySnapshots> {
+  const [user, project] = await Promise.all([
+    buildScopeSnapshotAsync(getUserAgentsDir()),
+    buildScopeSnapshotAsync(discovery.projectAgentsDir),
+  ]);
+  return { user, project };
+}
+
+async function canTrustDerivedScopeAsync(
+  source: AgentSource,
+  bothEntry: AgentDiscoveryCacheEntry,
+): Promise<boolean> {
+  const dir =
+    source === "user" ? getUserAgentsDir() : bothEntry.projectAgentsDir;
+  const scopeResult = bothEntry.scopes[source];
+  const cachedSnapshot = bothEntry.snapshots?.[source];
+  if (!cachedSnapshot) return false;
+  if (!scopeAgentsMatchListing(scopeResult, source, dir)) return false;
+  if (!equalStringSets(scopeResult.markdownFiles, cachedSnapshot.markdownFiles))
+    return false;
+  return snapshotsEqual(cachedSnapshot, await buildScopeSnapshotAsync(dir));
+}
+
+function buildSourceRecord<T>(
+  source: AgentSource,
+  value: T,
+  empty: () => T,
+): Record<AgentSource, T> {
+  const record: Record<AgentSource, T> = { user: empty(), project: empty() };
+  record[source] = value;
+  return record;
+}
+function createDerivedCacheEntry(
+  bothEntry: AgentDiscoveryCacheEntry,
+  source: AgentSource,
+): AgentDiscoveryCacheEntry {
+  const { agents, markdownFiles } = bothEntry.scopes[source];
+  const clonedScope: AgentDiscoveryScopeResult = {
+    agents: [...agents],
+    markdownFiles: [...markdownFiles],
+  };
+  return {
+    agents: clonedScope.agents,
+    projectAgentsDir: bothEntry.projectAgentsDir,
+    scopes: buildSourceRecord(source, clonedScope, emptyScopeResult),
+    ts: bothEntry.ts,
+    snapshots: buildSourceRecord(
+      source,
+      cloneScopeSnapshot(bothEntry.snapshots?.[source]),
+      emptySnapshot,
+    ),
+  };
+}
+
+async function discoverAndCacheAsync(
+  ctx: CacheOperationContext,
+  scope: AgentScope,
+): Promise<AgentDiscoveryCacheEntry> {
+  const discovery = await discoverAgentsAsync(ctx.cwd, scope);
+  const entry: AgentDiscoveryCacheEntry = {
+    ...discovery,
+    ts: ctx.ts,
+    snapshots: await buildCacheSnapshotsAsync(discovery),
+  };
+  ctx.cache.set(cacheKey(ctx.cwd, scope), entry);
+  if (scope === "both") {
+    await primeScopedCacheEntriesAsync(ctx, entry);
+  }
+  return entry;
+}
+
+async function deriveOrDiscoverScopedEntryAsync(
+  ctx: CacheOperationContext,
+  source: AgentSource,
+  bothEntry: AgentDiscoveryCacheEntry,
+): Promise<AgentDiscoveryCacheEntry> {
+  if (await canTrustDerivedScopeAsync(source, bothEntry)) {
+    const entry = createDerivedCacheEntry(bothEntry, source);
+    ctx.cache.set(cacheKey(ctx.cwd, source), entry);
+    return entry;
+  }
+  return discoverAndCacheAsync(ctx, source);
+}
+
+async function primeScopedCacheEntriesAsync(
+  ctx: CacheOperationContext,
+  bothEntry: AgentDiscoveryCacheEntry,
+): Promise<void> {
+  for (const source of AGENT_SOURCES) {
+    const scopedKey = cacheKey(ctx.cwd, source);
+    if (getFreshCacheEntry(ctx, scopedKey)) continue;
+    await deriveOrDiscoverScopedEntryAsync(ctx, source, bothEntry);
+  }
+}
+
+export async function getCachedAgentDiscovery(
+  cwd: string,
+  scope: AgentScope,
+  cache: AgentDiscoveryCache = sharedAgentDiscoveryCache,
+  cacheTtlMs = AGENT_DISCOVERY_CACHE_TTL_MS,
+): Promise<AgentDiscoveryCacheEntry> {
+  const ctx: CacheOperationContext = { cwd, cache, ts: Date.now(), cacheTtlMs };
+  const key = cacheKey(cwd, scope);
+  const entry = getFreshCacheEntry(ctx, key);
+  if (entry) return entry;
+  if (scope !== "both") {
+    const bothEntry = getFreshCacheEntry(ctx, cacheKey(cwd, "both"));
+    if (bothEntry) {
+      return deriveOrDiscoverScopedEntryAsync(ctx, scope, bothEntry);
+    }
+  }
+  return discoverAndCacheAsync(ctx, scope);
+}
+
+export async function getCachedAgentCompletions(
+  prefix: string,
+  cwd = process.cwd(),
+  cache: AgentDiscoveryCache = sharedAgentDiscoveryCache,
+  cacheTtlMs = AGENT_DISCOVERY_CACHE_TTL_MS,
+): Promise<{ value: string; label: string }[]> {
+  return (await getCachedAgentDiscovery(cwd, "both", cache, cacheTtlMs)).agents
+    .filter((agent) => agent.name.startsWith(prefix))
+    .map((agent) => ({ value: agent.name, label: agent.name }));
+}

package/src/agent/agents.ts

@@ -0,0 +1,232 @@
+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";
+
+export type AgentSource = "user" | "project";
+export type AgentScope = AgentSource | "both";
+
+const THINKING_LEVELS = [
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+] as const;
+
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+
+export interface AgentConfig {
+  name: string;
+  description: string;
+  tools?: string[];
+  skills?: string[];
+  thinking?: ThinkingLevel;
+  systemPrompt: string;
+  source: AgentSource;
+  filePath: string;
+}
+
+export interface AgentDiscoveryScopeResult {
+  agents: AgentConfig[];
+  markdownFiles: string[];
+}
+
+export interface AgentDiscoveryResult {
+  agents: AgentConfig[];
+  projectAgentsDir: string | null;
+  scopes: Record<AgentSource, AgentDiscoveryScopeResult>;
+}
+
+function mergeAgentLists(
+  userResult: AgentDiscoveryScopeResult,
+  projectResult: AgentDiscoveryScopeResult,
+  projectAgentsDir: string | null,
+): AgentDiscoveryResult {
+  const agentMap = new Map<string, AgentConfig>();
+  for (const agent of userResult.agents) agentMap.set(agent.name, agent);
+  for (const agent of projectResult.agents) agentMap.set(agent.name, agent);
+  return {
+    agents: Array.from(agentMap.values()),
+    projectAgentsDir,
+    scopes: {
+      user: userResult,
+      project: projectResult,
+    },
+  };
+}
+
+function parseCommaList(raw: unknown): string[] | undefined {
+  if (typeof raw !== "string") return undefined;
+  const items = raw
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  return items.length > 0 ? items : undefined;
+}
+
+function parseThinkingLevel(raw: unknown): ThinkingLevel | undefined {
+  if (typeof raw !== "string") return undefined;
+  const normalized = raw.trim().toLowerCase();
+  return (THINKING_LEVELS as readonly string[]).includes(normalized)
+    ? (normalized as ThinkingLevel)
+    : undefined;
+}
+
+function parseAgentConfig(
+  content: string,
+  source: AgentSource,
+  filePath: string,
+): AgentConfig | null {
+  let parsed: ReturnType<typeof parseFrontmatter<Record<string, unknown>>>;
+  try {
+    parsed = parseFrontmatter<Record<string, unknown>>(content);
+  } catch {
+    return null;
+  }
+  const { frontmatter, body } = parsed;
+  if (
+    typeof frontmatter !== "object" ||
+    frontmatter === null ||
+    Array.isArray(frontmatter)
+  )
+    return null;
+  const {
+    name,
+    description,
+    tools: rawTools,
+    skills: rawSkills,
+    thinking: rawThinking,
+  } = 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;
+  const tools = parseCommaList(rawTools);
+  const skills = Object.hasOwn(frontmatter, "skills")
+    ? (parseCommaList(rawSkills) ?? [])
+    : undefined;
+  const thinking = parseThinkingLevel(rawThinking);
+  return {
+    name,
+    description,
+    tools,
+    skills,
+    thinking,
+    systemPrompt: body,
+    source,
+    filePath,
+  };
+}
+
+async function loadAgentEntryAsync(
+  dir: string,
+  entryName: string,
+  source: AgentSource,
+): Promise<AgentConfig | null> {
+  const filePath = path.join(dir, entryName);
+  let content: string;
+  try {
+    content = await fsPromises.readFile(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+  return parseAgentConfig(content, source, filePath);
+}
+
+export function emptyScopeResult(): AgentDiscoveryScopeResult {
+  return { agents: [], markdownFiles: [] };
+}
+
+async function loadAgentsFromDirAsync(
+  dir: string,
+  source: AgentSource,
+): Promise<AgentDiscoveryScopeResult> {
+  const markdownEntries = await readMarkdownDirEntriesAsync(dir);
+  const markdownFiles = markdownEntries.map((entry) => entry.name);
+  const parsedAgents = await Promise.all(
+    markdownEntries.map((entry) =>
+      loadAgentEntryAsync(dir, entry.name, source),
+    ),
+  );
+  const agents = parsedAgents.filter(
+    (agent): agent is AgentConfig => agent !== null,
+  );
+  return { agents, markdownFiles };
+}
+
+export function isMarkdownDirent(entry: Dirent): boolean {
+  return (
+    entry.name.endsWith(".md") && (entry.isFile() || entry.isSymbolicLink())
+  );
+}
+
+export async function readMarkdownDirEntriesAsync(
+  dir: string | null,
+): Promise<Dirent[]> {
+  if (!dir) return [];
+  try {
+    const entries = await fsPromises.readdir(dir, { withFileTypes: true });
+    return entries.filter(isMarkdownDirent);
+  } catch {
+    return [];
+  }
+}
+
+export function getUserAgentsDir(): string {
+  return path.join(getAgentDir(), "agents");
+}
+
+export async function isDirectoryAsync(p: string): Promise<boolean> {
+  try {
+    return (await fsPromises.stat(p)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function findNearestProjectAgentsDirAsync(
+  cwd: string,
+): Promise<string | null> {
+  let currentDir = cwd;
+  while (true) {
+    const candidate = path.join(currentDir, ".pi", "agents");
+    if (await isDirectoryAsync(candidate)) return candidate;
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir) return null;
+    currentDir = parentDir;
+  }
+}
+
+export async function discoverAgentsAsync(
+  cwd: string,
+  scope: AgentScope,
+): Promise<AgentDiscoveryResult> {
+  const userDir = getUserAgentsDir();
+  const projectAgentsDir = await findNearestProjectAgentsDirAsync(cwd);
+  const [userDiscovery, projectDiscovery] = await Promise.all([
+    scope === "project"
+      ? emptyScopeResult()
+      : loadAgentsFromDirAsync(userDir, "user"),
+    scope === "user" || !projectAgentsDir
+      ? emptyScopeResult()
+      : loadAgentsFromDirAsync(projectAgentsDir, "project"),
+  ]);
+  return mergeAgentLists(userDiscovery, projectDiscovery, projectAgentsDir);
+}
+
+export function formatAgentList(
+  agents: AgentConfig[],
+  maxItems: number,
+): { text: string; remaining: number } {
+  if (agents.length === 0) return { text: "none", remaining: 0 };
+  const listed = agents.slice(0, maxItems);
+  const remaining = agents.length - listed.length;
+  return {
+    text: listed
+      .map((a) => `${a.name} (${a.source}): ${a.description}`)
+      .join("; "),
+    remaining,
+  };
+}

package/src/child/child-events.ts

@@ -0,0 +1,119 @@
+import { makeToolPreview } from "../output/normalize.js";
+import type { ToolActivity } from "../shared/types.js";
+
+// Extracts results[0] from details; null-safe for malformed input.
+function tryFirstResult(details: unknown): Record<string, unknown> | null {
+  try {
+    if (typeof details !== "object" || details === null) return null;
+    const results = (details as Record<string, unknown>).results;
+    if (!Array.isArray(results) || results.length === 0) return null;
+    const nested = results[0];
+    if (typeof nested !== "object" || nested === null) return null;
+    return nested as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+// Malformed details (null result) falls back to { toolName }.
+function parseToolActivity(
+  toolName: string,
+  partialResult: { content?: unknown; details?: unknown },
+): ToolActivity {
+  const nestedRecord = tryFirstResult(partialResult.details);
+  if (!nestedRecord) return { toolName, inputSummary: toolName };
+  const isSubagent = toolName === "subagent";
+  const activity: ToolActivity = { toolName };
+  const agent = typeof nestedRecord.agent === "string" && nestedRecord.agent;
+  activity.inputSummary =
+    isSubagent && agent ? makeToolPreview(toolName, nestedRecord) : toolName;
+  if (
+    typeof nestedRecord.instanceName === "string" &&
+    nestedRecord.instanceName
+  ) {
+    activity.instanceName = nestedRecord.instanceName;
+  }
+  const progress = nestedRecord.progress;
+  if (typeof progress === "object" && progress !== null) {
+    const activeToolActivity = (progress as Record<string, unknown>)
+      .activeToolActivity;
+    if (
+      typeof activeToolActivity === "object" &&
+      activeToolActivity !== null &&
+      typeof (activeToolActivity as Record<string, unknown>).toolName ===
+        "string"
+    ) {
+      const childActivity = activeToolActivity as ToolActivity;
+      activity.child = childActivity;
+      // Subagent delegates inputSummary to its own agent name, not child
+      if (
+        !isSubagent &&
+        typeof childActivity.inputSummary === "string" &&
+        childActivity.inputSummary
+      ) {
+        activity.inputSummary = childActivity.inputSummary;
+      }
+    }
+  }
+  return activity;
+}
+
+export type ChildKnownEvent =
+  | { type: "message_end"; message: unknown }
+  | { type: "tool_result_end"; message: unknown }
+  | { type: "agent_end"; messages?: unknown; stopReason?: string }
+  | {
+      type: "tool_execution_update";
+      toolName: string;
+      partialResult: { content?: unknown; details?: unknown };
+      toolActivity: ToolActivity;
+    };
+
+export type ChildEventParseResult =
+  | { kind: "known"; event: ChildKnownEvent }
+  | { kind: "unknown"; event: unknown }
+  | { kind: "invalid"; line: string };
+
+export const TOOL_EXECUTION_UPDATE_EVENT = "tool_execution_update" as const;
+
+const KNOWN_TYPES = new Set([
+  "message_end",
+  "tool_result_end",
+  "agent_end",
+  TOOL_EXECUTION_UPDATE_EVENT,
+]);
+
+export function parseChildEventLine(line: string): ChildEventParseResult {
+  if (typeof line !== "string" || !line.trim())
+    return { kind: "invalid", line };
+  let event: unknown;
+  try {
+    event = JSON.parse(line);
+  } catch {
+    return { kind: "invalid", line };
+  }
+  if (
+    typeof event === "object" &&
+    event !== null &&
+    "type" in event &&
+    typeof (event as Record<string, unknown>).type === "string" &&
+    KNOWN_TYPES.has((event as Record<string, unknown>).type as string)
+  ) {
+    const record = event as Record<string, unknown>;
+    if (record.type === TOOL_EXECUTION_UPDATE_EVENT) {
+      if (
+        typeof record.toolName !== "string" ||
+        typeof record.partialResult !== "object" ||
+        record.partialResult === null
+      ) {
+        return { kind: "unknown", event };
+      }
+      record.toolActivity = parseToolActivity(
+        record.toolName as string,
+        record.partialResult as { content?: unknown; details?: unknown },
+      );
+    }
+    return { kind: "known", event: event as ChildKnownEvent };
+  }
+  return { kind: "unknown", event };
+}