pi-subagents-lite 1.2.0 → 1.4.0

package/src/index.ts

@@ -11,8 +11,8 @@
  *
  * Config:
  *   - Loaded from ~/.pi/agent/subagents-lite.json at session_start
- *   - Module-level __config cache; tool_call reads from cache
- *   - Config mutations update cache + atomic write to disk
+ *   - ConfigStore owns config + session overrides + persistence + side effects
+ *   - Tool execution and menus read/write through store
  *
  * Commands:
  *   - /agents: Management menu (model settings, concurrency, running agents, debug)
@@ -23,276 +23,13 @@
  *   - session_shutdown: Abort all, dispose manager
  */
 
-import { Type } from "@sinclair/typebox";
-import * as path from "node:path";
-import type {
-  ExtensionAPI,
-  ExtensionCommandContext,
-  ExtensionContext,
-} from "@earendil-works/pi-coding-agent";
-import { DEFAULT_AGENTS } from "./default-agents.js";
-import { registerAgents, getAvailableTypes, setAgentScanDirs } from "./agent-types.js";
-import { scanAgentFilesInDir, mergeAgents } from "./agent-discovery.js";
-import { AgentManager } from "./agent-manager.js";
-import { AgentWidget, type UICtx } from "./ui/agent-widget.js";
-import { showAgentsMainMenu } from "./menus.js";
-import { loadConfig } from "./config-io.js";
-import { executeAgentTool, executeStopAgentTool, toolCallListener, backgroundAgentIds, scheduleNudge } from "./tool-execution.js";
-import { renderAgentToolCall, renderAgentToolResult, renderSubagentResult } from "./renderer.js";
-import {
-  __config,
-  sessionOverrides,
-  agentActivity,
-  piInstance,
-  setConfig,
-  setManager,
-  clearManager,
-  setWidget,
-  setPiInstance,
-  setSessionCtx,
-  resetSessionOverrides,
-  resetLastToolsExpanded,
-  syncWidgetSettings,
-  syncCompactFromToolsExpanded,
-  getManager,
-  getWidget,
-} from "./state.js";
-
-// Re-exports for backward compatibility
-export {
-  __config,
-  sessionOverrides,
-  agentActivity,
-  piInstance,
-  setShowCostEnabled,
-  syncWidgetSettings,
-  syncCompactFromToolsExpanded,
-} from "./state.js";
-
-
-
-// ============================================================================
-// Config loader — session_start handler logic
-// ============================================================================
-
-/**
- * Ensure the manager and widget singletons exist.
- * Idempotent — safe to call on every session_start.
- */
-function ensureManagerAndWidget(): void {
-  const currentManager = getManager();
-  const currentWidget = getWidget();
-  // Create manager if missing
-  if (!currentManager) {
-    const newManager = new AgentManager(
-      (record) => {
-        // Only nudge for background (async) agents — sync agents already returned via tool result
-        if (backgroundAgentIds.has(record.id)) {
-          scheduleNudge(record.id);
-          backgroundAgentIds.delete(record.id);
-        }
-
-        // Mark finished and update widget BEFORE deleting activity —
-        // renderFinishedLine reads activity for turn count, tokens, etc.
-        getWidget()?.markFinished(record.id);
-        getWidget()?.update();
-
-        // Remove from live activity tracking
-        agentActivity.delete(record.id);
-      },
-      __config.concurrency,
-    );
-    setManager(newManager);
-  }
-
-  // Create widget if missing (uses existing or newly created manager)
-  if (!currentWidget) {
-    const newWidget = new AgentWidget(getManager(), agentActivity);
-    newWidget.setShowCost(__config.agent.showCost === true);
-    setWidget(newWidget);
-    syncWidgetSettings();
-  }
-}
-
-/**
- * Scan agent files from user and project directories, merge with defaults,
- * and register into the type registry.
- */
-async function scanAndRegisterAgents(ctx: ExtensionContext): Promise<void> {
-  const homeDir = process.env.HOME || "";
-  const userAgentDir = path.join(homeDir, ".pi", "agent", "agents");
-  const projectAgentDir = path.join(ctx.cwd, ".pi", "agents");
-
-  // Store scan dirs for on-demand discovery (agents added during the session)
-  setAgentScanDirs(userAgentDir, projectAgentDir);
-
-  const [userAgents, projectAgents] = await Promise.all([
-    scanAgentFilesInDir(userAgentDir, "user"),
-    scanAgentFilesInDir(projectAgentDir, "project"),
-  ]);
-
-  // Merge with defaults
-  const merged = mergeAgents(DEFAULT_AGENTS, userAgents, projectAgents);
-
-  // Register into the type registry
-  registerAgents(merged);
-}
-
-async function loadConfigAndRegisterAgents(ctx: ExtensionContext): Promise<void> {
-  setConfig(loadConfig());
-  ensureManagerAndWidget();
-  await scanAndRegisterAgents(ctx);
-}
-
-
-
-// ============================================================================
-// Agent tool registration helper — dynamic enum for agent types
-// ============================================================================
-
-/**
- * Register (or re-register) the Agent tool with current agent types.
- * At init time only defaults exist; call again from session_start after
- * user/project agents are loaded to update the enum.
- */
-function registerAgentTool(pi: ExtensionAPI): void {
-  const types = getAvailableTypes();
-  // Use plain string to avoid verbose anyOf in prompt.
-  // Available types are listed in description for discoverability.
-  const agentParam = types.length > 0
-    ? Type.Optional(Type.String({ description: types.join(",") }))
-    : Type.Optional(Type.String());
-  // @ts-expect-error — description removed to save prompt tokens
-  pi.registerTool({
-    name: "Agent",
-    label: "Agent",
-    parameters: Type.Object({
-      prompt: Type.String(),
-      description: Type.String(),
-      agent: agentParam,
-      run_in_background: Type.Optional(Type.Boolean()),
-      worktree_path: Type.Optional(Type.String()),
-    }),
-    execute: executeAgentTool,
-
-    renderCall: (args, theme) => renderAgentToolCall(args as Record<string, unknown>, theme),
-
-    renderResult: (result, options, theme) => renderAgentToolResult(
-      result as { content: Array<{ type: string; text?: string }>; details?: Record<string, unknown>; isError?: boolean },
-      options as { expanded?: boolean },
-      theme,
-    ),
-  });
-}
-
-// ============================================================================
-// Extension factory
-// ============================================================================
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { setPiInstance } from "./shell.js";
+import { registerTools } from "./registration.js";
+import { setupEventListeners } from "./events.js";
 
 export default function (pi: ExtensionAPI) {
-  // Store pi for execute callbacks
   setPiInstance(pi);
-
-  // ========================================================================
-  // Tool registration (stealth schemas — at init time)
-  // ========================================================================
-
-  // Agent tool — stealth schema with dynamic agent type enum
-  registerAgentTool(pi);
-
-  // StopAgent tool — stealth schema, stop a running agent by ID
-  // @ts-expect-error — description removed to save prompt tokens
-  pi.registerTool({
-    name: "StopAgent",
-    label: "StopAgent",
-    parameters: Type.Object({
-      agent_id: Type.String(),
-    }),
-    execute: executeStopAgentTool,
-  });
-
-  // Message renderer — subagent-result (background agent completion)
-  pi.registerMessageRenderer("subagent-result", (message, options, theme) =>
-    renderSubagentResult(
-      message as { content?: string; details?: Record<string, unknown> },
-      options as { expanded?: boolean },
-      theme,
-    ),
-  );
-
-  // Command registration
-  pi.registerCommand("agents", {
-    description: "Manage subagents: agent briefing, model settings, concurrency, running agents, agent types",
-    handler: async (_args: string, ctx: ExtensionCommandContext) => {
-      const modelOptions = ctx.modelRegistry.getAvailable().map((m) => `${m.provider}/${m.id}`);
-      await showAgentsMainMenu(ctx, modelOptions);
-    },
-  });
-
-  // Event listeners
-  pi.on("tool_call", toolCallListener);
-
-  pi.on("tool_execution_start", async (_event, ctx) => {
-    // Set UI context on first tool execution
-    if (!getWidget()) {
-      ensureManagerAndWidget();
-    }
-    getWidget()?.setUICtx(ctx.ui as unknown as UICtx);
-    getWidget()?.onTurnStart();
-  });
-
-
-
-  // session_start — load config, scan agents, register into registry,
-  // then re-register Agent tool with dynamic agent type enum
-  // Listen for ctrl+o keypress to sync compact mode (push-based, no polling)
-  let unregisterTerminalInput: (() => void) | undefined;
-
-  pi.on("session_start", async (_event: unknown, ctx: ExtensionContext) => {
-    setSessionCtx(ctx);
-    resetSessionOverrides();
-    agentActivity.clear();
-    resetLastToolsExpanded();
-    await loadConfigAndRegisterAgents(ctx);
-    // Re-register with updated agent type list (now includes user/project agents)
-    registerAgentTool(pi);
-    // Register ctrl+o listener
-    if (ctx.hasUI && !unregisterTerminalInput) {
-      unregisterTerminalInput = ctx.ui.onTerminalInput((data: string) => {
-        // ctrl+o = 0x0F (15) — toggles tool expansion
-        if (data === "\u000f") {
-          // Read state after a tick to let the built-in handler process it first
-          setTimeout(() => {
-            const ui = ctx.ui as unknown as { getToolsExpanded?: () => boolean };
-            const expanded = ui.getToolsExpanded?.();
-            if (expanded !== undefined) {
-              getWidget()?.notifyToolsExpansionChanged(expanded);
-            }
-          }, 0);
-        }
-        return undefined; // Don't consume the input
-      });
-    }
-    // Sync compact mode with initial tool expansion state
-    syncCompactFromToolsExpanded(false);
-  });
-
-  pi.on("session_shutdown", async (_event: unknown, ctx: ExtensionContext) => {
-    // Warn if agents were killed
-    const currentManager = getManager();
-    if (currentManager) {
-      const records = currentManager.listAgents();
-      const active = records.filter(r => r.lifecycle.status === "running" || r.lifecycle.status === "queued");
-      if (active.length > 0 && ctx.hasUI) {
-        ctx.ui.notify(`${active.length} agent(s) killed by reload`, "warning");
-      }
-    }
-    getWidget()?.dispose();
-    setWidget(undefined);
-    const mgr = getManager();
-    if (mgr) {
-      await mgr.dispose();
-      clearManager();
-    }
-  });
+  registerTools(pi);
+  setupEventListeners(pi);
 }

