@ilya-lesikov/pi-pi 0.1.0

package/3p/pi-subagents/src/agent-types.ts

@@ -0,0 +1,248 @@
+/**
+ * agent-types.ts — Unified agent type registry.
+ *
+ * Merges embedded default agents with user-defined agents from .pi/agents/*.md.
+ * User agents override defaults with the same name. Disabled agents are kept but excluded from spawning.
+ */
+
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import {
+  createBashTool,
+  createEditTool,
+  createFindTool,
+  createGrepTool,
+  createLsTool,
+  createReadTool,
+  createWriteTool,
+} from "@earendil-works/pi-coding-agent";
+import { DEFAULT_AGENTS } from "./default-agents.js";
+import type { AgentConfig } from "./types.js";
+
+type ToolFactory = (cwd: string) => AgentTool<any>;
+
+const TOOL_FACTORIES: Record<string, ToolFactory> = {
+  read: (cwd) => createReadTool(cwd),
+  bash: (cwd) => createBashTool(cwd),
+  edit: (cwd) => createEditTool(cwd),
+  write: (cwd) => createWriteTool(cwd),
+  grep: (cwd) => createGrepTool(cwd),
+  find: (cwd) => createFindTool(cwd),
+  ls: (cwd) => createLsTool(cwd),
+};
+
+/** All known built-in tool names, derived from the factory registry. */
+export const BUILTIN_TOOL_NAMES = Object.keys(TOOL_FACTORIES);
+
+/** Unified runtime registry of all agents (defaults + user-defined). */
+const agents = new Map<string, AgentConfig>();
+
+/** Extension-injected agents (highest priority, survive reloads). */
+const extensionAgents = new Map<string, AgentConfig>();
+
+/** When true, only extension-registered agents are used. Defaults and user .md files are skipped. */
+let extensionOnlyMode = false;
+
+/** Enable extension-only mode: skip defaults and user .md agents entirely. */
+export function setExtensionOnlyMode(enabled: boolean): void {
+  extensionOnlyMode = enabled;
+}
+
+/**
+ * Register agents into the unified registry.
+ * Priority (highest wins): extension agents > user .md files > defaults.
+ * In extension-only mode, defaults and user agents are skipped entirely.
+ * Disabled agents (enabled === false) are kept in the registry but excluded from spawning.
+ */
+export function registerAgents(userAgents: Map<string, AgentConfig>): void {
+  agents.clear();
+
+  if (!extensionOnlyMode) {
+    // Start with defaults
+    for (const [name, config] of DEFAULT_AGENTS) {
+      agents.set(name, config);
+    }
+
+    // Overlay user agents (overrides defaults with same name)
+    for (const [name, config] of userAgents) {
+      agents.set(name, config);
+    }
+  }
+
+  // Overlay extension-injected agents (highest priority)
+  for (const [name, config] of extensionAgents) {
+    agents.set(name, config);
+  }
+}
+
+/**
+ * Register agents from another extension (e.g. pi-pi).
+ * These persist across reloadCustomAgents() calls and take highest priority.
+ */
+export function registerExtensionAgents(newAgents: Map<string, AgentConfig>): void {
+  for (const [name, config] of newAgents) {
+    extensionAgents.set(name, config);
+  }
+}
+
+/**
+ * Remove extension-registered agents by name.
+ */
+export function unregisterExtensionAgents(names: string[]): void {
+  for (const name of names) {
+    extensionAgents.delete(name);
+  }
+}
+
+/**
+ * Remove extension-registered agents whose names start with a prefix.
+ */
+export function unregisterExtensionAgentsByPrefix(prefix: string): void {
+  for (const name of extensionAgents.keys()) {
+    if (name.startsWith(prefix)) {
+      extensionAgents.delete(name);
+    }
+  }
+}
+
+/**
+ * Remove all extension-registered agents.
+ */
+export function clearExtensionAgents(): void {
+  extensionAgents.clear();
+}
+
+/** Case-insensitive key resolution. */
+function resolveKey(name: string): string | undefined {
+  if (agents.has(name)) return name;
+  const lower = name.toLowerCase();
+  for (const key of agents.keys()) {
+    if (key.toLowerCase() === lower) return key;
+  }
+  return undefined;
+}
+
+/** Resolve a type name case-insensitively. Returns the canonical key or undefined. */
+export function resolveType(name: string): string | undefined {
+  return resolveKey(name);
+}
+
+/** Get the agent config for a type (case-insensitive). */
+export function getAgentConfig(name: string): AgentConfig | undefined {
+  const key = resolveKey(name);
+  return key ? agents.get(key) : undefined;
+}
+
+/** Get all enabled type names (for spawning and tool descriptions). */
+export function getAvailableTypes(): string[] {
+  return [...agents.entries()]
+    .filter(([_, config]) => config.enabled !== false)
+    .map(([name]) => name);
+}
+
+/** Get all type names including disabled (for UI listing). */
+export function getAllTypes(): string[] {
+  return [...agents.keys()];
+}
+
+/** Get names of default agents currently in the registry. */
+export function getDefaultAgentNames(): string[] {
+  return [...agents.entries()]
+    .filter(([_, config]) => config.isDefault === true)
+    .map(([name]) => name);
+}
+
+/** Get names of user-defined agents (non-defaults) currently in the registry. */
+export function getUserAgentNames(): string[] {
+  return [...agents.entries()]
+    .filter(([_, config]) => config.isDefault !== true)
+    .map(([name]) => name);
+}
+
+/** Check if a type is valid and enabled (case-insensitive). */
+export function isValidType(type: string): boolean {
+  const key = resolveKey(type);
+  if (!key) return false;
+  return agents.get(key)?.enabled !== false;
+}
+
+/** Tool names required for memory management. */
+const MEMORY_TOOL_NAMES = ["read", "write", "edit"];
+
+/**
+ * Get the tools needed for memory management (read, write, edit).
+ * Only returns tools that are NOT already in the provided set.
+ */
+export function getMemoryTools(cwd: string, existingToolNames: Set<string>): AgentTool<any>[] {
+  return MEMORY_TOOL_NAMES
+    .filter(n => !existingToolNames.has(n) && n in TOOL_FACTORIES)
+    .map(n => TOOL_FACTORIES[n](cwd));
+}
+
+/** Tool names needed for read-only memory access. */
+const READONLY_MEMORY_TOOL_NAMES = ["read"];
+
+/**
+ * Get only the read tool for read-only memory access.
+ * Only returns tools that are NOT already in the provided set.
+ */
+export function getReadOnlyMemoryTools(cwd: string, existingToolNames: Set<string>): AgentTool<any>[] {
+  return READONLY_MEMORY_TOOL_NAMES
+    .filter(n => !existingToolNames.has(n) && n in TOOL_FACTORIES)
+    .map(n => TOOL_FACTORIES[n](cwd));
+}
+
+/** Get built-in tools for a type (case-insensitive). */
+export function getToolsForType(type: string, cwd: string): AgentTool<any>[] {
+  const key = resolveKey(type);
+  const raw = key ? agents.get(key) : undefined;
+  const config = raw?.enabled !== false ? raw : undefined;
+  const toolNames = config?.builtinToolNames?.length ? config.builtinToolNames : BUILTIN_TOOL_NAMES;
+  return toolNames.filter((n) => n in TOOL_FACTORIES).map((n) => TOOL_FACTORIES[n](cwd));
+}
+
+/** Get config for a type (case-insensitive, returns a SubagentTypeConfig-compatible object). Falls back to general-purpose. */
+export function getConfig(type: string): {
+  displayName: string;
+  description: string;
+  builtinToolNames: string[];
+  extensions: true | string[] | false;
+  skills: true | string[] | false;
+  promptMode: "replace" | "append";
+} {
+  const key = resolveKey(type);
+  const config = key ? agents.get(key) : undefined;
+  if (config && config.enabled !== false) {
+    return {
+      displayName: config.displayName ?? config.name,
+      description: config.description,
+      builtinToolNames: config.builtinToolNames ?? BUILTIN_TOOL_NAMES,
+      extensions: config.extensions,
+      skills: config.skills,
+      promptMode: config.promptMode,
+    };
+  }
+
+  // Fallback for unknown/disabled types — general-purpose config
+  const gp = agents.get("general-purpose");
+  if (gp && gp.enabled !== false) {
+    return {
+      displayName: gp.displayName ?? gp.name,
+      description: gp.description,
+      builtinToolNames: gp.builtinToolNames ?? BUILTIN_TOOL_NAMES,
+      extensions: gp.extensions,
+      skills: gp.skills,
+      promptMode: gp.promptMode,
+    };
+  }
+
+  // Absolute fallback (should never happen)
+  return {
+    displayName: "Agent",
+    description: "General-purpose agent for complex, multi-step tasks",
+    builtinToolNames: BUILTIN_TOOL_NAMES,
+    extensions: true,
+    skills: true,
+    promptMode: "append",
+  };
+}
+

