@nklisch/pi-enhanced 0.1.0

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/tools/agent-tool.ts

@@ -0,0 +1,247 @@
+/* eslint-disable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-base-to-string, @typescript-eslint/restrict-template-expressions -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
+import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "@sinclair/typebox";
+import { AgentTypeRegistry } from "#src/config/agent-types";
+import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import type { AgentSpawnConfig } from "#src/lifecycle/subagent-manager";
+import { spawnBackground } from "#src/tools/background-spawner";
+import { runForeground } from "#src/tools/foreground-runner";
+import { buildAgentGuidelines, buildDetails, buildTypeListText, textResult } from "#src/tools/helpers";
+import { renderAgentResult } from "#src/tools/result-renderer";
+import { type ModelInfo, resolveSpawnConfig } from "#src/tools/spawn-config";
+import type { ParentSessionInfo, Subagent } from "#src/types";
+import { type AgentDetails, getDisplayName } from "#src/ui/display";
+
+// ---- Deps interfaces ----
+
+/** Narrow manager interface — only the methods the Agent tool calls. */
+export interface AgentToolManager {
+	spawn: (snapshot: ParentSnapshot, type: string, prompt: string, opts: AgentSpawnConfig) => string;
+	spawnAndWait: (snapshot: ParentSnapshot, type: string, prompt: string, opts: Omit<AgentSpawnConfig, "isBackground">) => Promise<Subagent>;
+	resume: (id: string, prompt: string, signal: AbortSignal) => Promise<Subagent | undefined>;
+	getRecord: (id: string) => Subagent | undefined;
+}
+
+/** Narrow runtime interface — the Agent tool's slice of SubagentRuntime. */
+export interface AgentToolRuntime {
+	buildSnapshot(inheritContext: boolean): ParentSnapshot;
+	getModelInfo(): ModelInfo;
+	getSessionInfo(): { parentSessionFile: string; parentSessionId: string };
+}
+
+/** Narrow settings accessor — only the fields the Agent tool reads. */
+export type AgentToolSettings = {
+	readonly defaultMaxTurns: number | undefined;
+	readonly maxConcurrent: number;
+};
+
+// ---- Class ----
+
+export class AgentTool {
+	private readonly typeListText: string;
+	private readonly availableTypesText: string;
+	private readonly agentGuidelines: string[];
+
+	constructor(
+		private readonly manager: AgentToolManager,
+		private readonly runtime: AgentToolRuntime,
+		private readonly settings: AgentToolSettings,
+		private readonly registry: AgentTypeRegistry,
+		private readonly agentDir: string,
+	) {
+		this.typeListText = buildTypeListText(registry, agentDir);
+		this.availableTypesText = registry.getAvailableTypes().join(", ");
+		this.agentGuidelines = buildAgentGuidelines(registry);
+	}
+
+	async execute(
+		toolCallId: string,
+		params: Record<string, unknown>,
+		signal: AbortSignal | undefined,
+		onUpdate: ((update: AgentToolResult<any>) => void) | undefined,
+		_ctx: any,
+	) {
+		// Reload custom agents so new .pi/agents/*.md files are picked up without restart
+		this.registry.reload();
+
+		// ---- Config resolution (pure) ----
+		const config = resolveSpawnConfig(
+			params,
+			this.registry,
+			this.runtime.getModelInfo(),
+			this.settings,
+		);
+		if ("error" in config) return textResult(config.error);
+
+		// ---- Boundary extraction (after config so inheritContext is resolved) ----
+		const snapshot = this.runtime.buildSnapshot(config.execution.inheritContext);
+		const { parentSessionFile, parentSessionId } = this.runtime.getSessionInfo();
+		const parentSession: ParentSessionInfo = { parentSessionFile, parentSessionId, toolCallId };
+
+		// ---- Resume existing agent ----
+		if (params.resume) {
+			const existing = this.manager.getRecord(params.resume as string);
+			if (!existing) {
+				return textResult(
+					`Agent not found: "${params.resume}". It may have been cleaned up.`,
+				);
+			}
+			if (!existing.isSessionReady()) {
+				return textResult(
+					`Agent "${params.resume}" has no active session to resume.`,
+				);
+			}
+			const record = await this.manager.resume(
+				params.resume as string,
+				params.prompt as string,
+				signal ?? new AbortController().signal,
+			);
+			if (!record) {
+				return textResult(`Failed to resume agent "${params.resume}".`);
+			}
+			return textResult(
+				record.result?.trim() ?? record.error?.trim() ?? "No output.",
+				buildDetails(config.presentation.detailBase, record),
+			);
+		}
+
+		// ---- Background execution ----
+		if (config.execution.runInBackground) {
+			return spawnBackground(
+				this.manager,
+				{ config, snapshot, parentSession, settings: this.settings },
+			);
+		}
+
+		// ---- Foreground execution — stream progress via onUpdate ----
+		return runForeground(
+			this.manager,
+			{ config, snapshot, parentSession },
+			signal,
+			onUpdate,
+		);
+	}
+
+	toToolDefinition() {
+		const typeListText = this.typeListText;
+		const availableTypesText = this.availableTypesText;
+		const agentDir = this.agentDir;
+		const registry = this.registry;
+
+		const guidelines = [
+			"- For parallel work, use run_in_background: true on each agent. Foreground calls run sequentially — only one executes at a time.",
+			...this.agentGuidelines,
+			"- Provide clear, detailed prompts so the agent can work autonomously.",
+			"- Subagent results are returned as text — summarize them for the user.",
+			"- Use run_in_background for work you don't need immediately. You will be notified when it completes.",
+			"- Use resume with an agent ID to continue a previous agent's work.",
+			"- Use steer_subagent to send mid-run messages to a running background agent.",
+			'- Use model to specify a different model (as "provider/modelId", or fuzzy e.g. "haiku", "sonnet").',
+			"- Use thinking to control extended thinking level.",
+			"- Use inherit_context if the agent needs the parent conversation history.",
+		].join("\n");
+
+		return defineTool({
+			name: "subagent" as const,
+			label: "Subagent",
+			promptSnippet: "subagent: Launch a specialized agent for complex, multi-step tasks.",
+			description: `Launch a new agent to handle complex, multi-step tasks autonomously.
+
+The subagent tool launches specialized agents that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.
+
+Available agent types:
+${typeListText}
+
+Guidelines:
+${guidelines}
+`,
+			parameters: Type.Object({
+				prompt: Type.String({
+					description: "The task for the agent to perform.",
+				}),
+				description: Type.String({
+					description: "A short (3-5 word) description of the task (shown in UI).",
+				}),
+				subagent_type: Type.String({
+					description: `The type of specialized agent to use. Available types: ${availableTypesText}. Custom agents from .pi/agents/<name>.md (project) or ${agentDir}/agents/<name>.md (global) are also available.`,
+				}),
+				model: Type.Optional(
+					Type.String({
+						description:
+							'Optional model override. Accepts "provider/modelId" or fuzzy name (e.g. "haiku", "sonnet"). Omit to use the agent type\'s default.',
+					}),
+				),
+				thinking: Type.Optional(
+					Type.String({
+						description:
+							"Thinking level: off, minimal, low, medium, high, xhigh. Overrides agent default.",
+					}),
+				),
+				max_turns: Type.Optional(
+					Type.Number({
+						description:
+							"Maximum number of agentic turns before stopping. Omit for unlimited (default).",
+						minimum: 1,
+					}),
+				),
+				run_in_background: Type.Optional(
+					Type.Boolean({
+						description:
+							"Set to true to run in background. Returns agent ID immediately. You will be notified when it completes.",
+					}),
+				),
+				resume: Type.Optional(
+					Type.String({
+						description: "Optional agent ID to resume from. Continues from previous context.",
+					}),
+				),
+				inherit_context: Type.Optional(
+					Type.Boolean({
+						description:
+							"If true, fork parent conversation into the agent. Default: false (fresh context).",
+					}),
+				),
+			}),
+
+			// ---- Custom rendering: inline subagent results ----
+
+			renderCall(args: Record<string, unknown>, theme: any) {
+				const displayName = args.subagent_type
+					? getDisplayName(args.subagent_type as string, registry)
+					: "Subagent";
+				const desc = (args.description as string | undefined) ?? "";
+				return new Text(
+					"▸ " +
+						theme.fg("toolTitle", theme.bold(displayName)) +
+						(desc ? "  " + theme.fg("muted", desc) : ""),
+					0,
+					0,
+				);
+			},
+
+			renderResult(result: any, { expanded, isPartial }: any, theme: any) {
+				const details = result.details as AgentDetails | undefined;
+				if (!details) {
+					const text = result.content[0]?.type === "text" ? result.content[0].text : "";
+					return new Text(text, 0, 0);
+				}
+				const resultText = result.content[0]?.type === "text" ? result.content[0].text : "";
+				return new Text(
+					renderAgentResult(details, resultText, expanded, isPartial, theme),
+					0,
+					0,
+				);
+			},
+
+			execute: (
+				toolCallId: string,
+				params: Record<string, unknown>,
+				signal: AbortSignal | undefined,
+				onUpdate: ((update: AgentToolResult<any>) => void) | undefined,
+				ctx: any,
+			) => this.execute(toolCallId, params, signal, onUpdate, ctx),
+		});
+	}
+}

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/tools/background-spawner.ts

