@clinebot/core 0.0.34 → 0.0.36

package/src/extensions/tools/runtime.ts

@@ -0,0 +1,261 @@
+import type { CoreAgentMode } from "../../types/config";
+import {
+	DEFAULT_MODEL_TOOL_ROUTING_RULES,
+	resolveToolRoutingConfig,
+} from "./model-tool-routing";
+import { resolveToolPresetName, ToolPresets } from "./presets";
+import { createSpawnAgentTool } from "./team/spawn-agent-tool";
+import { TEAM_TOOL_NAMES } from "./team/team-tools";
+import type { DefaultToolsConfig } from "./types";
+
+export interface ToolCatalogEntry {
+	id: string;
+	description: string;
+	defaultEnabled: boolean;
+	headlessToolNames: string[];
+}
+
+export interface BuiltinToolAvailabilityContext {
+	mode?: CoreAgentMode;
+	providerId?: string;
+	modelId?: string;
+	enableSpawnAgent?: boolean;
+	enableAgentTeams?: boolean;
+	disabledToolIds?: ReadonlySet<string>;
+}
+
+type RuntimeToolCatalogEntry = Omit<ToolCatalogEntry, "defaultEnabled">;
+
+const BASE_TOOL_CATALOG: readonly RuntimeToolCatalogEntry[] = [
+	{
+		id: "read_files",
+		description:
+			"Read the full content of text or image files at the provided absolute paths, or return only an inclusive one-based line range when start_line/end_line are provided.",
+		headlessToolNames: ["read_files"],
+	},
+	{
+		id: "search_codebase",
+		description:
+			"Perform regex pattern searches across the codebase for code patterns, definitions, imports, and other text matches.",
+		headlessToolNames: ["search_codebase"],
+	},
+	{
+		id: "run_commands",
+		description:
+			"Run shell commands from the root of the workspace for listing files, checking git status, builds, tests, and similar tasks.",
+		headlessToolNames: ["run_commands"],
+	},
+	{
+		id: "editor",
+		description:
+			"Make controlled filesystem edits on text files with create, replace, and insert operations.",
+		headlessToolNames: ["editor"],
+	},
+	{
+		id: "fetch_web_content",
+		description:
+			"Fetch URL content and analyze it with a prompt describing what to extract.",
+		headlessToolNames: ["fetch_web_content"],
+	},
+	{
+		id: "skills",
+		description:
+			"Execute a configured skill within the main conversation when a matching skill exists for the task.",
+		headlessToolNames: ["skills"],
+	},
+	{
+		id: "ask_question",
+		description:
+			"Ask the user a single clarifying question with 2-5 selectable options.",
+		headlessToolNames: ["ask_question"],
+	},
+	{
+		id: "spawn_agent",
+		description: createSpawnAgentTool({ configProvider: {} as never })
+			.description,
+		headlessToolNames: ["spawn_agent"],
+	},
+	{
+		id: "teams",
+		description:
+			"Enable team collaboration tools for teammate management, task coordination, mailbox messaging, mission logs, and outcomes.",
+		headlessToolNames: [...TEAM_TOOL_NAMES],
+	},
+] as const;
+
+const TOOL_NAME_TO_FLAG: Partial<
+	Record<
+		string,
+		keyof Pick<
+			DefaultToolsConfig,
+			| "enableReadFiles"
+			| "enableSearch"
+			| "enableBash"
+			| "enableWebFetch"
+			| "enableApplyPatch"
+			| "enableEditor"
+			| "enableSkills"
+			| "enableAskQuestion"
+			| "enableSubmitAndExit"
+		>
+	>
+> = {
+	read_files: "enableReadFiles",
+	search_codebase: "enableSearch",
+	run_commands: "enableBash",
+	fetch_web_content: "enableWebFetch",
+	apply_patch: "enableApplyPatch",
+	editor: "enableEditor",
+	skills: "enableSkills",
+	ask_question: "enableAskQuestion",
+};
+
+function resolveContextMode(
+	mode?: BuiltinToolAvailabilityContext["mode"],
+): CoreAgentMode {
+	return mode === "plan" || mode === "yolo" ? mode : "act";
+}
+
+type ResolvedToolFlags = Pick<
+	DefaultToolsConfig,
+	| "enableReadFiles"
+	| "enableSearch"
+	| "enableBash"
+	| "enableWebFetch"
+	| "enableApplyPatch"
+	| "enableEditor"
+	| "enableSkills"
+	| "enableAskQuestion"
+	| "enableSubmitAndExit"
+> & {
+	enableSpawnAgent?: boolean;
+	enableAgentTeams?: boolean;
+};
+
+function resolvePresetFlags(context: BuiltinToolAvailabilityContext): {
+	mode: CoreAgentMode;
+	flags: ResolvedToolFlags;
+} {
+	const mode = resolveContextMode(context.mode);
+	const preset = ToolPresets[resolveToolPresetName({ mode })];
+	const routed = resolveToolRoutingConfig(
+		context.providerId ?? "",
+		context.modelId ?? "",
+		mode,
+		DEFAULT_MODEL_TOOL_ROUTING_RULES,
+	);
+	return {
+		mode,
+		flags: {
+			...preset,
+			...routed,
+			...(typeof context.enableSpawnAgent === "boolean"
+				? { enableSpawnAgent: context.enableSpawnAgent }
+				: {}),
+			...(typeof context.enableAgentTeams === "boolean"
+				? { enableAgentTeams: context.enableAgentTeams }
+				: {}),
+		},
+	};
+}
+
+function isEntryEnabledByDefault(
+	entryId: string,
+	context: BuiltinToolAvailabilityContext,
+): boolean {
+	if (context.disabledToolIds?.has(entryId)) {
+		return false;
+	}
+
+	const { flags } = resolvePresetFlags(context);
+	if (entryId === "spawn_agent") {
+		return flags.enableSpawnAgent === true;
+	}
+	if (entryId === "teams") {
+		return flags.enableAgentTeams === true;
+	}
+	if (entryId === "editor") {
+		return flags.enableEditor === true || flags.enableApplyPatch === true;
+	}
+
+	const flag = TOOL_NAME_TO_FLAG[entryId];
+	return flag ? flags[flag] === true : false;
+}
+
+function buildCatalogEntry(
+	entry: RuntimeToolCatalogEntry,
+	context: BuiltinToolAvailabilityContext,
+): ToolCatalogEntry {
+	if (entry.id === "editor") {
+		const { flags } = resolvePresetFlags(context);
+		const usesApplyPatch =
+			flags.enableApplyPatch === true && flags.enableEditor !== true;
+		return {
+			...entry,
+			defaultEnabled: isEntryEnabledByDefault(entry.id, context),
+			headlessToolNames: [usesApplyPatch ? "apply_patch" : "editor"],
+		};
+	}
+
+	return {
+		...entry,
+		defaultEnabled: isEntryEnabledByDefault(entry.id, context),
+	};
+}
+
+export function getCoreBuiltinToolCatalog(
+	context: BuiltinToolAvailabilityContext = {},
+): ToolCatalogEntry[] {
+	return BASE_TOOL_CATALOG.map((entry) => buildCatalogEntry(entry, context));
+}
+
+export function getCoreDefaultEnabledToolIds(
+	context: BuiltinToolAvailabilityContext = {},
+): string[] {
+	return getCoreBuiltinToolCatalog(context)
+		.filter((entry) => entry.defaultEnabled)
+		.map((entry) => entry.id);
+}
+
+export function resolveCoreSelectedToolIds(input: {
+	enabled: boolean;
+	allowlist?: string[];
+	availabilityContext?: BuiltinToolAvailabilityContext;
+}): Set<string> {
+	if (!input.enabled) {
+		return new Set();
+	}
+
+	const catalog = getCoreBuiltinToolCatalog(input.availabilityContext);
+	const known = new Set(catalog.map((entry) => entry.id));
+	if (!input.allowlist || input.allowlist.length === 0) {
+		return new Set(
+			catalog.filter((entry) => entry.defaultEnabled).map((entry) => entry.id),
+		);
+	}
+
+	for (const id of input.allowlist) {
+		if (!known.has(id)) {
+			throw new Error(
+				`Unknown tool "${id}". Available tools: ${catalog.map((entry) => entry.id).join(", ")}`,
+			);
+		}
+	}
+	return new Set(input.allowlist);
+}
+
+export function getCoreHeadlessToolNames(
+	selectedToolIds: ReadonlySet<string>,
+	context: BuiltinToolAvailabilityContext = {},
+): string[] {
+	return getCoreBuiltinToolCatalog(context)
+		.filter((entry) => selectedToolIds.has(entry.id))
+		.flatMap((entry) => entry.headlessToolNames);
+}
+
+export function getCoreAcpToolNames(
+	selectedToolIds: ReadonlySet<string>,
+	context: BuiltinToolAvailabilityContext = {},
+): string[] {
+	return getCoreHeadlessToolNames(selectedToolIds, context);
+}

