pi-subagents-lite 1.2.0 → 1.4.0

package/src/{tool-execution.ts → agents/tool-execution.ts}

@@ -1,57 +1,40 @@
+import { getStatusNote } from "../status-note.js";
 /**
  * tool-execution.ts — Agent tool execution handlers.
  *
- * Contains the execute callbacks registered for the Agent tool,
- * plus nudge scheduling and activity tracking helpers.
+ * Contains the execute callbacks registered for the Agent tool.
+ * Spawn coordination, nudge scheduling, and live-view tracking have moved
+ * to spawn-coordinator.ts. buildAgentDetails stays here as a pure helper.
  */
 
 import type { ExtensionContext, ToolCallEvent } from "@earendil-works/pi-coding-agent";
 
-import type { AgentRecord } from "./types.js";
-import { SHORT_ID_LENGTH } from "./types.js";
-import type { SpawnOptions as AgentManagerSpawnOptions } from "./agent-manager.js";
-import type { AgentActivity } from "./ui/agent-widget.js";
+import type { AgentRecord } from "../types.js";
+import { SHORT_ID_LENGTH } from "../types.js";
 import { resolveType, getAgentConfig, discoverNewAgents } from "./agent-types.js";
-import { resolveModel } from "./model-precedence.js";
-import { addUsage, getLifetimeTotal, getSessionContextPercent, type LifetimeUsage } from "./usage.js";
-import { validateWorktreePath } from "./worktree-validator.js";
+import { getLifetimeTotal, getSessionContextPercent } from "./usage.js";
+import { validateWorktreePath } from "../spawn/worktree-validator.js";
 
-// Shared state imported from state.ts
-import { parseModelKey, findModelInRegistry, parseThinkingLevel } from "./utils.js";
+import { parseModelKey, findModelInRegistry, parseThinkingLevel } from "../utils.js";
 import {
-  __config,
-  sessionOverrides,
-  piInstance,
-  agentActivity,
+  getPiInstance,
+  getSessionCtx,
+  getStore,
+  getCoordinator,
   getManager,
-  getWidget,
-  sessionCtx,
-} from "./state.js";
-
-// ============================================================================
-// Module-level state
-// ============================================================================
-
-/** Agent IDs that were spawned as background — only these trigger a nudge on completion. */
-export const backgroundAgentIds = new Set<string>();
-
-const pendingNudges = new Set<string>();
-let nudgeTimer: ReturnType<typeof setTimeout> | null = null;
-
-/** Batch delay for nudges — only emit one update per batch window (ms). */
-const NUDGE_DELAY_MS = 200;
+} from "../shell.js";
 
 // ============================================================================
 // Tool result helpers
 // ============================================================================
 
 /** Shortcut for a successful tool result. */
