@yandy0725/pi-subagents 0.1.0

package/src/tools/result-renderer.ts

@@ -0,0 +1,109 @@
+/**
+ * result-renderer.ts — Pure per-status rendering functions for Agent tool results.
+ *
+ * All functions are stateless: they receive AgentDetails and a Theme, returning
+ * formatted strings. No SDK types, no timers, no side effects.
+ * Consumed by the renderResult hook in agent-tool.ts.
+ */
+
+import type { AgentDetails, Theme } from "../ui/display";
+import { formatMs, formatTurns, SPINNER } from "../ui/display";
+
+// ---- Dispatcher ----
+
+/** Dispatch to the per-status renderer based on details.status and isPartial. */
+export function renderAgentResult(
+	details: AgentDetails,
+	resultText: string,
+	expanded: boolean,
+	isPartial: boolean,
+	theme: Theme,
+): string {
+	if (isPartial || details.status === "running") return renderRunning(details, theme);
+	if (details.status === "background") return renderBackground(details, theme);
+	if (details.status === "completed" || details.status === "steered")
+		return renderCompleted(details, resultText, expanded, theme);
+	if (details.status === "stopped") return renderStopped(details, theme);
+	return renderFailed(details, theme);
+}
+
+// ---- Per-status renderers ----
+
+/** Render running/partial status: spinner + stats + activity line. */
+export function renderRunning(details: AgentDetails, theme: Theme): string {
+	const frame = SPINNER[details.spinnerFrame ?? 0];
+	const s = renderStats(details, theme);
+	let line = theme.fg("accent", frame) + (s ? " " + s : "");
+	line += "\n" + theme.fg("dim", `  ⎿  ${details.activity ?? "thinking\u2026"}`);
+	return line;
+}
+
+/** Render background launch status. */
+export function renderBackground(details: AgentDetails, theme: Theme): string {
+	return theme.fg("dim", `  \u23BF  Running in background (ID: ${details.agentId})`);
+}
+
+/** Render completed or steered status with optional expanded result text. */
+export function renderCompleted(details: AgentDetails, resultText: string, expanded: boolean, theme: Theme): string {
+	const duration = formatMs(details.durationMs);
+	const isSteered = details.status === "steered";
+	const icon = isSteered ? theme.fg("warning", "\u2713") : theme.fg("success", "\u2713");
+	const s = renderStats(details, theme);
+	let line = icon + (s ? " " + s : "");
+	line += " " + theme.fg("dim", "\u00B7") + " " + theme.fg("dim", duration);
+
+	if (expanded) {
+		if (resultText) {
+			const lines = resultText.split("\n").slice(0, 50);
+			for (const l of lines) {
+				line += "\n" + theme.fg("dim", `  ${l}`);
+			}
+			if (resultText.split("\n").length > 50) {
+				line += "\n" + theme.fg("muted", "  ... (use get_subagent_result with verbose for full output)");
+			}
+		}
+	} else {
+		const doneText = isSteered ? "Wrapped up (turn limit)" : "Done";
+		line += "\n" + theme.fg("dim", `  \u23BF  ${doneText}`);
+	}
+	return line;
+}
+
+/** Render stopped status: dim stop icon + stats + "Stopped". */
+export function renderStopped(details: AgentDetails, theme: Theme): string {
+	const s = renderStats(details, theme);
+	let line = theme.fg("dim", "\u25A0") + (s ? " " + s : "");
+	line += "\n" + theme.fg("dim", "  \u23BF  Stopped");
+	return line;
+}
+
+/** Render error or aborted status: error icon + stats + status message. */
+export function renderFailed(details: AgentDetails, theme: Theme): string {
+	const s = renderStats(details, theme);
+	let line = theme.fg("error", "\u2717") + (s ? " " + s : "");
+
+	if (details.status === "error") {
+		line += "\n" + theme.fg("error", `  \u23BF  Error: ${details.error ?? "unknown"}`);
+	} else {
+		line += "\n" + theme.fg("warning", "  \u23BF  Aborted (max turns exceeded)");
+	}
+	return line;
+}
+
+// ---- Shared helper ----
+
+/**
+ * Build the stats string: "haiku · thinking: high · ⟳5≤30 · 3 tool uses · 33.8k token".
+ * Returns an empty string when all fields are absent or zero.
+ */
+export function renderStats(details: AgentDetails, theme: Theme): string {
+	const parts: string[] = [];
+	if (details.modelName) parts.push(details.modelName);
+	if (details.tags) parts.push(...details.tags);
+	if (details.turnCount != null && details.turnCount > 0) {
+		parts.push(formatTurns(details.turnCount, details.maxTurns));
+	}
+	if (details.toolUses > 0) parts.push(`${details.toolUses} tool use${details.toolUses === 1 ? "" : "s"}`);
+	if (details.tokens) parts.push(details.tokens);
+	return parts.map((p) => theme.fg("dim", p)).join(" " + theme.fg("dim", "\u00B7") + " ");
+}

