@melihmucuk/pi-crew 1.0.17 → 1.0.19

package/extension/subagent-session.ts

@@ -0,0 +1,257 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { Api, AssistantMessage, Model } from "@earendil-works/pi-ai";
+import {
+	type AgentSession,
+	createAgentSession,
+	DefaultResourceLoader,
+	type ModelRegistry,
+	SessionManager,
+	SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+import type { AgentConfig } from "./catalog.js";
+import { SUPPORTED_TOOL_NAMES, type SupportedToolName } from "./catalog.js";
+import type { SubagentState } from "./crew.js";
+import type { SubagentStatus } from "./ui.js";
+
+export interface BootstrapContext {
+	model: Model<Api> | undefined;
+	modelRegistry: ModelRegistry;
+	agentDir: string;
+	parentSessionFile?: string;
+}
+
+interface BootstrapOptions {
+	agentConfig: AgentConfig;
+	cwd: string;
+	ctx: BootstrapContext;
+	extensionResolvedPath: string;
+}
+
+interface BootstrapResult {
+	session: AgentSession;
+	warnings: string[];
+}
+
+interface PromptOutcome {
+	status: Extract<SubagentStatus, "done" | "waiting" | "error" | "aborted">;
+	result?: string;
+	error?: string;
+}
+
+interface StartOptions {
+	cwd: string;
+	ctx: BootstrapContext;
+	extensionResolvedPath: string;
+	onWarning?: (message: string) => void;
+}
+
+export interface SubagentRunnerCallbacks {
+	isCurrent: (state: SubagentState) => boolean;
+	onProgress: (ownerSessionId: string) => void;
+	onSettled: (
+		state: SubagentState,
+		status: Extract<SubagentStatus, "done" | "waiting" | "error" | "aborted">,
+		outcome: { result?: string; error?: string },
+	) => void;
+}
+
+export interface SubagentRunner {
+	start(state: SubagentState, opts: StartOptions): void;
+	respond(state: SubagentState, message: string): void;
+	abort(state: SubagentState): void;
+}
+
+function resolveTools(agentConfig: AgentConfig): SupportedToolName[] {
+	return [...(agentConfig.tools ?? SUPPORTED_TOOL_NAMES)];
+}
+
+function resolveModel(agentConfig: AgentConfig, ctx: BootstrapContext): { model: Model<Api> | undefined; warnings: string[] } {
+	const warnings: string[] = [];
+	const model = ctx.model;
+	if (!agentConfig.parsedModel) return { model, warnings };
+
+	const found = ctx.modelRegistry.find(agentConfig.parsedModel.provider, agentConfig.parsedModel.modelId);
+	if (found) return { model: found, warnings };
+
+	warnings.push(`Model "${agentConfig.model}" not found, using current session model`);
+	return { model, warnings };
+}
+
+function getSkillWarnings(agentConfig: AgentConfig, resourceLoader: DefaultResourceLoader): string[] {
+	const warnings: string[] = [];
+	if (!agentConfig.skills) return warnings;
+
+	const availableSkillNames = new Set(resourceLoader.getSkills().skills.map((skill) => skill.name));
+	for (const skillName of agentConfig.skills) {
+		if (!availableSkillNames.has(skillName)) {
+			warnings.push(`Unknown skill "${skillName}" in subagent config, skipping`);
+		}
+	}
+	return warnings;
+}
+
+async function bootstrapSession(opts: BootstrapOptions): Promise<BootstrapResult> {
+	const warnings: string[] = [];
+	const { agentConfig, cwd, ctx, extensionResolvedPath } = opts;
+
+	const authStorage = ctx.modelRegistry.authStorage;
+	const modelRegistry = ctx.modelRegistry;
+	const { model, warnings: modelWarnings } = resolveModel(agentConfig, ctx);
+	warnings.push(...modelWarnings);
+	const tools = resolveTools(agentConfig);
+
+	const resourceLoader = new DefaultResourceLoader({
+		cwd,
+		agentDir: ctx.agentDir,
+		extensionsOverride: (base) => ({
+			...base,
+			extensions: base.extensions.filter((ext) => !ext.resolvedPath.startsWith(extensionResolvedPath)),
+		}),
+		skillsOverride: agentConfig.skills
+			? (base) => ({
+				skills: base.skills.filter((skill) => agentConfig.skills!.includes(skill.name)),
+				diagnostics: base.diagnostics,
+			})
+			: undefined,
+		appendSystemPromptOverride: (base) => agentConfig.systemPrompt.trim() ? [...base, agentConfig.systemPrompt] : base,
+	});
+	await resourceLoader.reload();
+	warnings.push(...getSkillWarnings(agentConfig, resourceLoader));
+
+	const settingsManager = SettingsManager.inMemory({
+		compaction: { enabled: agentConfig.compaction ?? true },
+	});
+
+	const sessionManager = SessionManager.create(cwd);
+	sessionManager.newSession({ parentSession: ctx.parentSessionFile });
+
+	const result = await createAgentSession({
+		cwd,
+		agentDir: ctx.agentDir,
+		model,
+		thinkingLevel: agentConfig.thinking,
+		tools,
+		resourceLoader,
+		sessionManager,
+		settingsManager,
+		authStorage,
+		modelRegistry,
+	});
+
+	return { session: result.session, warnings };
+}
+
+function getLastAssistantMessage(messages: AgentMessage[]): AssistantMessage | undefined {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const msg = messages[i];
+		if (msg.role === "assistant") return msg as AssistantMessage;
+	}
+	return undefined;
+}
+
+function getAssistantText(message: AssistantMessage | undefined): string | undefined {
+	if (!message) return undefined;
+	const texts: string[] = [];
+	for (const part of message.content) {
+		if (part.type === "text") texts.push(part.text);
+	}
+	return texts.length > 0 ? texts.join("\n") : undefined;
+}
+
+function getPromptOutcome(state: SubagentState): PromptOutcome {
+	const lastAssistant = getLastAssistantMessage(state.session!.messages);
+	const text = getAssistantText(lastAssistant);
+
+	if (lastAssistant?.stopReason === "error") {
+		return { status: "error", error: lastAssistant.errorMessage ?? text ?? "(no output)" };
+	}
+	if (lastAssistant?.stopReason === "aborted") {
+		return { status: "aborted", error: lastAssistant.errorMessage ?? text ?? "(no output)" };
+	}
+	return { status: state.agentConfig.interactive ? "waiting" : "done", result: text ?? "(no output)" };
+}
+
+function isAborted(state: SubagentState): boolean {
+	return state.status === "aborted";
+}
+
+export class SubagentSessionRunner implements SubagentRunner {
+	constructor(private readonly callbacks: SubagentRunnerCallbacks) {}
+
+	start(state: SubagentState, opts: StartOptions): void {
+		void this.spawnSession(state, opts);
+	}
+
+	respond(state: SubagentState, message: string): void {
+		void this.runPromptCycle(state, message);
+	}
+
+	abort(state: SubagentState): void {
+		state.session?.abortCompaction();
+		state.session?.abort().catch(() => {});
+	}
+
+	private attachSessionListeners(state: SubagentState, session: AgentSession): void {
+		state.unsubscribe = session.subscribe((event) => {
+			if (event.type !== "turn_end") return;
+			state.turns++;
+			const msg = event.message;
+			if (msg.role === "assistant") {
+				const assistantMsg = msg as AssistantMessage;
+				state.contextTokens = assistantMsg.usage.totalTokens;
+				state.model = assistantMsg.model;
+			}
+			this.callbacks.onProgress(state.ownerSessionId);
+		});
+	}
+
+	private attachSpawnedSession(state: SubagentState, session: AgentSession): boolean {
+		if (!this.callbacks.isCurrent(state)) {
+			session.dispose();
+			return false;
+		}
+		state.session = session;
+		return true;
+	}
+
+	private async runPromptCycle(state: SubagentState, prompt: string): Promise<void> {
+		if (isAborted(state)) return;
+
+		try {
+			await state.session!.prompt(prompt);
+			if (isAborted(state)) return;
+
+			const outcome = getPromptOutcome(state);
+			this.callbacks.onSettled(state, outcome.status, outcome);
+		} catch (err) {
+			if (isAborted(state)) return;
+			const error = err instanceof Error ? err.message : String(err);
+			this.callbacks.onSettled(state, "error", { error });
+		}
+	}
+
+	private async spawnSession(state: SubagentState, opts: StartOptions): Promise<void> {
+		try {
+			if (isAborted(state)) return;
+
+			const { session, warnings } = await bootstrapSession({
+				agentConfig: state.agentConfig,
+				cwd: opts.cwd,
+				ctx: opts.ctx,
+				extensionResolvedPath: opts.extensionResolvedPath,
+			});
+
+			for (const warning of warnings) opts.onWarning?.(warning);
+			if (!this.attachSpawnedSession(state, session)) return;
+
+			this.attachSessionListeners(state, session);
+			await this.runPromptCycle(state, state.task);
+		} catch (err) {
+			if (isAborted(state)) return;
+			if (state.status === "running") {
+				const error = err instanceof Error ? err.message : String(err);
+				this.callbacks.onSettled(state, "error", { error });
+			}
+		}
+	}
+}