-export function successResult(text: string, details?: Record<string, unknown>) {
+function successResult(text: string, details?: Record<string, unknown>) {
   return { content: [{ type: "text", text }], details };
 }
 
 /** Shortcut for an error tool result. */
-export function errorResult(text: string, details?: Record<string, unknown>) {
+function errorResult(text: string, details?: Record<string, unknown>) {
   return { content: [{ type: "text", text }], isError: true as const, details };
 }
 
@@ -59,67 +42,6 @@ export function errorResult(text: string, details?: Record<string, unknown>) {
 // Activity tracking
 // ============================================================================
 
-/**
- * Create an AgentActivity state and spawn callbacks for tracking tool usage.
- * Used by both foreground and background paths to avoid duplication.
- * Exported for use by the menu spawn flow.
- */
-export function createActivityTracker(maxTurns?: number, onStreamUpdate?: () => void) {
-  const state: AgentActivity = {
-    activeTools: new Map(),
-    toolUses: 0,
-    turnCount: 1,
-    maxTurns,
-    responseText: "",
-    session: undefined,
-    lifetimeUsage: { input: 0, output: 0, cacheWrite: 0, cost: 0 },
-  };
-
-  const callbacks = {
-    onToolActivity: (activity: { type: "start" | "end"; toolName: string }) => {
-      if (activity.type === "start") {
-        state.activeTools.set(`${activity.toolName}_${Date.now()}`, activity.toolName);
-      } else {
-        for (const [key, name] of state.activeTools) {
-          if (name === activity.toolName) { state.activeTools.delete(key); break; }
-        }
-        state.toolUses++;
-      }
-      onStreamUpdate?.();
-    },
-    onTextDelta: (_delta: string, fullText: string) => {
-      state.responseText = fullText;
-      onStreamUpdate?.();
-    },
-    onTurnEnd: (turnCount: number) => {
-      state.turnCount = turnCount;
-      onStreamUpdate?.();
-    },
-    onSessionCreated: (session: unknown) => {
-      state.session = session as Parameters<typeof getSessionContextPercent>[0];
-    },
-    onAssistantUsage: (usage: LifetimeUsage) => {
-      addUsage(state.lifetimeUsage, usage);
-      onStreamUpdate?.();
-    },
-  };
-
-  return { state, callbacks };
-}
-
-// ============================================================================
-// buildAgentDetails — consolidated stats/details construction
-// ============================================================================
-
-interface AgentDetailsOptions {
-  /** Include full stats (turns, tokens, context%, compactions, cost). Default: false. */
-  includeStats?: boolean;
-  /** Include status and outputFile. Default: false. */
-  includeStatus?: boolean;
-  /** Override the turnCount (e.g. from activity tracker). Default: record.turnCount. */
-  turnCount?: number;
-}
-
 /**
  * Build a details Record from an AgentRecord, controlled by options.
  *
@@ -130,6 +52,13 @@ interface AgentDetailsOptions {
  * Consolidates the identical field-selection logic previously duplicated
  * across emitIndividualNudge, executeSpawnForeground, and executeSpawnBackground.
  */
+interface AgentDetailsOptions {
+  /** Include full stats (turns, tokens, context%, compactions, cost). Default: false. */
+  includeStats?: boolean;
+  /** Include status and outputFile. Default: false. */
+  includeStatus?: boolean;
+}
+
 export function buildAgentDetails(
   record: AgentRecord,
   options?: AgentDetailsOptions,
@@ -149,13 +78,13 @@ export function buildAgentDetails(
   }
 
   if (options?.includeStats) {
-    const totalTokens = getLifetimeTotal(record.stats.lifetimeUsage);
     const elapsedMs = record.lifecycle.completedAt ? record.lifecycle.completedAt - record.lifecycle.startedAt : 0;
 
-    details.turnCount = options.turnCount ?? record.stats.turnCount;
+    details.turnCount = record.stats.turnCount;
     details.maxTurns = record.stats.maxTurns;
     details.toolUses = record.stats.toolUses;
-    details.tokens = totalTokens;
+    details.input = record.stats.lifetimeUsage.input;
+    details.output = record.stats.lifetimeUsage.output;
     details.contextPercent = getSessionContextPercent(record.execution.session);
     details.durationMs = elapsedMs;
     details.compactions = record.stats.compactionCount;
@@ -166,49 +95,6 @@ export function buildAgentDetails(
   return details;
 }
 
-// ============================================================================
-// Nudge scheduling — batch completion notifications within the hold window
-// ============================================================================
-
-export function scheduleNudge(agentId: string): void {
-  pendingNudges.add(agentId);
-
-  if (nudgeTimer) return;
-
-  nudgeTimer = setTimeout(() => {
-    nudgeTimer = null;
-    const batch = [...pendingNudges];
-    pendingNudges.clear();
-
-    for (const id of batch) {
-      emitIndividualNudge(id, getManager()?.getRecord(id));
-    }
-  }, NUDGE_DELAY_MS);
-}
-
-function emitIndividualNudge(agentId: string, record?: AgentRecord): void {
-  if (!record) return;
-
-  const details = buildAgentDetails(record, {
-    includeStats: true,
-    includeStatus: true,
-    turnCount: record.stats.turnCount ?? agentActivity.get(agentId)?.turnCount,
-  });
-
-  piInstance.sendMessage(
-    {
-      customType: "subagent-result",
-      content: `[Subagent "${record.display.type}" ${record.lifecycle.status}]\n\n${record.result ?? ""}`,
-      details,
-      display: true,
-    },
-    {
-      deliverAs: "steer",
-      triggerTurn: true,
-    },
-  );
-}
-
 // ============================================================================
 // Tool execute handlers
 // ============================================================================
@@ -226,8 +112,8 @@ export async function executeAgentTool(
   let worktreeLabel: string | undefined;
   if (rawWorktreePath && rawWorktreePath.trim() !== "") {
     try {
-      const parentCwd = sessionCtx?.cwd ?? ctx.cwd;
-      const validation = await validateWorktreePath(piInstance, rawWorktreePath, parentCwd);
+      const parentCwd = getSessionCtx()?.cwd ?? ctx.cwd;
+      const validation = await validateWorktreePath(getPiInstance(), rawWorktreePath, parentCwd);
       if (!validation.ok) {
         return errorResult(validation.error);
       }
@@ -253,7 +139,7 @@ export async function executeAgentTool(
   }
 
   const prompt = params.prompt as string;
-  const description = params.description as string;
+  const description = (params.description as string | undefined) || prompt.split("\n")[0].slice(0, 80) || prompt.slice(0, 80);
   const runInBackground = params.run_in_background as boolean | undefined;
   const maxTurns = params.max_turns as number | undefined ?? getAgentConfig(resolvedType)?.maxTurns;
 
@@ -266,90 +152,44 @@ export async function executeAgentTool(
 
   // Resolve thinking: explicit param > agent config (frontmatter) > undefined (inherit)
   const thinkingLevel = parseThinkingLevel(params.thinking as string | undefined)
-    ?? getAgentConfig(resolvedType)?.thinking;
+    ?? getAgentConfig(resolvedType)?.thinkingLevel;
 
-  const spawnOptions: AgentManagerSpawnOptions = {
+  // Use SpawnCoordinator for unified spawn path
+  const coordinator = getCoordinator()!;
+  const result = await coordinator.spawn(getPiInstance(), ctx, {
+    type: resolvedType,
+    prompt,
     description,
     model,
+    modelKey,
     maxTurns,
     thinkingLevel,
-    modelKey,
-    invocation: { modelName },
-    graceTurns: __config.agent.graceTurns,
+    graceTurns: getStore().agent.graceTurns,
     worktreePath: validatedWorktreePath,
     worktreeLabel,
-  };
-
-  if (runInBackground || __config.agent.forceBackground) {
-    return executeSpawnBackground(resolvedType, prompt, ctx, spawnOptions);
-  }
-
-  return executeSpawnForeground(resolvedType, prompt, ctx, spawnOptions);
-}
-
-async function executeSpawnBackground(
-  resolvedType: string,
-  prompt: string,
-  ctx: ExtensionContext,
-  spawnOptions: AgentManagerSpawnOptions,
-): Promise<any> {
-  const { state, callbacks } = createActivityTracker(
-    spawnOptions.maxTurns,
-  );
-
-  const agentId = getManager().spawn(piInstance, ctx, resolvedType, prompt, {
-    ...spawnOptions,
-    isBackground: true,
-    ...callbacks,
-  });
-  backgroundAgentIds.add(agentId);
-  agentActivity.set(agentId, state);
-  getWidget()?.ensureTimer();
-  getWidget()?.update();
-
-  const record = getManager().getRecord(agentId)!;
-  const details = buildAgentDetails(record);
-  const suffix = `A notification will arrive when done - User asks you not to poll, check status or duplicate the delegated work.\n\nAgent ID: ${agentId}`;
-  const label = record.lifecycle.status === "queued" ? "Agent queued" : "Agent running";
-
-  return successResult(`[${label}] ${suffix}`, details);
-}
-
-async function executeSpawnForeground(
-  resolvedType: string,
-  prompt: string,
-  ctx: ExtensionContext,
-  spawnOptions: AgentManagerSpawnOptions,
-): Promise<any> {
-  const { state: fgState, callbacks: fgCallbacks } = createActivityTracker(
-    spawnOptions.maxTurns,
-  );
-
-  const fgId = getManager().spawn(piInstance, ctx, resolvedType, prompt, {
-    ...spawnOptions,
-    ...fgCallbacks,
-    isBackground: false,
+    invocation: { modelName },
+    runInBackground: runInBackground || getStore().agent.forceBackground,
   });
-  agentActivity.set(fgId, fgState);
-  getWidget()?.ensureTimer();
 
-  const record = getManager().getRecord(fgId)!;
-  await record.execution.promise;
+  const { agentId, record } = result;
 
-  agentActivity.delete(fgId);
-  getWidget()?.markFinished(fgId);
-  getWidget()?.update();
+  if (runInBackground || getStore().agent.forceBackground) {
+    // Background: return immediately
+    const suffix = `A notification will arrive when done - User asks you not to poll, check status or duplicate the delegated work.\n\nAgent ID: ${agentId}`;
+    const label = record.lifecycle.status === "queued" ? "Agent queued" : "Agent running";
+    const details = buildAgentDetails(record);
+    return successResult(`[${label}] ${suffix}`, details);
+  }
 
-  const stats = buildAgentDetails(record, {
-    includeStats: true,
-    turnCount: fgState.turnCount,
-  });
+  // Foreground: record.execution.promise is already awaited by coordinator.spawn()
+  const details = buildAgentDetails(record, { includeStats: true });
 
   if (record.lifecycle.status === "error") {
-    return errorResult(`Agent failed: ${record.error || "unknown error"}`, stats);
+    return errorResult(`Agent failed: ${record.error || "unknown error"}`, details);
   }
 
-  return successResult(record.result ?? "", stats);
+  const statusNote = getStatusNote(record.lifecycle.status);
+  return successResult((record.result ?? "") + statusNote, details);
 }
 
 // ============================================================================
@@ -361,7 +201,7 @@ async function executeSpawnForeground(
  * Format: "type·short_id, type·short_id" — one line, easy for LLM to parse.
  */
 function formatRunningAgents(): string {
-  const agents = getManager().listAgents().filter(
+  const agents = getManager()!.listAgents().filter(
     (a) => a.lifecycle.status === "running" || a.lifecycle.status === "queued",
   );
 
@@ -389,7 +229,7 @@ export async function executeStopAgentTool(
     return errorResult("agent_id is required");
   }
 
-  const record = getManager().getRecord(agentId);
+  const record = getManager()!.getRecord(agentId);
 
   if (!record) {
     // Agent not found → return error + list of running agents
@@ -406,7 +246,7 @@ export async function executeStopAgentTool(
   }
 
   // Attempt to stop the running/queued agent
-  if (getManager().abort(agentId)) {
+  if (getManager()!.abort(agentId)) {
     return successResult(`Stopped agent ${agentId.slice(0, SHORT_ID_LENGTH)}`);
   }
 
@@ -429,13 +269,11 @@ export async function toolCallListener(
 
   const parentModelId = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "";
 
-  const effectiveModel = resolveModel({
-    subagentType: subagentType ?? "general-purpose",
-    agentConfig,
-    config: __config,
+  const effectiveModel = getStore().modelFor(
+    subagentType ?? "general-purpose",
     parentModelId,
-    sessionOverrides,
-  });
+    agentConfig,
+  );
 
   if (effectiveModel) {
     input.model = effectiveModel;
@@ -447,7 +285,7 @@ export async function toolCallListener(
   }
 
   // Inject thinking from agent config if not explicitly passed
-  if (input.thinking === undefined && agentConfig?.thinking !== undefined) {
-    input.thinking = agentConfig.thinking;
+  if (input.thinking === undefined && agentConfig?.thinkingLevel !== undefined) {
+    input.thinking = agentConfig.thinkingLevel;
   }
 }

package/src/agents/types.ts

@@ -0,0 +1,54 @@
+import type { ThinkingLevel } from "../types.js";
+
+/** Agent type: any string name (built-in defaults or user-defined). */
+export type SubagentType = string;
+
+/** How the subagent system prompt is constructed. */
+export type SystemPromptMode = "replace" | "inherit" | "custom";
+
+/** Unified agent configuration — used for both default and user-defined agents. */
+export interface AgentConfig {
+  name: string;
+  displayName?: string;
+  description: string;
+  /** Tools to register with the session (controls availability, not LLM visibility). */
+  registeredTools?: string[];
+  /**
+   * Controls which tool schemas the LLM sees. Can reference built-in tools
+   * and extension tools. true = all, string[] = listed, false = none.
+   * Supports ext/* syntax to include all tools from an extension.
+   * Mutually exclusive with excludeTools.
+   */
+  tools?: true | string[] | false;
+  /** Tool blacklist — all tools except these are visible. Mutually exclusive with tools (when tools is string[]). */
+  excludeTools?: string[];
+  /** true = inherit all, string[] = only listed, false = none. undefined = not set (uses global default). Mutually exclusive with excludeExtensions. */
+  extensions?: true | string[] | false;
+  /** Extension blacklist — all extensions except these load. Mutually exclusive with extensions (when extensions is string[]). */
+  excludeExtensions?: string[];
+  /** Whitelist of allowed skills (metadata only in system prompt). true = all, string[] = listed, false = none. undefined = not set (uses global default). */
+  skills?: true | string[] | false;
+  /** Skills to preload with full content into system prompt. string[] = listed, false/undefined = none */
+  preloadSkills?: string[] | false;
+  model?: string;
+  thinkingLevel?: ThinkingLevel;
+  maxTurns?: number;
+  /** Max output tokens per LLM response. Passed to provider as max_tokens or max_completion_tokens. */
+  maxTokens?: number;
+  systemPrompt: string;
+
+  /** true = this is an embedded default agent (informational) */
+  isDefault?: boolean;
+  /** true = agent is hidden from the schema enum but can still be called by name. */
+  hidden?: boolean;
+  /** Where this agent was loaded from */
+  source?: "project" | "global";
+}
+
+export interface AgentInvocation {
+  /** Short display name, e.g. "haiku" — only set when different from parent. */
+  modelName?: string;
+  thinkingLevel?: ThinkingLevel;
+  maxTurns?: number;
+  runInBackground?: boolean;
+}

package/src/{usage.ts → agents/usage.ts}

@@ -36,6 +36,13 @@ export function formatTokens(count: number): string {
   return `${count}`;
 }
 
+/** Format token count for widget display: rounded to whole number for k. */
+export function formatTokensCompact(count: number): string {
+  if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
+  if (count >= 1_000) return `${Math.round(count / 1_000)}k`;
+  return `${count}`;
+}
+
 /** Format cost as a dollar amount: "$0.00", "$0.01", "$1.23". */
 export function formatCost(cost: number): string {
   return `$${cost.toFixed(2)}`;

package/src/{config-io.ts → config/config-io.ts}

@@ -7,26 +7,43 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { SubagentsConfig } from "./model-precedence.js";
+import type { SubagentsConfig } from "../models/model-precedence.js";
 
 const CONFIG_DIR = path.join(process.env.HOME || "", ".pi", "agent");
 const CONFIG_PATH = path.join(CONFIG_DIR, "subagents-lite.json");
 
+/** Default number of grace turns before an agent is force-stopped. */
+export const DEFAULT_GRACE_TURNS = 6;
+
 /** Default configuration — used when config file doesn't exist or is invalid. */
 export const DEFAULT_CONFIG: SubagentsConfig = {
   agent: {
     default: null,
     forceBackground: false,
-    graceTurns: 6,
+    graceTurns: DEFAULT_GRACE_TURNS,
     widgetMaxLines: 12,
     // widgetMaxLinesCompact intentionally omitted — derives from widgetMaxLines
+    widgetDescLengthFull: 50,
+    widgetDescLengthCompact: 30,
     widgetCompact: false,
     widgetShortcut: false,
+    systemPromptMode: "replace",
+    includeContextFiles: true,
+    disableDefaultAgents: false,
+    showTools: true,
+    showTurns: true,
+    showInput: true,
+    showOutput: true,
+    showContext: true,
+    showCost: false,
+    showTime: true,
   },
   concurrency: { default: 4 },
 };
 
-/** Read config from disk. Returns defaults if file doesn't exist or is invalid. */
+/**
+ * Read config from disk. Returns defaults if file doesn't exist or is invalid.
+ */
 export function loadConfig(): SubagentsConfig {
   try {
     const raw = fs.readFileSync(CONFIG_PATH, "utf-8");