@@ -0,0 +1,72 @@
+import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import type { AgentSpawnConfig } from "#src/lifecycle/subagent-manager";
+import { textResult } from "#src/tools/helpers";
+import type { ResolvedSpawnConfig } from "#src/tools/spawn-config";
+import type { ParentSessionInfo, Subagent } from "#src/types";
+
+/** Narrow manager interface for the background spawner. */
+export interface BackgroundManagerDeps {
+  spawn(snapshot: ParentSnapshot, type: string, prompt: string, opts: AgentSpawnConfig): string;
+  getRecord(id: string): Subagent | undefined;
+}
+
+/** All values the background spawner needs beyond the resolved config. */
+export interface BackgroundParams {
+  config: ResolvedSpawnConfig;
+  snapshot: ParentSnapshot;
+  parentSession: ParentSessionInfo;
+  settings: { readonly maxConcurrent: number };
+}
+
+/**
+ * Spawn a background agent and return the tool result immediately.
+ * Owns: launch message formatting.
+ */
+export function spawnBackground(
+  manager: BackgroundManagerDeps,
+  params: BackgroundParams,
+) {
+  const { identity, execution, presentation } = params.config;
+
+  let id: string;
+  try {
+    id = manager.spawn(params.snapshot, identity.subagentType, execution.prompt, {
+      parentSession: params.parentSession,
+      description: execution.description,
+      model: execution.model,
+      maxTurns: execution.effectiveMaxTurns,
+      inheritContext: execution.inheritContext,
+      thinkingLevel: execution.thinking,
+      isBackground: true,
+      origin: "tool",
+      invocation: execution.agentInvocation,
+    });
+  } catch (err) {
+    return textResult(err instanceof Error ? err.message : String(err));
+  }
+
+  const record = manager.getRecord(id);
+
+  const isQueued = record?.status === "queued";
+  return textResult(
+    `Agent ${isQueued ? "queued" : "started"} in background.\n` +
+      `Agent ID: ${id}\n` +
+      `Type: ${identity.displayName}\n` +
+      `Description: ${execution.description}\n` +
+      (record?.outputFile ? `Output file: ${record.outputFile}\n` : "") +
+      (isQueued
+        ? `Position: queued (max ${params.settings.maxConcurrent} concurrent)\n`
+        : "") +
+      `\nYou will be notified when this agent completes.\n` +
+      `Use get_subagent_result to retrieve full results, or steer_subagent to send it messages.\n` +
+      `Do not duplicate this agent's work.`,
+    {
+      ...presentation.detailBase,
+      toolUses: 0,
+      tokens: "",
+      durationMs: 0,
+      status: "background" as const,
+      agentId: id,
+    },
+  );
+}

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/tools/foreground-runner.ts