package/extension/tools.ts

@@ -0,0 +1,323 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import { getAgentDir, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import {
+	discoverAgents,
+	type AgentConfig,
+	type AgentDiscoveryWarning,
+} from "./catalog.js";
+import type { AbortOwnedResult, ActiveAgentSummary, CrewRuntime } from "./crew.js";
+import { STATUS_ICON, renderCrewCall, renderCrewResult, sendCrewListActiveWarning } from "./ui.js";
+
+export type CrewToolResult = AgentToolResult<unknown> & {
+	isError?: boolean;
+	terminate?: boolean;
+};
+
+type RegisteredTool = Parameters<ExtensionAPI["registerTool"]>[0];
+type ToolRenderCall = Exclude<RegisteredTool["renderCall"], undefined>;
+
+interface ToolContext {
+	cwd: string;
+	callerSessionId: string;
+}
+
+function getToolContext(ctx: ExtensionContext): ToolContext {
+	return {
+		cwd: ctx.cwd,
+		callerSessionId: ctx.sessionManager.getSessionId(),
+	};
+}
+
+function toolError(text: string): CrewToolResult {
+	return {
+		content: [{ type: "text", text }],
+		isError: true,
+		details: { error: true },
+	};
+}
+
+function toolSuccess(
+	text: string,
+	details: Record<string, unknown> = {},
+	options: { terminate?: boolean } = {},
+): CrewToolResult {
+	return {
+		content: [{ type: "text", text }],
+		details,
+		...(options.terminate ? { terminate: true } : {}),
+	};
+}
+
+function formatAvailableAgents(agents: AgentConfig[]): string[] {
+	if (agents.length === 0) {
+		return ["No valid subagent definitions found. Add `.md` files to `<cwd>/.pi/agents/` or `~/.pi/agent/agents/`."];
+	}
+
+	return agents.flatMap((agent) => [
+		"",
+		`name: ${agent.name}`,
+		`description: ${agent.description}`,
+		`interactive: ${agent.interactive ? "true" : "false"}`,
+	]);
+}
+
+function formatWarnings(warnings: AgentDiscoveryWarning[]): string[] {
+	if (warnings.length === 0) return [];
+	return [
+		"",
+		"## Ignored subagent definitions",
+		...warnings.map((warning) => `- ${warning.message} (${warning.filePath})`),
+	];
+}
+
+function formatActiveAgents(running: ActiveAgentSummary[]): string[] {
+	if (running.length === 0) return ["No subagents currently active."];
+	return running.flatMap((agent) => {
+		const icon = STATUS_ICON[agent.status] ?? "❓";
+		return ["", `id: ${agent.id}`, `name: ${agent.agentName}`, `status: ${icon} ${agent.status}`];
+	});
+}
+
+function formatAbortToolMessage(result: AbortOwnedResult): string {
+	const parts: string[] = [];
+	if (result.abortedIds.length > 0) parts.push(`Aborted ${result.abortedIds.length} subagent(s): ${result.abortedIds.join(", ")}`);
+	if (result.missingIds.length > 0) parts.push(`Not found or already finished: ${result.missingIds.join(", ")}`);
+	if (result.foreignIds.length > 0) parts.push(`Belong to a different session: ${result.foreignIds.join(", ")}`);
+	return parts.join("\n");
+}
+
+function notifyDiscoveryWarnings(
+	ctx: ExtensionContext,
+	shownDiscoveryWarnings: Set<string>,
+	warnings: AgentDiscoveryWarning[],
+): void {
+	if (!ctx.hasUI) return;
+	for (const warning of warnings) {
+		const key = `${warning.filePath}:${warning.message}`;
+		if (shownDiscoveryWarnings.has(key)) continue;
+		shownDiscoveryWarnings.add(key);
+		ctx.ui.notify(`${warning.message} (${warning.filePath})`, "error");
+	}
+}
+
+function showActiveListWarning(pi: ExtensionAPI, ctx: ExtensionContext): void {
+	Promise.resolve().then(() => {
+		sendCrewListActiveWarning(pi.sendMessage.bind(pi), {
+			isIdle: ctx.isIdle(),
+			triggerTurn: true,
+		});
+	});
+}
+
+function registerActionTool<Params extends object>(
+	pi: ExtensionAPI,
+	options: Omit<RegisteredTool, "execute" | "renderResult" | "renderCall"> & {
+		action: (params: Params, ctx: ExtensionContext) => CrewToolResult;
+		renderCall?: (
+			args: Partial<Params>,
+			theme: Parameters<ToolRenderCall>[1],
+			context: Parameters<ToolRenderCall>[2],
+		) => ReturnType<ToolRenderCall>;
+	},
+): void {
+	const { action, renderCall, ...tool } = options;
+	pi.registerTool({
+		...tool,
+		...(renderCall ? { renderCall: (args, theme, context) => renderCall(args as Partial<Params>, theme, context) } : {}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			return action(params as Params, ctx);
+		},
+		renderResult(result, _options, theme, _context) {
+			return renderCrewResult(result, theme);
+		},
+	});
+}
+
+export function registerCrewTools(pi: ExtensionAPI, crew: CrewRuntime, extensionDir: string): void {
+	const shownDiscoveryWarnings = new Set<string>();
+
+	pi.registerTool({
+		name: "crew_list",
+		label: "List Crew",
+		description:
+			"List available subagent definitions and currently running subagents with their status. Use only to discover which subagents exist or to get a one-time status snapshot. Do NOT call this repeatedly to check if a subagent has finished — results are delivered automatically as steering messages.",
+		parameters: Type.Object({}),
+		promptSnippet: "List subagent definitions and active subagents",
+		promptGuidelines: [
+			"crew_list: List available subagents and active subagents owned by this session.",
+			"crew_list: Use before crew_spawn to discover names, descriptions, and interactive status.",
+			"crew_list: Use only for discovery or a requested status snapshot; do not poll for completion.",
+		],
+		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+			const toolCtx = getToolContext(ctx);
+			const { agents, warnings } = discoverAgents(toolCtx.cwd);
+			const running = crew.getActiveSummariesForOwner(toolCtx.callerSessionId);
+			const lines = [
+				"## Available Subagents",
+				...formatAvailableAgents(agents),
+				...formatWarnings(warnings),
+				"",
+				"## Active Subagents",
+				...formatActiveAgents(running),
+			];
+			notifyDiscoveryWarnings(ctx, shownDiscoveryWarnings, warnings);
+			if (running.length > 0) showActiveListWarning(pi, ctx);
+			return { content: [{ type: "text", text: lines.join("\n") }], details: {} };
+		},
+		renderCall(_args, theme, _context) {
+			return new Text(theme.fg("toolTitle", theme.bold("crew_list")), 0, 0);
+		},
+		renderResult(result, _options, _theme, _context) {
+			const text = result.content[0];
+			return new Text(text?.type === "text" ? text.text : "(no output)", 0, 0);
+		},
+	});
+
+	registerActionTool<{ subagent: string; task: string }>(pi, {
+		name: "crew_spawn",
+		label: "Spawn Crew",
+		description:
+			"Spawn a non-blocking subagent that runs in an isolated session. The subagent works independently while your session stays interactive. Results are delivered back to your session as steering messages.",
+		parameters: Type.Object({
+			subagent: Type.String({ description: "Subagent name from crew_list" }),
+			task: Type.String({ description: "Task to delegate to the subagent" }),
+		}),
+		promptSnippet: "Spawn a non-blocking subagent. Use crew_list first to see available subagents.",
+		promptGuidelines: [
+			"crew_spawn: Spawn a discovered subagent for one clearly delegated, self-contained task.",
+			"crew_spawn: Include only needed context: constraints, relevant files, acceptance criteria, and expected output.",
+			"crew_spawn: After spawning, ownership transfers to the subagent; do not work on that task yourself.",
+			"crew_spawn: Results arrive as steering messages; do not poll crew_list or fabricate results.",
+			"crew_spawn: Use the bundled pi-crew skill for detailed delegation patterns.",
+		],
+		action: (params, ctx) => {
+			const toolCtx = getToolContext(ctx);
+			const { agents, warnings } = discoverAgents(toolCtx.cwd);
+			notifyDiscoveryWarnings(ctx, shownDiscoveryWarnings, warnings);
+			const subagent = agents.find((candidate) => candidate.name === params.subagent);
+			if (!subagent) {
+				const available = agents.map((candidate) => candidate.name).join(", ") || "none";
+				return toolError(`Unknown subagent: "${params.subagent}". Available: ${available}`);
+			}
+
+			const id = crew.spawn(
+				subagent,
+				params.task,
+				toolCtx.cwd,
+				toolCtx.callerSessionId,
+				{
+					model: ctx.model,
+					modelRegistry: ctx.modelRegistry,
+					agentDir: getAgentDir(),
+					parentSessionFile: ctx.sessionManager.getSessionFile(),
+					onWarning: (msg) => ctx.ui.notify(msg, "warning"),
+				},
+				extensionDir,
+			);
+			return toolSuccess(
+				`Subagent '${subagent.name}' spawned as ${id}. Result will be delivered as a steering message when done.`,
+				{ id, agentName: subagent.name, task: params.task },
+			);
+		},
+		renderCall(args, theme, _context) {
+			return renderCrewCall(theme, "crew_spawn", args.subagent || "...", args.task);
+		},
+	});
+
+	registerActionTool<{ subagent_id?: string; subagent_ids?: string[]; all?: boolean }>(pi, {
+		name: "crew_abort",
+		label: "Abort Crew",
+		description: "Abort one, many, or all active subagents owned by the current session.",
+		parameters: Type.Object({
+			subagent_id: Type.Optional(Type.String({ description: "Single subagent ID to abort" })),
+			subagent_ids: Type.Optional(Type.Array(Type.String(), { minItems: 1, description: "Multiple subagent IDs to abort" })),
+			all: Type.Optional(Type.Boolean({ description: "Abort all active subagents owned by the current session" })),
+		}),
+		promptSnippet: "Abort one, many, or all active subagents from this session.",
+		promptGuidelines: [
+			"crew_abort: Abort one, many, or all active subagents owned by this session.",
+			"crew_abort: Provide exactly one mode: subagent_id, subagent_ids, or all=true.",
+			"crew_abort: Use only when delegated work is obsolete, wrong, or explicitly cancelled.",
+		],
+		action: (params, ctx) => {
+			const { callerSessionId } = getToolContext(ctx);
+			const modeCount = Number(Boolean(params.subagent_id)) + Number(Boolean(params.subagent_ids?.length)) + Number(params.all === true);
+			if (modeCount !== 1) return toolError("Provide exactly one of: subagent_id, subagent_ids, or all=true.");
+
+			if (params.all) {
+				const abortedIds = crew.abortAllOwned(callerSessionId, { reason: "Aborted by tool request" });
+				if (abortedIds.length === 0) return toolError("No active subagents in the current session.");
+				return toolSuccess(`Aborted ${abortedIds.length} subagent(s): ${abortedIds.join(", ")}`, { ids: abortedIds }, { terminate: true });
+			}
+
+			const ids = params.subagent_id ? [params.subagent_id] : (params.subagent_ids ?? []);
+			const result = crew.abortOwned(ids, callerSessionId, { reason: "Aborted by tool request" });
+			const message = formatAbortToolMessage(result);
+			if (result.abortedIds.length === 0) return toolError(message || "No subagents were aborted.");
+			return toolSuccess(
+				message,
+				{ ids: result.abortedIds, missing_ids: result.missingIds, foreign_ids: result.foreignIds },
+				{ terminate: true },
+			);
+		},
+		renderCall(args, theme, _context) {
+			if (args.all) return renderCrewCall(theme, "crew_abort", "all");
+			if (args.subagent_id) return renderCrewCall(theme, "crew_abort", args.subagent_id);
+			const count = Array.isArray(args.subagent_ids) ? args.subagent_ids.length : 0;
+			return renderCrewCall(theme, "crew_abort", `${count} ids`);
+		},
+	});
+
+	registerActionTool<{ subagent_id: string; message: string }>(pi, {
+		name: "crew_respond",
+		label: "Respond to Crew",
+		description: "Send a follow-up message to an interactive subagent that is waiting for a response.",
+		parameters: Type.Object({
+			subagent_id: Type.String({ description: "ID of the waiting subagent (from crew_list or crew_spawn result)" }),
+			message: Type.String({ description: "Message to send to the subagent" }),
+		}),
+		promptSnippet: "Send a follow-up message to a waiting interactive subagent.",
+		promptGuidelines: [
+			"crew_respond: Send a complete follow-up message to a waiting interactive subagent.",
+			"crew_respond: Use the waiting subagent ID from crew_spawn results or crew_list.",
+			"crew_respond: The response arrives as a steering message; do not poll crew_list.",
+		],
+		action: (params, ctx) => {
+			const { callerSessionId } = getToolContext(ctx);
+			const { error } = crew.respond(params.subagent_id, params.message, callerSessionId);
+			if (error) return toolError(error);
+			return toolSuccess(
+				`Message sent to subagent ${params.subagent_id}. Response will be delivered as a steering message.`,
+				{ id: params.subagent_id, message: params.message },
+			);
+		},
+		renderCall(args, theme, _context) {
+			return renderCrewCall(theme, "crew_respond", args.subagent_id || "...", args.message);
+		},
+	});
+
+	registerActionTool<{ subagent_id: string }>(pi, {
+		name: "crew_done",
+		label: "Done with Crew",
+		description: "Close an interactive subagent session. Use when you no longer need to interact with the subagent.",
+		parameters: Type.Object({
+			subagent_id: Type.String({ description: "ID of the subagent to close" }),
+		}),
+		promptSnippet: "Close an interactive subagent session when done.",
+		promptGuidelines: [
+			"crew_done: Close a waiting interactive subagent owned by this session.",
+			"crew_done: Use only when no further follow-up is needed; otherwise use crew_respond.",
+		],
+		action: (params, ctx) => {
+			const { callerSessionId } = getToolContext(ctx);
+			const { error } = crew.done(params.subagent_id, callerSessionId);
+			if (error) return toolError(error);
+			return toolSuccess(`Subagent ${params.subagent_id} closed.`, { id: params.subagent_id });
+		},
+		renderCall(args, theme, _context) {
+			return renderCrewCall(theme, "crew_done", args.subagent_id || "...");
+		},
+	});
+}