pi-subagents-lite 1.0.2 → 1.2.0

package/src/tool-execution.ts

@@ -8,22 +8,25 @@
 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 { 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";
 
-// Shared state imported from index.ts
+// Shared state imported from state.ts
 import { parseModelKey, findModelInRegistry, parseThinkingLevel } from "./utils.js";
 import {
   __config,
   sessionOverrides,
-  manager,
   piInstance,
   agentActivity,
-  widget,
-} from "./index.js";
+  getManager,
+  getWidget,
+  sessionCtx,
+} from "./state.js";
 
 // ============================================================================
 // Module-level state
@@ -59,8 +62,9 @@ export function errorResult(text: string, details?: Record<string, unknown>) {
 /**
  * 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.
  */
-function createActivityTracker(maxTurns?: number, onStreamUpdate?: () => void) {
+export function createActivityTracker(maxTurns?: number, onStreamUpdate?: () => void) {
   const state: AgentActivity = {
     activeTools: new Map(),
     toolUses: 0,
@@ -103,6 +107,65 @@ function createActivityTracker(maxTurns?: number, onStreamUpdate?: () => void) {
   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.
+ *
+ * Always includes `type` and `description`. Optional groups:
+ * - `includeStatus`: adds `status`, `outputFile`
+ * - `includeStats`: adds turn/token/cost/context/compaction/model fields
+ *
+ * Consolidates the identical field-selection logic previously duplicated
+ * across emitIndividualNudge, executeSpawnForeground, and executeSpawnBackground.
+ */
+export function buildAgentDetails(
+  record: AgentRecord,
+  options?: AgentDetailsOptions,
+): Record<string, unknown> {
+  const details: Record<string, unknown> = {
+    type: record.display.type,
+    description: record.display.description,
+  };
+
+  if (record.display.worktreePath) {
+    details.worktreePath = record.display.worktreePath;
+  }
+
+  if (options?.includeStatus) {
+    details.status = record.lifecycle.status;
+    details.outputFile = record.display.outputFile;
+  }
+
+  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.maxTurns = record.stats.maxTurns;
+    details.toolUses = record.stats.toolUses;
+    details.tokens = totalTokens;
+    details.contextPercent = getSessionContextPercent(record.execution.session);
+    details.durationMs = elapsedMs;
+    details.compactions = record.stats.compactionCount;
+    details.modelName = record.display.invocation?.modelName;
+    details.cost = record.stats.lifetimeUsage.cost;
+  }
+
+  return details;
+}
+
 // ============================================================================
 // Nudge scheduling — batch completion notifications within the hold window
 // ============================================================================
@@ -118,7 +181,7 @@ export function scheduleNudge(agentId: string): void {
     pendingNudges.clear();
 
     for (const id of batch) {
-      emitIndividualNudge(id, manager?.getRecord(id));
+      emitIndividualNudge(id, getManager()?.getRecord(id));
     }
   }, NUDGE_DELAY_MS);
 }
@@ -126,31 +189,16 @@ export function scheduleNudge(agentId: string): void {
 function emitIndividualNudge(agentId: string, record?: AgentRecord): void {
   if (!record) return;
 
-  const totalTokens = getLifetimeTotal(record.lifetimeUsage);
-  const elapsedMs = record.completedAt
-    ? record.completedAt - record.startedAt
-    : 0;
-
-  const details: Record<string, unknown> = {
-    type: record.type,
-    description: record.description,
-    status: record.status,
-    outputFile: record.outputFile,
-    turnCount: record.turnCount ?? agentActivity.get(agentId)?.turnCount,
-    maxTurns: record.maxTurns,
-    toolUses: record.toolUses,
-    tokens: totalTokens,
-    cost: record.lifetimeUsage.cost,
-    contextPercent: getSessionContextPercent(record.session),
-    durationMs: elapsedMs,
-    compactions: record.compactionCount,
-    modelName: record.invocation?.modelName,
-  };
+  const details = buildAgentDetails(record, {
+    includeStats: true,
+    includeStatus: true,
+    turnCount: record.stats.turnCount ?? agentActivity.get(agentId)?.turnCount,
+  });
 
   piInstance.sendMessage(
     {
       customType: "subagent-result",
-      content: `[Subagent "${record.type}" completed]\n\n${record.result ?? ""}`,
+      content: `[Subagent "${record.display.type}" ${record.lifecycle.status}]\n\n${record.result ?? ""}`,
       details,
       display: true,
     },
@@ -172,11 +220,32 @@ export async function executeAgentTool(
   _onUpdate: ((update: any) => void) | undefined,
   ctx: ExtensionContext,
 ): Promise<any> {
+  // Validate worktree_path early — needed for on-demand agent discovery
+  const rawWorktreePath = params.worktree_path as string | undefined;
+  let validatedWorktreePath: string | undefined;
+  let worktreeLabel: string | undefined;
+  if (rawWorktreePath && rawWorktreePath.trim() !== "") {
+    try {
+      const parentCwd = sessionCtx?.cwd ?? ctx.cwd;
+      const validation = await validateWorktreePath(piInstance, rawWorktreePath, parentCwd);
+      if (!validation.ok) {
+        return errorResult(validation.error);
+      }
+      validatedWorktreePath = validation.resolvedPath;
+      worktreeLabel = validation.label;
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return errorResult(`worktree_path validation failed: ${msg}`);
+    }
+  }
+
   const type = (params.agent as string) || "general-purpose";
   let resolvedType = resolveType(type);
   if (!resolvedType) {
-    // Not found in registry — try scanning filesystem for agents added during the session
-    await discoverNewAgents();
+    // Not found in registry — try scanning filesystem for agents added during the session.
+    // When worktree_path is set, also scan the worktree's .pi/agents/ directory.
+    const worktreeDir = validatedWorktreePath ? `${validatedWorktreePath}/.pi/agents` : undefined;
+    await discoverNewAgents(worktreeDir);
     resolvedType = resolveType(type);
   }
   if (!resolvedType) {
@@ -187,6 +256,7 @@ export async function executeAgentTool(
   const description = params.description as string;
   const runInBackground = params.run_in_background as boolean | undefined;
   const maxTurns = params.max_turns as number | undefined ?? getAgentConfig(resolvedType)?.maxTurns;
+
   const modelStr = params.model as string | undefined;
   const model = findModelInRegistry(modelStr, ctx.modelRegistry, ctx.model);
   const modelKey = model ? `${model.provider}/${model.id}` : undefined;
@@ -206,6 +276,8 @@ export async function executeAgentTool(
     modelKey,
     invocation: { modelName },
     graceTurns: __config.agent.graceTurns,
+    worktreePath: validatedWorktreePath,
+    worktreeLabel,
   };
 
   if (runInBackground || __config.agent.forceBackground) {
@@ -225,20 +297,20 @@ async function executeSpawnBackground(
     spawnOptions.maxTurns,
   );
 
-  const agentId = manager.spawn(piInstance, ctx, resolvedType, prompt, {
+  const agentId = getManager().spawn(piInstance, ctx, resolvedType, prompt, {
     ...spawnOptions,
     isBackground: true,
     ...callbacks,
   });
   backgroundAgentIds.add(agentId);
   agentActivity.set(agentId, state);
-  widget?.ensureTimer();
-  widget?.update();
+  getWidget()?.ensureTimer();
+  getWidget()?.update();
 
-  const record = manager.getRecord(agentId)!;
-  const details: Record<string, unknown> = { type: resolvedType, description: spawnOptions.description };
+  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.status === "queued" ? "Agent queued" : "Agent running";
+  const label = record.lifecycle.status === "queued" ? "Agent queued" : "Agent running";
 
   return successResult(`[${label}] ${suffix}`, details);
 }
@@ -253,37 +325,27 @@ async function executeSpawnForeground(
     spawnOptions.maxTurns,
   );
 
-  const fgId = manager.spawn(piInstance, ctx, resolvedType, prompt, {
+  const fgId = getManager().spawn(piInstance, ctx, resolvedType, prompt, {
     ...spawnOptions,
     ...fgCallbacks,
     isBackground: false,
   });
   agentActivity.set(fgId, fgState);
-  widget?.ensureTimer();
+  getWidget()?.ensureTimer();
 
-  const record = manager.getRecord(fgId)!;
-  await record.promise;
+  const record = getManager().getRecord(fgId)!;
+  await record.execution.promise;
 
   agentActivity.delete(fgId);
-  widget?.markFinished(fgId);
-  widget?.update();
+  getWidget()?.markFinished(fgId);
+  getWidget()?.update();
 
-  const elapsedMs = (record.completedAt ?? Date.now()) - record.startedAt;
-  const totalTokens = getLifetimeTotal(record.lifetimeUsage);
-  const stats: Record<string, unknown> = {
-    type: resolvedType,
+  const stats = buildAgentDetails(record, {
+    includeStats: true,
     turnCount: fgState.turnCount,
-    maxTurns: fgState.maxTurns,
-    toolUses: record.toolUses,
-    tokens: totalTokens,
-    contextPercent: getSessionContextPercent(fgState.session),
-    durationMs: elapsedMs,
-    description: spawnOptions.description,
-    compactions: record.compactionCount,
-    modelName: record.invocation?.modelName,
-  };
+  });
 
-  if (record.status === "error") {
+  if (record.lifecycle.status === "error") {
     return errorResult(`Agent failed: ${record.error || "unknown error"}`, stats);
   }
 
@@ -291,8 +353,69 @@ async function executeSpawnForeground(
 }
 
 // ============================================================================
-// Tool_call listener — inject model into Agent tool calls
+// Running agents list helper (used by executeStopAgentTool)
+// ============================================================================
+
+/**
+ * Build a compact list of running (or queued) agents.
+ * Format: "type·short_id, type·short_id" — one line, easy for LLM to parse.
+ */
+function formatRunningAgents(): string {
+  const agents = getManager().listAgents().filter(
+    (a) => a.lifecycle.status === "running" || a.lifecycle.status === "queued",
+  );
+
+  if (agents.length === 0) return "none";
+
+  return agents
+    .map((a) => `${a.display.type}·${a.id.slice(0, SHORT_ID_LENGTH)}`)
+    .join(", ");
+}
+
 // ============================================================================
+// StopAgent execute handler
+// ============================================================================
+
+export async function executeStopAgentTool(
+  _toolCallId: string,
+  params: Record<string, unknown>,
+  _signal: AbortSignal | undefined,
+  _onUpdate: ((update: any) => void) | undefined,
+  _ctx: ExtensionContext,
+): Promise<any> {
+  const agentId = params.agent_id as string | undefined;
+
+  if (!agentId) {
+    return errorResult("agent_id is required");
+  }
+
+  const record = getManager().getRecord(agentId);
+
+  if (!record) {
+    // Agent not found → return error + list of running agents
+    return errorResult(
+      `Agent ${agentId} not found. Running agents: ${formatRunningAgents()}`,
+    );
+  }
+
+  // Check if already in a terminal state (not running or queued)
+  if (record.lifecycle.status !== "running" && record.lifecycle.status !== "queued") {
+    return successResult(
+      `Agent ${agentId} is already ${record.lifecycle.status}. Running agents: ${formatRunningAgents()}`,
+    );
+  }
+
+  // Attempt to stop the running/queued agent
+  if (getManager().abort(agentId)) {
+    return successResult(`Stopped agent ${agentId.slice(0, SHORT_ID_LENGTH)}`);
+  }
+
+  return errorResult(`Failed to stop agent ${agentId}`);
+}
+
+// ============================================================================
+// Tool_call listener — inject model into Agent tool calls
+// =============================================================================
 
 export async function toolCallListener(
   event: ToolCallEvent,

package/src/types.ts

@@ -50,39 +50,16 @@ export interface AgentConfig {
 
 export interface AgentRecord {
   id: string;
-  type: SubagentType;
-  description: string;
-  status: "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error";
   result?: string;
   error?: string;
-  toolUses: number;
-  startedAt: number;
-  completedAt?: number;
-  session?: AgentSession;
-  abortController?: AbortController;
-  promise?: Promise<string>;
-  /** Steering messages queued before the session was ready. */
-  pendingSteers?: string[];
-  /** The tool_use_id from the original Agent tool call. */
-  toolCallId?: string;
-  /** Path to the streaming output transcript file. */
-  outputFile?: string;
-  /** Cleanup function for the output file stream subscription. */
-  outputCleanup?: () => void;
-  /**
-   * Lifetime usage breakdown, accumulated via `message_end` events. Survives
-   * compaction. Total = input + output + cacheWrite + cost (cacheRead deliberately
-   * excluded — see issue #38). Initialized to zeros at spawn.
-   */
-  lifetimeUsage: LifetimeUsage;
-  /** Final turn count (set on completion). Used by widget after activity cleanup. */
-  turnCount?: number;
-  /** Max turns limit (from invocation or default). */
-  maxTurns?: number;
-  /** Number of times this agent's session has compacted. Initialized to 0 at spawn. */
-  compactionCount: number;
-  /** Resolved spawn params, captured for UI display. Fixed at spawn time. */
-  invocation?: AgentInvocation;
+  /** Lifecycle state: status, timestamps. */
+  lifecycle: AgentLifecycle;
+  /** Display-oriented info: type, description, output file, invocation. */
+  display: AgentDisplayInfo;
+  /** Execution internals: session, abort controller, pending steers. */
+  execution: AgentExecutionState;
+  /** Accumulated statistics: usage, tool uses, turns. */
+  stats: AgentAccumulatedStats;
 }
 
 export interface AgentInvocation {
@@ -102,6 +79,30 @@ export interface EnvInfo {
 /** How many characters of agent ID to show in display. */
 export const SHORT_ID_LENGTH = 8;
 
+/**
+ * Theme for terminal rendering — used by format.ts, renderer.ts, and UI widgets.
+ * Defined here (not in ui/agent-widget.ts) so non-UI modules can import it
+ * without depending on the UI layer.
+ */
+export type Theme = {
+  fg(color: string, text: string): string;
+  bg(color: string, text: string): string;
+  bold(text: string): string;
+  italic?: (text: string) => string;
+};
+
+/** Non-model keys in config.agent — preserved when clearing all overrides. */
+export const CONFIG_AGENT_NON_MODEL_KEYS = [
+  "default",
+  "forceBackground",
+  "graceTurns",
+  "showCost",
+  "widgetMaxLines",
+  "widgetMaxLinesCompact",
+  "widgetCompact",
+  "widgetShortcut",
+];
+
 /** Reason for a context compaction event. */
 export type CompactionReason = "manual" | "threshold" | "overflow";
 
@@ -111,4 +112,76 @@ export interface CompactionInfo {
   tokensBefore: number;
 }
 
+// ---------------------------------------------------------------------------
+// Sub-object interfaces for decomposed AgentRecord
+// ---------------------------------------------------------------------------
+
+/** Possible agent lifecycle statuses. */
+export type AgentStatus = "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error";
+
+/**
+ * Lifecycle state: when the agent started, completed, and its current status.
+ * Used by agent-manager (lifecycle control), menus (status display), widget (linger logic).
+ */
+export interface AgentLifecycle {
+  status: AgentStatus;
+  startedAt: number;
+  completedAt?: number;
+}
+
+/**
+ * Display-oriented fields: type name, description, output file, invocation params.
+ * Used by widget (rendering), menus (listing), renderer (display).
+ */
+export interface AgentDisplayInfo {
+  type: SubagentType;
+  description: string;
+  /** Path to the streaming output transcript file. */
+  outputFile?: string;
+  /** Resolved spawn params, captured for UI display. Fixed at spawn time. */
+  invocation?: AgentInvocation;
+  /** The tool_use_id from the original Agent tool call. */
+  toolCallId?: string;
+  /** Resolved absolute path of the worktree this agent is running in. */
+  worktreePath?: string;
+  /** Short display label for the worktree (e.g., "feature" or "feature/packages/web"). */
+  worktreeLabel?: string;
+}
+
+/**
+ * Execution internals: session handle, abort controller, pending steers.
+ * Used by agent-manager (session lifecycle), tool-execution (steering, nudge).
+ */
+export interface AgentExecutionState {
+  session?: AgentSession;
+  abortController?: AbortController;
+  promise?: Promise<string>;
+  /** Steering messages queued before the session was ready. */
+  pendingSteers?: string[];
+  /** Cleanup function for the output file stream subscription. */
+  outputCleanup?: () => void;
+}
+
+/**
+ * Accumulated statistics: usage breakdown, tool uses, turn count.
+ * Used by widget (stats display), tool-execution (details building), menus (result viewer).
+ */
+export interface AgentAccumulatedStats {
+  /**
+   * Lifetime usage breakdown, accumulated via `message_end` events. Survives
+   * compaction. Total = input + output + cacheWrite + cost (cacheRead deliberately
+   * excluded — see issue #38). Initialized to zeros at spawn.
+   */
+  lifetimeUsage: LifetimeUsage;
+  toolUses: number;
+  /** Final turn count (set on completion). Used by widget after activity cleanup. */
+  turnCount?: number;
+  /** Max turns limit (from invocation or default). */
+  maxTurns?: number;
+  /** Number of times this agent's session has compacted. Initialized to 0 at spawn. */
+  compactionCount: number;
+  /** Last-known context usage percentage (0–100), captured at completion. */
+  contextPercent?: number | null;
+}
+