@@ -0,0 +1,133 @@
+import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
+import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import type { AgentSpawnConfig } from "#src/lifecycle/subagent-manager";
+import {
+  buildDetails,
+  formatLifetimeTokens,
+  getStatusNote,
+  textResult,
+} from "#src/tools/helpers";
+import type { ResolvedSpawnConfig } from "#src/tools/spawn-config";
+import type { ParentSessionInfo, Subagent } from "#src/types";
+import {
+  type AgentDetails,
+  describeActivity,
+  formatMs,
+  SPINNER,
+} from "#src/ui/display";
+
+/** Narrow manager interface for the foreground runner. */
+export interface ForegroundManagerDeps {
+  spawnAndWait(
+    snapshot: ParentSnapshot,
+    type: string,
+    prompt: string,
+    opts: Omit<AgentSpawnConfig, "isBackground">,
+  ): Promise<Subagent>;
+}
+
+/** All values the foreground runner needs beyond the resolved config. */
+export interface ForegroundParams {
+  config: ResolvedSpawnConfig;
+  snapshot: ParentSnapshot;
+  parentSession: ParentSessionInfo;
+}
+
+/**
+ * Run an agent synchronously in the foreground, streaming spinner updates.
+ * Owns: spinner interval, streaming onUpdate callbacks, cleanup, and result formatting.
+ */
+export async function runForeground(
+  manager: ForegroundManagerDeps,
+  params: ForegroundParams,
+  signal: AbortSignal | undefined,
+  onUpdate: ((update: AgentToolResult<any>) => void) | undefined,
+) {
+  const { identity, execution, presentation } = params.config;
+  let spinnerFrame = 0;
+  const startedAt = Date.now();
+
+  let recordRef: Subagent | undefined;
+
+  const streamUpdate = () => {
+    const toolUses = recordRef?.toolUses ?? 0;
+    const details: AgentDetails = {
+      ...presentation.detailBase,
+      toolUses,
+      tokens: recordRef ? formatLifetimeTokens(recordRef) : "",
+      // Read activity off the record; fall back to safe defaults before onSessionCreated fires
+      turnCount: recordRef?.turnCount ?? 1,
+      maxTurns: recordRef?.maxTurns ?? execution.effectiveMaxTurns,
+      durationMs: Date.now() - startedAt,
+      status: "running",
+      activity: describeActivity(
+        recordRef?.activeTools ?? new Map(),
+        recordRef?.responseText ?? "",
+      ),
+      spinnerFrame: spinnerFrame % SPINNER.length,
+    };
+    onUpdate?.({
+      content: [{ type: "text", text: `${toolUses} tool uses...` }],
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- Pi SDK ToolCallUpdate details type is not exported
+      details: details as any,
+    });
+  };
+
+  // Animate spinner at ~80ms (smooth rotation through 10 braille frames)
+  const spinnerInterval = setInterval(() => {
+    spinnerFrame++;
+    streamUpdate();
+  }, 80);
+
+  streamUpdate();
+
+  let record: Subagent;
+  try {
+    record = await manager.spawnAndWait(
+      params.snapshot,
+      identity.subagentType,
+      execution.prompt,
+      {
+        description: execution.description,
+        model: execution.model,
+        maxTurns: execution.effectiveMaxTurns,
+        inheritContext: execution.inheritContext,
+        thinkingLevel: execution.thinking,
+        origin: "tool",
+        invocation: execution.agentInvocation,
+        signal,
+        parentSession: params.parentSession,
+        observer: {
+          onSessionCreated: (agent) => {
+            recordRef = agent;
+          },
+        },
+      },
+    );
+  } catch (err) {
+    clearInterval(spinnerInterval);
+    return textResult(err instanceof Error ? err.message : String(err));
+  }
+
+  clearInterval(spinnerInterval);
+
+  const tokenText = formatLifetimeTokens(record);
+  const details = buildDetails(presentation.detailBase, record, { tokens: tokenText });
+
+  const fallbackNote = identity.fellBack
+    ? `Note: Unknown agent type "${identity.rawType}" — using general-purpose.\n\n`
+    : "";
+
+  if (record.status === "error") {
+    return textResult(`${fallbackNote}Agent failed: ${record.error}`, details);
+  }
+
+  const durationMs = (record.completedAt ?? Date.now()) - record.startedAt;
+  const statsParts = [`${record.toolUses} tool uses`];
+  if (tokenText) statsParts.push(tokenText);
+  return textResult(
+    `${fallbackNote}Agent completed in ${formatMs(durationMs)} (${statsParts.join(", ")})${getStatusNote(record.status)}.\n\n` +
+      (record.result?.trim() ?? "No output."),
+    details,
+  );
+}

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/tools/get-result-report.ts