package/src/{tools → extensions/tools}/schemas.ts

@@ -228,10 +228,12 @@ export const ApplyPatchInputSchema = z
 		input: z
 			.string()
 			.min(1)
-			.describe("The apply_patch text payload, including patch instructions"),
+			.describe(
+				"The freeform apply_patch payload in the canonical patch grammar (e.g *** Begin Patch, *** Update File:, @@, and *** End Patch).",
+			),
 	})
 	.describe(
-		"Modify or create a text file by applying patches. Prefer using this tool for file edits over shell commands. IMPORTANT: large patches can time out, so use small chunks and multiple calls when possible.",
+		"Modify or create a text file by applying patches using the canonical apply_patch diff grammar. Prefer sending the patch body directly rather than wrapping it in shell syntax. IMPORTANT: large patches can time out, so use small chunks and multiple calls when possible.",
 	);
 export const ApplyPatchInputUnionSchema = z.union([
 	ApplyPatchInputSchema,

package/src/{team → extensions/tools/team}/multi-agent.ts

@@ -138,6 +138,23 @@ export interface SpawnTeammateOptions {
 	config: TeamMemberConfig;
 }
 
+function isAbortLikeError(error: unknown): boolean {
+	if (
+		typeof DOMException !== "undefined" &&
+		error instanceof DOMException &&
+		error.name === "AbortError"
+	) {
+		return true;
+	}
+	if (!(error instanceof Error)) {
+		return false;
+	}
+	return (
+		error.name === "AbortError" ||
+		error.message.toLowerCase().includes("aborted")
+	);
+}
+
 // =============================================================================
 // AgentTeam
 // =============================================================================
@@ -484,6 +501,7 @@ interface TeamMemberState extends TeamMemberSnapshot {
 	runningCount: number;
 	lastMissionStep: number;
 	lastMissionAt: number;
+	pendingSteerMessage?: string;
 }
 
 export class AgentTeamsRuntime {
@@ -568,8 +586,6 @@ export class AgentTeamsRuntime {
 	listTaskItems(options?: {
 		status?: TeamTaskStatus;
 		assignee?: string;
-		unassignedOnly?: boolean;
-		readyOnly?: boolean;
 	}): TeamTaskListItem[] {
 		return Array.from(this.tasks.values())
 			.map((task) => {
@@ -590,12 +606,6 @@ export class AgentTeamsRuntime {
 				if (options?.assignee && task.assignee !== options.assignee) {
 					return false;
 				}
-				if (options?.unassignedOnly && !!task.assignee) {
-					return false;
-				}
-				if (options?.readyOnly && !task.isReady) {
-					return false;
-				}
 				return true;
 			});
 	}
@@ -825,6 +835,15 @@ export class AgentTeamsRuntime {
 		const wrappedConfig: TeamMemberConfig = {
 			...config,
 			apiTimeoutMs: TEAMMATE_API_TIMEOUT_MS,
+			consumePendingUserMessage: () => {
+				const member = this.members.get(agentId);
+				if (!member || !member.pendingSteerMessage) {
+					return undefined;
+				}
+				const message = member.pendingSteerMessage;
+				member.pendingSteerMessage = undefined;
+				return message;
+			},
 			onEvent: (event: AgentEvent) => {
 				config.onEvent?.(event);
 				this.emitEvent({ type: TeamMessageType.AgentEvent, agentId, event });
@@ -870,7 +889,13 @@ export class AgentTeamsRuntime {
 		if (!member || member.role !== "teammate") {
 			throw new Error(`Teammate "${agentId}" was not found`);
 		}
-		member.agent?.abort();
+		try {
+			member.agent?.abort();
+		} catch (error) {
+			if (!isAbortLikeError(error)) {
+				throw error;
+			}
+		}
 		member.status = "stopped";
 		this.emitEvent({ type: TeamMessageType.TeammateShutdown, agentId, reason });
 	}
@@ -986,9 +1011,17 @@ export class AgentTeamsRuntime {
 		this.emitEvent({ type: TeamMessageType.TaskStart, agentId, message });
 
 		try {
+			const unreadMail = this.listMailbox(agentId, {
+				unreadOnly: true,
+				markRead: true,
+			});
+			const enrichedMessage =
+				unreadMail.length > 0
+					? `${this.buildMailboxNotification(unreadMail)}\n\n${message}`
+					: message;
 			const result = options?.continueConversation
-				? await member.agent.continue(message)
-				: await member.agent.run(message);
+				? await member.agent.continue(enrichedMessage)
+				: await member.agent.run(enrichedMessage);
 			this.emitEvent({ type: TeamMessageType.TaskEnd, agentId, result });
 			this.recordProgressStep(
 				agentId,
@@ -1254,7 +1287,8 @@ export class AgentTeamsRuntime {
 		if (!this.members.has(fromAgentId)) {
 			throw new Error(`Unknown sender "${fromAgentId}"`);
 		}
-		if (!this.members.has(toAgentId)) {
+		const recipient = this.members.get(toAgentId);
+		if (!recipient) {
 			throw new Error(`Unknown recipient "${toAgentId}"`);
 		}
 		const message: TeamMailboxMessage = {
@@ -1272,6 +1306,13 @@ export class AgentTeamsRuntime {
 			type: TeamMessageType.TeamMessage,
 			message: { ...message },
 		});
+		if (
+			recipient.role === "teammate" &&
+			recipient.runningCount > 0 &&
+			recipient.agent
+		) {
+			recipient.pendingSteerMessage = `[MAILBOX] You got a message from ${fromAgentId}. Subject: "${subject}". Use the team_read_mailbox tool to read it at your convenience.`;
+		}
 		return { ...message };
 	}
 
@@ -1279,15 +1320,14 @@ export class AgentTeamsRuntime {
 		fromAgentId: string,
 		subject: string,
 		body: string,
-		options?: { includeLead?: boolean; taskId?: string },
+		options?: { taskId?: string },
 	): TeamMailboxMessage[] {
-		const includeLead = options?.includeLead ?? false;
 		const messages: TeamMailboxMessage[] = [];
 		for (const member of this.members.values()) {
 			if (member.agentId === fromAgentId) {
 				continue;
 			}
-			if (!includeLead && member.role === "lead") {
+			if (member.role === "lead") {
 				continue;
 			}
 			messages.push(
@@ -1458,7 +1498,13 @@ export class AgentTeamsRuntime {
 
 		for (const member of this.members.values()) {
 			if (member.role === "teammate") {
-				member.agent?.abort();
+				try {
+					member.agent?.abort();
+				} catch (error) {
+					if (!isAbortLikeError(error)) {
+						throw error;
+					}
+				}
 			}
 		}
 
@@ -1526,7 +1572,7 @@ export class AgentTeamsRuntime {
 			this.appendMissionLog({
 				agentId,
 				kind: "done",
-				summary: `Run completed after ${event.iterations} iteration(s)`,
+				summary: `Completed a delegated run (${event.iterations} iterations)`,
 			});
 			return;
 		}
@@ -1638,6 +1684,23 @@ export class AgentTeamsRuntime {
 		});
 	}
 
+	private buildMailboxNotification(messages: TeamMailboxMessage[]): string {
+		if (messages.length === 0) {
+			return "";
+		}
+		const lines: string[] = [
+			`[MAILBOX] You have ${messages.length} unread message(s):`,
+		];
+		for (const msg of messages) {
+			lines.push(
+				`--- Message from ${msg.fromAgentId} | subject: ${msg.subject} ---`,
+			);
+			lines.push(msg.body);
+		}
+		lines.push("---");
+		return lines.join("\n");
+	}
+
 	private emitEvent(event: TeamEvent): void {
 		try {
 			this.onTeamEvent?.(event);

package/src/{team → extensions/tools/team}/spawn-agent-tool.ts

@@ -32,12 +32,6 @@ export const SpawnAgentInputSchema = z.object({
 		.string()
 		.describe("System prompt defining the sub-agent's behavior"),
 	task: z.string().describe("Task for the sub-agent to complete"),
-	maxIterations: z
-		.number()
-		.int()
-		.min(1)
-		.optional()
-		.describe("Max iterations for the sub-agent"),
 });
 
 export type SpawnAgentInput = z.infer<typeof SpawnAgentInputSchema>;
@@ -136,7 +130,7 @@ export function createSpawnAgentTool(
 				prompt: input.systemPrompt,
 				configProvider: config.configProvider,
 				tools,
-				maxIterations: input.maxIterations ?? config.defaultMaxIterations,
+				maxIterations: config.defaultMaxIterations,
 				parentAgentId: context.agentId,
 				abortSignal: context.abortSignal,
 				onEvent: config.onSubAgentEvent,

package/src/{team → extensions/tools/team}/subagent-prompts.ts

@@ -11,7 +11,7 @@ export function buildTeammateSystemPrompt(
 	}
 
 	return buildClineSystemPrompt({
-		ide: config.clineIdeName?.trim() || "Terminal Shell",
+		ide: config.clineIdeName?.trim() || "Terminal",
 		workspaceRoot: config.cwd?.trim() || "/",
 		providerId: config.providerId,
 		rules: `# Team Teammate Role\n${trimmedPrompt}`,
@@ -31,7 +31,7 @@ export function buildSubAgentSystemPrompt(
 	}
 
 	return buildClineSystemPrompt({
-		ide: "Terminal Shell",
+		ide: config.clineIdeName || "Terminal",
 		workspaceRoot: config.cwd?.trim() || "/",
 		providerId: config.providerId,
 		overridePrompt: trimmedPrompt,