package/3p/pi-subagents/src/context.ts

@@ -0,0 +1,58 @@
+/**
+ * context.ts — Extract parent conversation context for subagent inheritance.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+/** Extract text from a message content block array. */
+export function extractText(content: unknown[]): string {
+  return content
+    .filter((c: any) => c.type === "text")
+    .map((c: any) => c.text ?? "")
+    .join("\n");
+}
+
+/**
+ * Build a text representation of the parent conversation context.
+ * Used when inherit_context is true to give the subagent visibility
+ * into what has been discussed/done so far.
+ */
+export function buildParentContext(ctx: ExtensionContext): string {
+  const entries = ctx.sessionManager.getBranch();
+  if (!entries || entries.length === 0) return "";
+
+  const parts: string[] = [];
+
+  for (const entry of entries) {
+    if (entry.type === "message") {
+      const msg = entry.message;
+      if (msg.role === "user") {
+        const text = typeof msg.content === "string"
+          ? msg.content
+          : extractText(msg.content);
+        if (text.trim()) parts.push(`[User]: ${text.trim()}`);
+      } else if (msg.role === "assistant") {
+        const text = extractText(msg.content);
+        if (text.trim()) parts.push(`[Assistant]: ${text.trim()}`);
+      }
+      // Skip toolResult messages — too verbose for context
+    } else if (entry.type === "compaction") {
+      // Include compaction summaries — they're already condensed
+      if (entry.summary) {
+        parts.push(`[Summary]: ${entry.summary}`);
+      }
+    }
+  }
+
+  if (parts.length === 0) return "";
+
+  return `# Parent Conversation Context
+The following is the conversation history from the parent session that spawned you.
+Use this context to understand what has been discussed and decided so far.
+
+${parts.join("\n\n")}
+
+---
+# Your Task (below)
+`;
+}