@@ -0,0 +1,60 @@
+/**
+ * get-result-report.ts — Pure report assembly for get_subagent_result.
+ *
+ * All functions are stateless: they receive an AgentReport, returning
+ * formatted strings. No SDK types, no timers, no side effects.
+ * Consumed by GetResultTool.execute in get-result-tool.ts. Mirrors the
+ * result-renderer.ts pattern used by the subagent tool's TUI renderer.
+ */
+
+import type { SubagentStatus } from "#src/lifecycle/subagent";
+
+/** The data a get_subagent_result report renders from — only what the formatter reads. */
+export interface AgentReport {
+	id: string;
+	displayName: string;
+	status: SubagentStatus;
+	toolUses: number;
+	/** Pre-formatted lifetime token total; "" when zero. */
+	tokens: string;
+	contextPercent: number | null;
+	compactionCount: number;
+	/** Pre-formatted duration string. */
+	duration: string;
+	description: string;
+	result: string | undefined;
+	error: string | undefined;
+	/** Present only when verbose was requested and a conversation is available. */
+	conversation?: string;
+}
+
+/** Assemble the stats parts: Tool uses / tokens? / Context? / Compactions? / Duration. */
+export function renderStatsParts(report: AgentReport): string[] {
+	const parts = [`Tool uses: ${report.toolUses}`];
+	if (report.tokens) parts.push(report.tokens);
+	if (report.contextPercent !== null) parts.push(`Context: ${Math.round(report.contextPercent)}%`);
+	if (report.compactionCount) parts.push(`Compactions: ${report.compactionCount}`);
+	parts.push(`Duration: ${report.duration}`);
+	return parts;
+}
+
+/** Select the per-status body: running note, error line, or trimmed result. */
+export function renderReportBody(report: AgentReport): string {
+	if (report.status === "running")
+		return "Agent is still running. Use wait: true or check back later.";
+	if (report.status === "error") return `Error: ${report.error}`;
+	return report.result?.trim() ?? "No output.";
+}
+
+/** Assemble the full get_subagent_result report text. */
+export function formatAgentReport(report: AgentReport): string {
+	let output =
+		`Agent: ${report.id}\n` +
+		`Type: ${report.displayName} | Status: ${report.status} | ${renderStatsParts(report).join(" | ")}\n` +
+		`Description: ${report.description}\n\n`;
+	output += renderReportBody(report);
+	if (report.conversation) {
+		output += `\n\n--- Agent Conversation ---\n${report.conversation}`;
+	}
+	return output;
+}

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/tools/get-result-tool.ts

