@mystilleef/pi-subagent 0.6.0 → 0.8.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 `3`.
 - `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.6.0",
+  "version": "0.8.0",
   "description": "Pi subagent for the SPAE Framework",
   "author": "Lateef Alabi-Oki <mystilleef@gmail.com>",
   "license": "MIT",
@@ -48,12 +48,11 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "lint": "biome check --error-on-warnings .",
-    "fix": "biome check --write --unsafe .",
+    "lint": "biome check --write --unsafe --error-on-warnings .",
     "migrate": "biome migrate --write",
     "coverage": "bun test --coverage",
     "check": "bun lint && bun typecheck",
-    "verify": "bun migrate && bun fix && bun typecheck && bun coverage",
+    "verify": "bun migrate && bun check && bun coverage",
     "pack:smoke": "bun scripts/pack-smoke.ts",
     "release": "sh -c 'npm version \"$1\" -m \"chore(release): %s\" && git push --follow-tags' --"
   },
@@ -66,13 +65,13 @@
   },
   "devDependencies": {
     "@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",
+    "@earendil-works/pi-agent-core": "^0.78.1",
+    "@earendil-works/pi-ai": "^0.78.1",
+    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@earendil-works/pi-tui": "^0.78.1",
     "@types/bun": "^1.3.14",
     "@types/node": "^25.9.1",
-    "typebox": "^1.1.39",
+    "typebox": "^1.2.1",
     "typescript": "^6.0.3"
   }
 }

package/src/agent/agent-cache.ts

@@ -1,32 +1,277 @@
+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,
+  readMarkdownDirWithStatusAsync,
 } from "./agents.js";
 
-export type AgentDiscoveryCacheEntry = AgentDiscoveryResult & { ts: number };
+interface AgentDiscoveryScopeSnapshot {
+  markdownFiles: string[];
+  fileHashes: Record<string, string | null>;
+  listingTrusted: boolean;
+  directory: 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: {},
+    listingTrusted: false,
+    directory: null,
+  };
+}
+
+function cloneScopeSnapshot(
+  snapshot: AgentDiscoveryScopeSnapshot | undefined,
+): AgentDiscoveryScopeSnapshot {
+  if (!snapshot) return emptySnapshot();
+  return {
+    markdownFiles: [...snapshot.markdownFiles],
+    fileHashes: { ...snapshot.fileHashes },
+    listingTrusted: snapshot.listingTrusted,
+    directory: snapshot.directory,
+  };
+}
+
+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 snapshotHasRequiredMetadata(
+  snapshot: AgentDiscoveryScopeSnapshot,
+): boolean {
+  if (typeof snapshot.listingTrusted !== "boolean") return false;
+  if (snapshot.directory !== null && typeof snapshot.directory !== "string")
+    return false;
+  if (
+    !equalStringSets(snapshot.markdownFiles, Object.keys(snapshot.fileHashes))
+  )
+    return false;
+  return true;
+}
+
+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> {
+  const listing = await readMarkdownDirWithStatusAsync(dir);
+  const markdownFiles = listing.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),
+    listingTrusted: listing.ok,
+    directory: dir ? path.resolve(dir) : null,
+  };
+}
+
+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 resolvedDir = dir ? path.resolve(dir) : null;
+  const scopeResult = bothEntry.scopes[source];
+  const cachedSnapshot = bothEntry.snapshots?.[source];
+  if (!cachedSnapshot) return false;
+  if (!snapshotHasRequiredMetadata(cachedSnapshot)) return false;
+  if (!cachedSnapshot.listingTrusted) return false;
+  if (cachedSnapshot.directory !== resolvedDir) return false;
+  if (!scopeAgentsMatchListing(scopeResult, source, dir)) return false;
+  if (!equalStringSets(scopeResult.markdownFiles, cachedSnapshot.markdownFiles))
+    return false;
+  const listing = await readMarkdownDirWithStatusAsync(dir);
+  if (!listing.ok) return false;
+  return equalStringSets(
+    cachedSnapshot.markdownFiles,
+    listing.entries.map((entry) => entry.name),
+  );
+}
+
+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> {
+  const missingSources = AGENT_SOURCES.filter(
+    (source) => !getFreshCacheEntry(ctx, cacheKey(ctx.cwd, source)),
+  );
+  await Promise.all(
+    missingSources.map((source) =>
+      deriveOrDiscoverScopedEntryAsync(ctx, source, bothEntry),
+    ),
+  );
+}
+
 export async function getCachedAgentDiscovery(
   cwd: string,
   scope: AgentScope,
   cache: AgentDiscoveryCache = sharedAgentDiscoveryCache,
   cacheTtlMs = AGENT_DISCOVERY_CACHE_TTL_MS,
 ): Promise<AgentDiscoveryCacheEntry> {
-  const key = `${path.resolve(cwd)}\0${scope}`;
-  const now = Date.now();
-  const entry = cache.get(key);
-  if (entry && now - entry.ts <= cacheTtlMs) return entry;
-  const nextEntry = { ...(await discoverAgentsAsync(cwd, scope)), ts: now };
-  cache.set(key, nextEntry);
-  return nextEntry;
+  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(

package/src/agent/agents.ts

@@ -1,21 +1,10 @@
-/**
- * Agent discovery and configuration
- */
-
 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 AgentScope = "user" | "project" | "both";
-
-export type ThinkingLevel =
-  | "off"
-  | "minimal"
-  | "low"
-  | "medium"
-  | "high"
-  | "xhigh";
+export type AgentSource = "user" | "project";
+export type AgentScope = AgentSource | "both";
 
 const THINKING_LEVELS = [
   "off",
@@ -26,6 +15,8 @@ const THINKING_LEVELS = [
   "xhigh",
 ] as const;
 
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+
 export interface AgentConfig {
   name: string;
   description: string;
@@ -33,24 +24,37 @@ export interface AgentConfig {
   skills?: string[];
   thinking?: ThinkingLevel;
   systemPrompt: string;
-  source: "user" | "project";
+  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(
-  userAgents: AgentConfig[],
-  projectAgents: AgentConfig[],
+  userResult: AgentDiscoveryScopeResult,
+  projectResult: AgentDiscoveryScopeResult,
   projectAgentsDir: string | null,
 ): AgentDiscoveryResult {
   const agentMap = new Map<string, AgentConfig>();
-  for (const agent of userAgents) agentMap.set(agent.name, agent);
-  for (const agent of projectAgents) agentMap.set(agent.name, agent);
-  return { agents: Array.from(agentMap.values()), projectAgentsDir };
+  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 {
@@ -72,7 +76,7 @@ function parseThinkingLevel(raw: unknown): ThinkingLevel | undefined {
 
 function parseAgentConfig(
   content: string,
-  source: "user" | "project",
+  source: AgentSource,
   filePath: string,
 ): AgentConfig | null {
   let parsed: ReturnType<typeof parseFrontmatter<Record<string, unknown>>>;
@@ -116,35 +120,70 @@ function parseAgentConfig(
   };
 }
 
-async function loadAgentsFromDirAsync(
+async function loadAgentEntryAsync(
   dir: string,
-  source: "user" | "project",
-): Promise<AgentConfig[]> {
-  const agents: AgentConfig[] = [];
-  if (!(await isDirectoryAsync(dir))) return agents;
-  let entries: Dirent[];
+  entryName: string,
+  source: AgentSource,
+): Promise<AgentConfig | null> {
+  const filePath = path.join(dir, entryName);
+  let content: string;
   try {
-    entries = await fsPromises.readdir(dir, { withFileTypes: true });
+    content = await fsPromises.readFile(filePath, "utf-8");
   } catch {
-    return agents;
+    return null;
   }
-  for (const entry of entries) {
-    if (!entry.name.endsWith(".md")) continue;
-    if (!entry.isFile() && !entry.isSymbolicLink()) continue;
-    const filePath = path.join(dir, entry.name);
-    let content: string;
-    try {
-      content = await fsPromises.readFile(filePath, "utf-8");
-    } catch {
-      continue;
-    }
-    const agent = parseAgentConfig(content, source, filePath);
-    if (agent) agents.push(agent);
+  return parseAgentConfig(content, source, filePath);
+}
+
+export function emptyScopeResult(): AgentDiscoveryScopeResult {
+  return { agents: [], markdownFiles: [] };
+}
+
+async function loadAgentsFromDirAsync(
+  dir: string,
+  source: AgentSource,
+): Promise<AgentDiscoveryScopeResult> {
+  const markdownEntries = (await readMarkdownDirWithStatusAsync(dir)).entries;
+  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 interface MarkdownDirListing {
+  entries: Dirent[];
+  ok: boolean;
+}
+
+export async function readMarkdownDirWithStatusAsync(
+  dir: string | null,
+): Promise<MarkdownDirListing> {
+  if (!dir) return { entries: [], ok: true };
+  try {
+    const entries = await fsPromises.readdir(dir, { withFileTypes: true });
+    return { entries: entries.filter(isMarkdownDirent), ok: true };
+  } catch {
+    return { entries: [], ok: false };
   }
-  return agents;
 }
 
-async function isDirectoryAsync(p: string): Promise<boolean> {
+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 {
@@ -169,15 +208,17 @@ export async function discoverAgentsAsync(
   cwd: string,
   scope: AgentScope,
 ): Promise<AgentDiscoveryResult> {
-  const userDir = path.join(getAgentDir(), "agents");
+  const userDir = getUserAgentsDir();
   const projectAgentsDir = await findNearestProjectAgentsDirAsync(cwd);
-  const [userAgents, projectAgents] = await Promise.all([
-    scope === "project" ? [] : loadAgentsFromDirAsync(userDir, "user"),
+  const [userDiscovery, projectDiscovery] = await Promise.all([
+    scope === "project"
+      ? emptyScopeResult()
+      : loadAgentsFromDirAsync(userDir, "user"),
     scope === "user" || !projectAgentsDir
-      ? []
+      ? emptyScopeResult()
       : loadAgentsFromDirAsync(projectAgentsDir, "project"),
   ]);
-  return mergeAgentLists(userAgents, projectAgents, projectAgentsDir);
+  return mergeAgentLists(userDiscovery, projectDiscovery, projectAgentsDir);
 }
 
 export function formatAgentList(

package/src/child/child-events.ts

@@ -1,14 +1,87 @@
-type ChildKnownEvent =
+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: "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 };
 
-const KNOWN_TYPES = new Set(["message_end", "tool_result_end", "agent_end"]);
+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())
@@ -26,6 +99,20 @@ export function parseChildEventLine(line: string): ChildEventParseResult {
     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 };