package/3p/pi-subagents/src/cross-extension-rpc.ts

@@ -0,0 +1,135 @@
+/**
+ * Cross-extension RPC handlers for the subagents extension.
+ *
+ * Exposes ping, spawn, and stop RPCs over the pi.events event bus,
+ * using per-request scoped reply channels.
+ *
+ * Reply envelope follows pi-mono convention:
+ *   success → { success: true, data?: T }
+ *   error   → { success: false, error: string }
+ */
+
+/** Minimal event bus interface needed by the RPC handlers. */
+export interface EventBus {
+  on(event: string, handler: (data: unknown) => void): () => void;
+  emit(event: string, data: unknown): void;
+}
+
+/** RPC reply envelope — matches pi-mono's RpcResponse shape. */
+export type RpcReply<T = void> =
+  | { success: true; data?: T }
+  | { success: false; error: string };
+
+/** RPC protocol version — bumped when the envelope or method contracts change. */
+export const PROTOCOL_VERSION = 2;
+
+/** Minimal AgentManager interface needed by the spawn/stop RPCs. */
+export interface SpawnCapable {
+  spawn(pi: unknown, ctx: unknown, type: string, prompt: string, options: any): string;
+  abort(id: string): boolean;
+}
+
+export interface SpawnRequest {
+  requestId: string;
+  type: string;
+  prompt: string;
+  options?: any;
+}
+
+export interface RpcDeps {
+  events: EventBus;
+  pi: unknown;                    // passed through to manager.spawn
+  getCtx: () => unknown | undefined;  // returns current ExtensionContext
+  isSubagentSession?: (ctx: unknown) => boolean;
+  manager: SpawnCapable;
+}
+
+export interface RpcHandle {
+  unsubPing: () => void;
+  unsubSpawn: () => void;
+  unsubStop: () => void;
+}
+
+function emitReply(events: EventBus, channel: string, requestId: string, reply: RpcReply<unknown>): void {
+  events.emit(`${channel}:reply:${requestId}`, reply);
+}
+
+/**
+ * Wire a single RPC handler: listen on `channel`, run `fn(params)`,
+ * emit the reply envelope on `channel:reply:${requestId}`.
+ */
+function handleRpc<P extends { requestId: string }>(
+  events: EventBus,
+  channel: string,
+  fn: (params: P) => unknown | Promise<unknown>,
+): () => void {
+  return events.on(channel, async (raw: unknown) => {
+    const params = raw as P;
+    try {
+      const data = await fn(params);
+      const reply: { success: true; data?: unknown } = { success: true };
+      if (data !== undefined) reply.data = data;
+      events.emit(`${channel}:reply:${params.requestId}`, reply);
+    } catch (err: any) {
+      events.emit(`${channel}:reply:${params.requestId}`, {
+        success: false, error: err?.message ?? String(err),
+      });
+    }
+  });
+}
+
+/**
+ * Register ping, spawn, and stop RPC handlers on the event bus.
+ * Returns unsub functions for cleanup.
+ */
+export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
+  const { events, pi, getCtx, isSubagentSession, manager } = deps;
+
+  const unsubPing = handleRpc(events, "subagents:rpc:ping", () => {
+    return { version: PROTOCOL_VERSION };
+  });
+
+  const unsubSpawn = events.on("subagents:rpc:spawn", (raw: unknown) => {
+    const params = raw as SpawnRequest;
+    const ctx = getCtx();
+    if (!ctx) {
+      emitReply(events, "subagents:rpc:spawn", params.requestId, { success: false, error: "No active session" });
+      return;
+    }
+    if (isSubagentSession?.(ctx)) {
+      emitReply(events, "subagents:rpc:spawn", params.requestId, {
+        success: false,
+        error: "Cannot spawn subagents from a subagent session context",
+      });
+      return;
+    }
+
+    queueMicrotask(() => {
+      try {
+        const rawOpts = params.options ?? {};
+        const spawnOpts = { ...rawOpts, isBackground: rawOpts.isBackground ?? rawOpts.run_in_background ?? true };
+        const id = manager.spawn(pi, ctx, params.type, params.prompt, spawnOpts);
+        events.emit("subagents:created", {
+          id,
+          type: params.type,
+          description: params.options?.description ?? params.type,
+          isBackground: params.options?.run_in_background ?? true,
+        });
+        emitReply(events, "subagents:rpc:spawn", params.requestId, { success: true, data: { id } });
+      } catch (err: any) {
+        emitReply(events, "subagents:rpc:spawn", params.requestId, {
+          success: false,
+          error: err?.message ?? String(err),
+        });
+      }
+    });
+  });
+
+  const unsubStop = handleRpc<{ requestId: string; agentId: string }>(
+    events, "subagents:rpc:stop", ({ agentId }) => {
+      if (!manager.abort(agentId)) throw new Error("Agent not found");
+    },
+  );
+
+  return { unsubPing, unsubSpawn, unsubStop };
+}