@@ -0,0 +1,108 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import type { AgentConfigLookup } from "#src/config/agent-types";
+import { type AgentReport, formatAgentReport } from "#src/tools/get-result-report";
+import { formatLifetimeTokens, textResult } from "#src/tools/helpers";
+import type { Subagent } from "#src/types";
+import { formatDuration, getDisplayName } from "#src/ui/display";
+
+// ---- Deps interfaces ----
+
+export interface GetResultToolManager {
+	getRecord(id: string): Subagent | undefined;
+}
+
+export interface GetResultToolNotifications {
+	consume(id: string): void;
+}
+
+// ---- Class ----
+
+export class GetResultTool {
+	constructor(
+		private readonly manager: GetResultToolManager,
+		private readonly notifications: GetResultToolNotifications,
+		private readonly registry: AgentConfigLookup,
+	) {}
+
+	async execute(
+		_toolCallId: string,
+		params: { agent_id: string; wait?: boolean; verbose?: boolean },
+		_signal: AbortSignal,
+		_onUpdate: unknown,
+		_ctx: unknown,
+	) {
+		const record = this.manager.getRecord(params.agent_id);
+		if (!record) {
+			return textResult(`Agent not found: "${params.agent_id}". It may have been cleaned up.`);
+		}
+
+		// Wait for completion if requested.
+		// Consume BEFORE awaiting: onComplete fires inside .then() (attached
+		// earlier at spawn time) and always runs before this await resumes.
+		// Consuming here prevents a redundant follow-up notification.
+		if (params.wait && record.status === "running" && record.promise) {
+			this.notifications.consume(params.agent_id);
+			await record.promise;
+		}
+
+		// Consume the settled result — suppresses the completion notification.
+		if (record.status !== "running" && record.status !== "queued") {
+			this.notifications.consume(params.agent_id);
+		}
+
+		return textResult(formatAgentReport(this.buildReport(record, params.verbose)));
+	}
+
+	private buildReport(record: Subagent, verbose?: boolean): AgentReport {
+		return {
+			id: record.id,
+			displayName: getDisplayName(record.type, this.registry),
+			status: record.status,
+			toolUses: record.toolUses,
+			tokens: formatLifetimeTokens(record),
+			contextPercent: record.getContextPercent(),
+			compactionCount: record.compactionCount,
+			duration: formatDuration(record.startedAt, record.completedAt),
+			description: record.description,
+			result: record.result,
+			error: record.error,
+			conversation: verbose ? record.getConversation() : undefined,
+		};
+	}
+
+	toToolDefinition() {
+		return defineTool({
+			name: "get_subagent_result" as const,
+			label: "Get Agent Result",
+			promptSnippet:
+				"get_subagent_result: Check status and retrieve results from a background agent.",
+			description:
+				"Check status and retrieve results from a background agent. Use the agent ID returned by Agent with run_in_background.",
+			parameters: Type.Object({
+				agent_id: Type.String({
+					description: "The agent ID to check.",
+				}),
+				wait: Type.Optional(
+					Type.Boolean({
+						description:
+							"If true, wait for the agent to complete before returning. Default: false.",
+					}),
+				),
+				verbose: Type.Optional(
+					Type.Boolean({
+						description:
+							"If true, include the agent's full conversation (messages + tool calls). Default: false.",
+					}),
+				),
+			}),
+			execute: (
+				toolCallId: string,
+				params: { agent_id: string; wait?: boolean; verbose?: boolean },
+				signal: AbortSignal,
+				onUpdate: unknown,
+				ctx: unknown,
+			) => this.execute(toolCallId, params, signal, onUpdate, ctx),
+		});
+	}
+}