package/src/{model-precedence.ts → models/model-precedence.ts}

@@ -12,6 +12,9 @@
  *   6. parentModelId                   (inherit from parent)
  */
 
+import type { ThinkingLevel } from "../types.js";
+import type { SystemPromptMode } from "../agents/types.js";
+
 /** Shape of the subagents-lite.json config file. */
 export interface SubagentsConfig {
   agent: {
@@ -23,6 +26,36 @@ export interface SubagentsConfig {
     widgetMaxLinesCompact?: number;
     widgetCompact?: boolean;
     widgetShortcut?: boolean;
+    /** System prompt mode: replace (default), inherit parent, or custom file. */
+    systemPromptMode?: SystemPromptMode;
+    /** Whether to include AGENTS.md context files in the subagent system prompt. Default: true. */
+    includeContextFiles?: boolean;
+    /** Default thinking level for spawned agents. Undefined = inherit from agent config. */
+    defaultThinking?: ThinkingLevel;
+    /** Default max turns for spawned agents. Undefined = unlimited. */
+    defaultMaxTurns?: number;
+    /** Global default for skills loading when agent doesn't explicitly set skills. true (default) or false. */
+    loadSkillsImplicitly?: boolean;
+    /** Global default for extensions loading when agent doesn't explicitly set extensions. true (default) or false. */
+    loadExtensionsImplicitly?: boolean;
+    /** When true, skip built-in default agents (general-purpose, Explore) at registration. */
+    disableDefaultAgents?: boolean;
+    /** Whether to show toolUses count in widget stats line. Default: true. */
+    showTools?: boolean;
+    /** Whether to show turn count in widget stats line. Default: true. */
+    showTurns?: boolean;
+    /** Whether to show input tokens in widget stats line. Default: true. */
+    showInput?: boolean;
+    /** Whether to show output tokens in widget stats line. Default: true. */
+    showOutput?: boolean;
+    /** Whether to show context percent and compactions in widget stats line. Default: true. */
+    showContext?: boolean;
+    /** Whether to show elapsed time in widget stats line. Default: true. */
+    showTime?: boolean;
+    /** Max description length in widget full mode. Default: 50. */
+    widgetDescLengthFull?: number;
+    /** Max description length in widget compact mode. Default: 30. */
+    widgetDescLengthCompact?: number;
     [agentType: string]: string | null | undefined | boolean | number;
   };
   concurrency: {

package/src/{model-selector.ts → models/model-selector.ts}

@@ -15,7 +15,7 @@ import {
   Text,
 } from "@earendil-works/pi-tui";
 import { DynamicBorder } from "@earendil-works/pi-coding-agent";
-import type { Theme } from "./ui/agent-widget.js";
+import type { Theme } from "../ui/agent-widget.js";
 
 /* ------------------------------------------------------------------ */
 /*  Types                                                              */

package/src/{context.ts → prompt/context.ts}

@@ -5,7 +5,7 @@
  * buildSnapshotMarkdown: format agent conversation as markdown for snapshot viewer.
  */
 
-import { summarizeToolArgs } from "./format.js";
+import { summarizeToolArgs } from "../ui/format.js";
 
 function isTextBlock(c: unknown): c is { type: "text"; text: string } {
   return typeof c === "object" && c !== null && (c as Record<string, unknown>).type === "text";

package/src/prompt/prompts.ts

@@ -0,0 +1,180 @@
+/**
+ * prompts.ts — System prompt builder for agents.
+ *
+ * Every agent gets a fresh context — no inherited parent identity.
+ * EnvInfo is imported from types.ts — branch is a string (empty when unknown).
+ */
+
+import type { EnvInfo } from "../types.js";
+import type { AgentConfig, SystemPromptMode } from "../agents/types.js";
+import type { SkillMeta, PreloadedSkill } from "./skill-loader.js";
+import { formatSkillsForPrompt, type Skill } from "@earendil-works/pi-coding-agent";
+
+/** Extra sections to inject into the system prompt (skills). */
+export interface PromptExtras {
+  /** Preloaded skill contents to inject (full content + description). */
+  skillBlocks?: PreloadedSkill[];
+  /** Skill metadata for whitelist display (name, description, location only). */
+  skillMetas?: SkillMeta[];
+  /** Parent system prompt (for inherit mode). */
+  parentSystemPrompt?: string;
+  /** Custom system prompt content (for custom mode). */
+  customSystemPrompt?: string;
+  /** Project context files (AGENTS.md) for custom mode. */
+  contextFiles?: Array<{ path: string; content: string }>;
+}
+
+/**
+ * Strip pi scaffolding sections from a parent system prompt.
+ *
+ * In inherit mode, the parent's prompt already contains:
+ *   - <project_context>...</project_context>  (AGENTS.md)
+ *   - Skills block (text intro + <available_skills>...</available_skills>)
+ *   - Current date: YYYY-MM-DD
+ *   - Current working directory: /path
+ *
+ * These are re-added by subagents-lite from the subagent's own config,
+ * so we strip them to avoid duplication.
+ *
+ * @param prompt  The parent system prompt to clean.
+ * @returns       The prompt with scaffolding sections removed.
+ */
+function stripScaffolding(prompt: string): string {
+  let result = prompt;
+
+  // 1. Strip <project_context>...</project_context> block
+  result = result.replace(/\n?<\s*project_context\s*>[\s\S]*?<\/\s*project_context\s*>\n?/g, "\n");
+
+  // 2. Strip skills block: optional intro text + <available_skills>...</available_skills>
+  result = result.replace(/\n?(?:The following skills provide[\s\S]*?)?<\s*available_skills\s*>[\s\S]*?<\/\s*available_skills\s*>\n?/g, "\n");
+
+  // 3. Strip Current date: line
+  result = result.replace(/\n?Current date:.*\n?/g, "\n");
+
+  // 4. Strip Current working directory: line
+  result = result.replace(/\n?Current working directory:.*\n?/g, "\n");
+
+  // Clean up: collapse runs of 3+ newlines into 2
+  result = result.replace(/\n{3,}/g, "\n\n");
+
+  return result.trim();
+}
+
+/**
+ * Build the system prompt for an agent from its config.
+ *
+ * Three modes:
+ * - replace (default): generic header + env + agent's systemPrompt
+ * - inherit: parent's system prompt (stripped of scaffolding) + env + agent's systemPrompt
+ * - custom: content of ~/.pi/agent/subagents-lite-prompt.md + env + agent's systemPrompt
+ *
+ * Agent's own systemPrompt is always included in <agent_instructions> tags.
+ *
+ * @param config   Agent configuration.
+ * @param cwd      Current working directory.
+ * @param env      Environment info.
+ * @param extras   Optional extra sections to inject (skills, parent/custom prompts).
+ * @param mode     System prompt mode (replace, inherit, custom).
+ */
+export function buildAgentPrompt(
+  config: AgentConfig,
+  cwd: string,
+  env: EnvInfo,
+  extras?: PromptExtras,
+  mode: SystemPromptMode = "replace",
+): string {
+  const envLines = [
+    "# Environment",
+    `Working directory: ${cwd}`,
+    env.isGitRepo ? "Git repository: yes" : "Not a git repository",
+  ];
+  if (env.isGitRepo && env.branch) {
+    envLines.push(`Branch: ${env.branch}`);
+  }
+  envLines.push(`Platform: ${env.platform}`);
+  const envBlock = envLines.join("\n");
+
+  // Unified skill index — all skills in one <available_skills> block
+  const hasSkills = extras?.skillMetas?.length || extras?.skillBlocks?.length;
+  let extrasSuffix = "";
+  if (hasSkills) {
+    const skillLines: string[] = [];
+
+    // Location-based skills: use Pi's formatSkillsForPrompt for XML escaping and
+    // disable-model-invocation filtering, then extract the <skill> elements.
+    if (extras?.skillMetas?.length) {
+      const piSkills: Skill[] = extras.skillMetas.map((m) => ({
+        name: m.name,
+        description: m.description,
+        filePath: m.location,
+        baseDir: "",
+        sourceInfo: {} as any,
+        disableModelInvocation: m.disableModelInvocation,
+      }));
+      const formatted = formatSkillsForPrompt(piSkills);
+      const skillElements = formatted.match(/<skill>[\s\S]*?<\/skill>/g);
+      if (skillElements) skillLines.push(...skillElements);
+    }
+
+    // Preloaded skills: content tags (not in Pi's formatSkillsForPrompt)
+    for (const skill of extras?.skillBlocks ?? []) {
+      skillLines.push(`<skill><name>${escapeXml(skill.name)}</name><description>${escapeXml(skill.description)}</description><content>${escapeXml(skill.content)}</content></skill>`);
+    }
+
+    const lines = [
+      "The 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>",
+      ...skillLines,
+      "</available_skills>",
+    ];
+    extrasSuffix = `\n\n${lines.join("\n")}`;
+  }
+
+  // Agent's own system prompt wrapped in <agent_instructions> tags
+  const agentInstructions = `\n<agent_instructions>\n${config.systemPrompt}\n</agent_instructions>`;
+
+  // Project context files (AGENTS.md) — placed after agent_instructions, before extras
+  let contextSuffix = "";
+  if (extras?.contextFiles?.length) {
+    const lines = [
+      "<project_context>",
+      "",
+      "Project-specific instructions and guidelines:",
+      "",
+    ];
+    for (const file of extras.contextFiles) {
+      lines.push(`<project_instructions path="${escapeXml(file.path)}">`);
+      lines.push(file.content);
+      lines.push(`</project_instructions>`);
+      lines.push("");
+    }
+    lines.push("</project_context>");
+    contextSuffix = `\n\n${lines.join("\n")}`;
+  }
+
+  // Build base prompt: mode-specific header if provided, otherwise default
+  const activeAgentTag = `<active_agent name="${config.name}"/>`;
+  const rawHeader = mode === "inherit" ? extras?.parentSystemPrompt
+                 : mode === "custom"  ? extras?.customSystemPrompt
+                 : undefined;
+  // Parent/custom headers carry pi's scaffolding (context, skills, date, cwd);
+  // strip it — we re-add these from the subagent's own config. (rawHeader is
+  // undefined in replace mode, so nothing to strip there.)
+  const customHeader = rawHeader ? stripScaffolding(rawHeader) : rawHeader;
+  const basePrompt = customHeader
+    ? `${customHeader}\n\n${envBlock}`
+    : `You are a Pi, an expert coding sub-agent.\nYou have been invoked to handle a specific task autonomously.\n\n${envBlock}`;
+
+  // active_agent goes AFTER shared prefix (header + env + context) for KV cache
+  return `${basePrompt}${contextSuffix}\n${activeAgentTag}\n${agentInstructions}${extrasSuffix}`;
+}
+
+function escapeXml(value: string): string {
+  // Only escape < and > — enough for XML-like tags, keeps text readable for LLMs
+  return value
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}