package/src/tools/spawn-config.ts

@@ -0,0 +1,150 @@
+/* eslint-disable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-argument -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
+/**
+ * spawn-config.ts — Pure config resolution for the Agent tool.
+ *
+ * Extracts all config resolution logic from execute: type resolution,
+ * invocation config merge, model resolution, max-turns normalization,
+ * tag building, and detail-base construction.
+ */
+
+import type { Model } from "@earendil-works/pi-ai";
+import type { AgentTypeRegistry } from "../config/agent-types";
+import { resolveAgentInvocationConfig } from "../config/invocation-config";
+import { normalizeMaxTurns } from "../lifecycle/turn-limits";
+import { resolveInvocationModel } from "../session/model-resolver";
+import type { AgentInvocation, SubagentType, ThinkingLevel } from "../types";
+import { type AgentDetails, buildInvocationTags, getDisplayName, getPromptModeLabel } from "../ui/display";
+
+/** Model info extracted from the parent session context. */
+export interface ModelInfo {
+	parentModel: { id: string; name?: string } | undefined;
+	modelRegistry: unknown;
+}
+
+/** Identity: who is being spawned. */
+export interface SpawnIdentity {
+	subagentType: string;
+	rawType: SubagentType;
+	fellBack: boolean;
+	displayName: string;
+}
+
+/** Execution: how the agent will run. */
+export interface SpawnExecution {
+	prompt: string;
+	description: string;
+	model: Model<any> | undefined;
+	effectiveMaxTurns: number | undefined;
+	thinking: ThinkingLevel | undefined;
+	inheritContext: boolean;
+	runInBackground: boolean;
+	agentInvocation: AgentInvocation;
+}
+
+/** Presentation: display/UI values derived from identity and execution. */
+export interface SpawnPresentation {
+	modelName: string | undefined;
+	agentTags: string[];
+	detailBase: Pick<AgentDetails, "displayName" | "description" | "subagentType" | "modelName" | "tags">;
+}
+
+/** Fully resolved config for spawning an agent — composed of domain-aligned sub-interfaces. */
+export interface ResolvedSpawnConfig {
+	identity: SpawnIdentity;
+	execution: SpawnExecution;
+	presentation: SpawnPresentation;
+}
+
+/** Error result when model resolution fails. */
+export interface SpawnConfigError {
+	error: string;
+}
+
+/**
+ * Resolve all config for an Agent tool invocation.
+ *
+ * Pure function — no SDK types, no side effects.
+ * Returns either a fully resolved config or an error.
+ */
+export function resolveSpawnConfig(
+	params: Record<string, unknown>,
+	registry: AgentTypeRegistry,
+	modelInfo: ModelInfo,
+	settings: { readonly defaultMaxTurns: number | undefined },
+): ResolvedSpawnConfig | SpawnConfigError {
+	const rawType = params.subagent_type as SubagentType;
+	const resolved = registry.resolveType(rawType);
+
+	// A known-but-disabled type is an explicit error, not a silent unknown-type fallback.
+	if (resolved !== undefined && !registry.isValidType(resolved)) {
+		return { error: `Agent type "${resolved}" is disabled` };
+	}
+
+	const subagentType = resolved ?? "general-purpose";
+	const fellBack = resolved === undefined;
+
+	const displayName = getDisplayName(subagentType, registry);
+
+	// Merge agent config defaults with tool-call params
+	const customConfig = registry.resolveAgentConfig(subagentType);
+	const resolvedConfig = resolveAgentInvocationConfig(customConfig, params);
+
+	// Resolve model
+	const resolution = resolveInvocationModel(
+		modelInfo.parentModel,
+		resolvedConfig.modelInput,
+		resolvedConfig.modelFromParams,
+		modelInfo.modelRegistry as any,
+	);
+	if (resolution.error) return { error: resolution.error };
+	const model = resolution.model;
+
+	const thinking = resolvedConfig.thinking;
+	const inheritContext = resolvedConfig.inheritContext;
+	const runInBackground = resolvedConfig.runInBackground;
+
+	// Compute display model name (only shown when different from parent)
+	const parentModelId = modelInfo.parentModel?.id;
+	const effectiveModelId = model?.id;
+	const modelName =
+		effectiveModelId && effectiveModelId !== parentModelId
+			? (model?.name ?? effectiveModelId).replace(/^Claude\s+/i, "").toLowerCase()
+			: undefined;
+
+	const effectiveMaxTurns = normalizeMaxTurns(resolvedConfig.maxTurns ?? settings.defaultMaxTurns);
+
+	const agentInvocation: AgentInvocation = {
+		modelName,
+		thinking,
+		maxTurns: normalizeMaxTurns(resolvedConfig.maxTurns),
+		inheritContext,
+		runInBackground,
+	};
+
+	const modeLabel = getPromptModeLabel(subagentType, registry);
+	const { tags: invocationTags } = buildInvocationTags(agentInvocation);
+	const agentTags = modeLabel ? [modeLabel, ...invocationTags] : invocationTags;
+
+	const detailBase = {
+		displayName,
+		description: params.description as string,
+		subagentType,
+		modelName,
+		tags: agentTags.length > 0 ? agentTags : undefined,
+	};
+
+	return {
+		identity: { subagentType, rawType, fellBack, displayName },
+		execution: {
+			prompt: params.prompt as string,
+			description: params.description as string,
+			model,
+			effectiveMaxTurns,
+			thinking,
+			inheritContext,
+			runInBackground,
+			agentInvocation,
+		},
+		presentation: { modelName, agentTags, detailBase },
+	};
+}