package/3p/pi-subagents/src/custom-agents.ts

@@ -0,0 +1,137 @@
+/**
+ * custom-agents.ts — Load user-defined agents from project (.pi/agents/) and global (~/.pi/agent/agents/) locations.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { BUILTIN_TOOL_NAMES } from "./agent-types.js";
+import type { AgentConfig, MemoryScope, ThinkingLevel } from "./types.js";
+
+/**
+ * Scan for custom agent .md files from multiple locations.
+ * Discovery hierarchy (higher priority wins):
+ *   1. Project: <cwd>/.pi/agents/*.md
+ *   2. Global:  ~/.pi/agent/agents/*.md
+ *
+ * Project-level agents override global ones with the same name.
+ * Any name is allowed — names matching defaults (e.g. "Explore") override them.
+ */
+export function loadCustomAgents(cwd: string): Map<string, AgentConfig> {
+  const globalDir = join(homedir(), ".pi", "agent", "agents");
+  const projectDir = join(cwd, ".pi", "agents");
+
+  const agents = new Map<string, AgentConfig>();
+  loadFromDir(globalDir, agents, "global");   // lower priority
+  loadFromDir(projectDir, agents, "project");  // higher priority (overwrites)
+  return agents;
+}
+
+/** Load agent configs from a directory into the map. */
+function loadFromDir(dir: string, agents: Map<string, AgentConfig>, source: "project" | "global"): void {
+  if (!existsSync(dir)) return;
+
+  let files: string[];
+  try {
+    files = readdirSync(dir).filter(f => f.endsWith(".md"));
+  } catch {
+    return;
+  }
+
+  for (const file of files) {
+    const name = basename(file, ".md");
+
+    let content: string;
+    try {
+      content = readFileSync(join(dir, file), "utf-8");
+    } catch {
+      continue;
+    }
+
+    const { frontmatter: fm, body } = parseFrontmatter<Record<string, unknown>>(content);
+
+    agents.set(name, {
+      name,
+      displayName: str(fm.display_name),
+      description: str(fm.description) ?? name,
+      builtinToolNames: csvList(fm.tools, BUILTIN_TOOL_NAMES),
+      disallowedTools: csvListOptional(fm.disallowed_tools),
+      extensions: inheritField(fm.extensions ?? fm.inherit_extensions),
+      skills: inheritField(fm.skills ?? fm.inherit_skills),
+      model: str(fm.model),
+      thinking: str(fm.thinking) as ThinkingLevel | undefined,
+      maxTurns: nonNegativeInt(fm.max_turns),
+      systemPrompt: body.trim(),
+      promptMode: fm.prompt_mode === "append" ? "append" : "replace",
+      inheritContext: fm.inherit_context != null ? fm.inherit_context === true : undefined,
+      runInBackground: fm.run_in_background != null ? fm.run_in_background === true : undefined,
+      isolated: fm.isolated != null ? fm.isolated === true : undefined,
+      memory: parseMemory(fm.memory),
+      isolation: fm.isolation === "worktree" ? "worktree" : undefined,
+      enabled: fm.enabled !== false,  // default true; explicitly false disables
+      source,
+    });
+  }
+}
+
+// ---- Field parsers ----
+// All follow the same convention: omitted → default, "none"/empty → nothing, value → exact.
+
+/** Extract a string or undefined. */
+function str(val: unknown): string | undefined {
+  return typeof val === "string" ? val : undefined;
+}
+
+/** Extract a non-negative integer or undefined. 0 means unlimited for max_turns. */
+function nonNegativeInt(val: unknown): number | undefined {
+  return typeof val === "number" && val >= 0 ? val : undefined;
+}
+
+/**
+ * Parse a raw CSV field value into items, or undefined if absent/empty/"none".
+ */
+function parseCsvField(val: unknown): string[] | undefined {
+  if (val === undefined || val === null) return undefined;
+  const s = String(val).trim();
+  if (!s || s === "none") return undefined;
+  const items = s.split(",").map(t => t.trim()).filter(Boolean);
+  return items.length > 0 ? items : undefined;
+}
+
+/**
+ * Parse a comma-separated list field with defaults.
+ * omitted → defaults; "none"/empty → []; csv → listed items.
+ */
+function csvList(val: unknown, defaults: string[]): string[] {
+  if (val === undefined || val === null) return defaults;
+  return parseCsvField(val) ?? [];
+}
+
+/**
+ * Parse an optional comma-separated list field.
+ * omitted → undefined; "none"/empty → undefined; csv → listed items.
+ */
+function csvListOptional(val: unknown): string[] | undefined {
+  return parseCsvField(val);
+}
+
+/**
+ * Parse a memory scope field.
+ * omitted → undefined; "user"/"project"/"local" → MemoryScope.
+ */
+function parseMemory(val: unknown): MemoryScope | undefined {
+  if (val === "user" || val === "project" || val === "local") return val;
+  return undefined;
+}
+
+/**
+ * Parse an inherit field (extensions, skills).
+ * omitted/true → true (inherit all); false/"none"/empty → false; csv → listed names.
+ */
+function inheritField(val: unknown): true | string[] | false {
+  if (val === undefined || val === null || val === true) return true;
+  if (val === false || val === "none") return false;
+  const items = csvList(val, []);
+  return items.length > 0 ? items : false;
+}