package/src/tools/steer-tool.ts

@@ -0,0 +1,90 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { formatLifetimeTokens, textResult } from "../tools/helpers";
+import type { Subagent } from "../types";
+
+// ---- Deps interfaces ----
+
+export interface SteerToolManager {
+	getRecord(id: string): Subagent | undefined;
+}
+
+export interface SteerToolEvents {
+	emit(name: string, data: unknown): void;
+}
+
+// ---- Class ----
+
+export class SteerTool {
+	constructor(
+		private readonly manager: SteerToolManager,
+		private readonly events: SteerToolEvents,
+	) {}
+
+	async execute(
+		_toolCallId: string,
+		params: { agent_id: string; message: string },
+		_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.`);
+		}
+		if (record.status !== "running") {
+			return textResult(
+				`Agent "${params.agent_id}" is not running (status: ${record.status}). Cannot steer a non-running agent.`,
+			);
+		}
+		try {
+			const delivered = await record.steer(params.message);
+			this.events.emit("subagents:steered", { id: record.id, message: params.message });
+			if (!delivered) {
+				return textResult(
+					`Steering message queued for agent ${record.id}. It will be delivered once the session initializes.`,
+				);
+			}
+			const tokens = formatLifetimeTokens(record);
+			const contextPercent = record.getContextPercent();
+			const stateParts: string[] = [];
+			if (tokens) stateParts.push(tokens);
+			stateParts.push(`${record.toolUses} tool ${record.toolUses === 1 ? "use" : "uses"}`);
+			if (contextPercent !== null) stateParts.push(`context ${Math.round(contextPercent)}% full`);
+			if (record.compactionCount)
+				stateParts.push(`${record.compactionCount} compaction${record.compactionCount === 1 ? "" : "s"}`);
+			return textResult(
+				`Steering message sent to agent ${record.id}. The agent will process it after its current tool execution.\n` +
+					`Current state: ${stateParts.join(" · ")}`,
+			);
+		} catch (err) {
+			return textResult(`Failed to steer agent: ${err instanceof Error ? err.message : String(err)}`);
+		}
+	}
+
+	toToolDefinition() {
+		return defineTool({
+			name: "steer_subagent" as const,
+			label: "Steer Agent",
+			promptSnippet: "steer_subagent: Send a mid-run message to redirect a running background agent.",
+			description:
+				"Send a steering message to a running agent. The message will interrupt the agent after its current tool execution " +
+				"and be injected into its conversation, allowing you to redirect its work mid-run. Only works on running agents.",
+			parameters: Type.Object({
+				agent_id: Type.String({
+					description: "The agent ID to steer (must be currently running).",
+				}),
+				message: Type.String({
+					description: "The steering message to send. This will appear as a user message in the agent's conversation.",
+				}),
+			}),
+			execute: (
+				toolCallId: string,
+				params: { agent_id: string; message: string },
+				signal: AbortSignal,
+				onUpdate: unknown,
+				ctx: unknown,
+			) => this.execute(toolCallId, params, signal, onUpdate, ctx),
+		});
+	}
+}

package/src/types.ts

@@ -0,0 +1,115 @@
+/**
+ * types.ts — Type definitions for the subagent system.
+ */
+
+import type { ThinkingLevel } from "@earendil-works/pi-ai";
+import type { AgentSessionEvent, SessionContext as SdkSessionContext } from "@earendil-works/pi-coding-agent";
+import type { ModelRegistry } from "./session/model-resolver";
+
+export { Subagent } from "./lifecycle/subagent";
+export type { AgentSessionEvent, ThinkingLevel };
+
+/**
+ * One message in a child session's history, typed from Pi's `SessionContext`.
+ *
+ * Derived from the barrel-exported `SessionContext` (whose `messages` field is
+ * `AgentMessage[]`) so the package needs no direct dependency on
+ * `@earendil-works/pi-agent-core`, which is not re-exported from the public barrel.
+ */
+export type SessionMessage = SdkSessionContext["messages"][number];
+
+/**
+ * Narrow session interface for event subscription.
+ * Used by record-observer — only the subscribe method is needed.
+ */
+export interface SubscribableSession {
+	subscribe(fn: (event: AgentSessionEvent) => void): () => void;
+}
+
+/** Agent type: any string name (built-in defaults or user-defined). */
+export type SubagentType = string;
+
+/** UI display and agent listing — name, display name, description, prompt mode. */
+export interface AgentIdentity {
+	name: string;
+	displayName?: string;
+	description: string;
+	promptMode: "replace" | "append";
+}
+
+/** Prompt assembly — name, prompt mode, system prompt. */
+export interface AgentPromptConfig {
+	name: string;
+	promptMode: "replace" | "append";
+	systemPrompt: string;
+}
+
+/** Unified agent configuration — used for both default and user-defined agents. */
+export interface AgentConfig extends AgentIdentity, AgentPromptConfig {
+	builtinToolNames?: string[];
+	model?: string;
+	thinking?: ThinkingLevel;
+	maxTurns?: number;
+	/** Default for spawn: fork parent conversation. undefined = caller decides. */
+	inheritContext?: boolean;
+	/** Default for spawn: run in background. undefined = caller decides. */
+	runInBackground?: boolean;
+	/** true = this is an embedded default agent (informational) */
+	isDefault?: boolean;
+	/** false = agent is hidden from the registry */
+	enabled?: boolean;
+	/** Where this agent was loaded from */
+	source?: "default" | "project" | "global";
+}
+
+export interface AgentInvocation {
+	/** Short display name, e.g. "haiku" — only set when different from parent. */
+	modelName?: string;
+	thinking?: ThinkingLevel;
+	maxTurns?: number;
+	inheritContext?: boolean;
+	runInBackground?: boolean;
+}
+
+/**
+ * Narrow shell-exec callback replacing `ExtensionAPI` in `detectEnv()`.
+ * Matches the shape of `pi.exec()` without carrying an SDK dependency.
+ */
+/**
+ * Narrow interface capturing the ExtensionContext fields SubagentRuntime needs.
+ * Avoids coupling runtime to the full SDK ExtensionContext surface (ISP).
+ */
+export interface SessionContext {
+	readonly cwd: string;
+	readonly model: unknown;
+	readonly modelRegistry: ModelRegistry | undefined;
+	getSystemPrompt(): string;
+	readonly sessionManager: {
+		getSessionFile(): string | undefined;
+		getSessionId(): string;
+		getBranch(): unknown[];
+	};
+}
+
+/**
+ * Narrow shell-exec callback replacing `ExtensionAPI` in `detectEnv()`.
+ * Matches the shape of `pi.exec()` without carrying an SDK dependency.
+ */
+export type ShellExec = (
+	command: string,
+	args: string[],
+	options?: { cwd?: string; timeout?: number },
+) => Promise<{ stdout: string; stderr: string; code: number }>;
+
+/** Parent session identity — grouped fields that travel together from the tool boundary. */
+export interface ParentSessionInfo {
+	/** Path to the parent session's JSONL file (for deriving the subagent session directory). */
+	parentSessionFile?: string;
+	/** Session ID of the parent agent (stored in the child session's parentSession header). */
+	parentSessionId?: string;
+	/** Tool call ID for background notification wiring. When set, spawn attaches NotificationState. */
+	toolCallId?: string;
+}
+
+/** Compaction event info passed through lifecycle observers. */
+export type CompactionInfo = { reason: "manual" | "threshold" | "overflow"; tokensBefore: number };