@clinebot/core 0.0.35 → 0.0.37

package/src/extensions/plugin/plugin-sandbox.ts

@@ -2,17 +2,48 @@ import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import type { AgentConfig, HookStage, Tool } from "@clinebot/shared";
+import type {
+	AgentConfig,
+	AgentExtensionAutomationEventType,
+	HookStage,
+	Message,
+	PluginSetupContext,
+	Tool,
+	WorkspaceInfo,
+} from "@clinebot/shared";
 import { SubprocessSandbox } from "../../runtime/subprocess-sandbox";
 import type { PluginLoadDiagnostics } from "./plugin-load-report";
+import type { PluginTargeting } from "./plugin-targeting";
 
-export interface PluginSandboxOptions {
+export type SandboxedPluginSetupContext = Pick<
+	PluginSetupContext,
+	"session" | "client" | "user" | "workspaceInfo" | "logger"
+>;
+
+export interface PluginSandboxOptions extends PluginTargeting {
 	pluginPaths: string[];
 	exportName?: string;
 	importTimeoutMs?: number;
 	hookTimeoutMs?: number;
 	contributionTimeoutMs?: number;
 	onEvent?: (event: { name: string; payload?: unknown }) => void;
+	/**
+	 * The session's working directory. Forwarded to the sandbox subprocess so
+	 * that `process.cwd()` returns the correct path inside the sandbox even
+	 * when `--cwd` was passed without calling `process.chdir()` on the host.
+	 */
+	cwd?: string;
+	/**
+	 * Structured workspace and git metadata (branch, commit, remotes) generated
+	 * at session startup. Forwarded to plugins via PluginSetupCtx.workspaceInfo
+	 * so they can inspect git state without running their own commands.
+	 */
+	workspaceInfo?: WorkspaceInfo;
+	session?: SandboxedPluginSetupContext["session"];
+	client?: SandboxedPluginSetupContext["client"];
+	user?: SandboxedPluginSetupContext["user"];
+	/** Enables a logger bridge that forwards sandbox log calls to the host. */
+	logger?: SandboxedPluginSetupContext["logger"];
 }
 
 type AgentExtension = NonNullable<AgentConfig["extensions"]>[number];
@@ -25,11 +56,14 @@ type SandboxedContributionDescriptor = {
 	inputSchema?: unknown;
 	timeoutMs?: number;
 	retryable?: boolean;
-	value?: string;
-	defaultValue?: boolean | string | number;
 	metadata?: Record<string, unknown>;
 };
 
+type SandboxedAutomationEventTypeDescriptor =
+	AgentExtensionAutomationEventType & {
+		id: string;
+	};
+
 type SandboxedPluginDescriptor = {
 	pluginId: string;
 	pluginPath: string;
@@ -38,10 +72,11 @@ type SandboxedPluginDescriptor = {
 	contributions: {
 		tools: SandboxedContributionDescriptor[];
 		commands: SandboxedContributionDescriptor[];
-		shortcuts: SandboxedContributionDescriptor[];
-		flags: SandboxedContributionDescriptor[];
 		messageBuilders: SandboxedContributionDescriptor[];
 		providers: SandboxedContributionDescriptor[];
+		automationEventTypes: SandboxedAutomationEventTypeDescriptor[];
+		shortcuts?: SandboxedContributionDescriptor[];
+		flags?: SandboxedContributionDescriptor[];
 	};
 };
 
@@ -49,6 +84,24 @@ type SandboxedInitializeResult = {
 	plugins: SandboxedPluginDescriptor[];
 } & PluginLoadDiagnostics;
 
+function normalizeDescriptor(
+	descriptor: SandboxedPluginDescriptor,
+): SandboxedPluginDescriptor {
+	return {
+		...descriptor,
+		contributions: {
+			tools: descriptor.contributions?.tools ?? [],
+			commands: descriptor.contributions?.commands ?? [],
+			messageBuilders: descriptor.contributions?.messageBuilders ?? [],
+			providers: descriptor.contributions?.providers ?? [],
+			automationEventTypes:
+				descriptor.contributions?.automationEventTypes ?? [],
+			shortcuts: descriptor.contributions?.shortcuts ?? [],
+			flags: descriptor.contributions?.flags ?? [],
+		},
+	};
+}
+
 function isUnknownPluginIdError(error: unknown): boolean {
 	const message = error instanceof Error ? error.message : String(error);
 	return message.includes("Unknown sandbox plugin id:");
@@ -113,6 +166,21 @@ const HOOK_BINDINGS: Array<{
 		extensionKey: "onSessionStart",
 		sandboxHookName: "onSessionStart",
 	},
+	{
+		stage: "run_start",
+		extensionKey: "onRunStart",
+		sandboxHookName: "onRunStart",
+	},
+	{
+		stage: "iteration_start",
+		extensionKey: "onIterationStart",
+		sandboxHookName: "onIterationStart",
+	},
+	{
+		stage: "turn_start",
+		extensionKey: "onTurnStart",
+		sandboxHookName: "onTurnStart",
+	},
 	{
 		stage: "before_agent_start",
 		extensionKey: "onBeforeAgentStart",
@@ -133,6 +201,21 @@ const HOOK_BINDINGS: Array<{
 		extensionKey: "onTurnEnd",
 		sandboxHookName: "onTurnEnd",
 	},
+	{
+		stage: "stop_error",
+		extensionKey: "onAgentError",
+		sandboxHookName: "onAgentError",
+	},
+	{
+		stage: "iteration_end",
+		extensionKey: "onIterationEnd",
+		sandboxHookName: "onIterationEnd",
+	},
+	{
+		stage: "run_end",
+		extensionKey: "onRunEnd",
+		sandboxHookName: "onRunEnd",
+	},
 	{
 		stage: "session_shutdown",
 		extensionKey: "onSessionShutdown",
@@ -181,6 +264,14 @@ export async function loadSandboxedPlugins(
 	const initArgs = {
 		pluginPaths: options.pluginPaths,
 		exportName: options.exportName,
+		providerId: options.providerId,
+		modelId: options.modelId,
+		cwd: options.cwd,
+		session: options.session,
+		client: options.client,
+		user: options.user,
+		workspaceInfo: options.workspaceInfo,
+		loggerEnabled: Boolean(options.logger),
 	};
 
 	// Guard against concurrent re-initialization when multiple tools/hooks
@@ -208,7 +299,7 @@ export async function loadSandboxedPlugins(
 		});
 		throw error;
 	}
-	const descriptors = initialized.plugins;
+	const descriptors = initialized.plugins.map(normalizeDescriptor);
 
 	const extensions: NonNullable<AgentConfig["extensions"]> = descriptors.map(
 		(descriptor) => {
@@ -230,6 +321,13 @@ export async function loadSandboxedPlugins(
 						contributionTimeoutMs,
 						reinitialize,
 					);
+					registerMessageBuilders(
+						api,
+						sandbox,
+						descriptor,
+						contributionTimeoutMs,
+						reinitialize,
+					);
 					registerSimpleContributions(api, descriptor);
 				},
 			};
@@ -267,7 +365,7 @@ function registerTools(
 	timeoutMs: number,
 	reinitialize: () => Promise<void>,
 ): void {
-	for (const td of descriptor.contributions.tools) {
+	for (const td of descriptor.contributions?.tools ?? []) {
 		const tool: Tool = {
 			name: td.name,
 			description: td.description ?? "",
@@ -318,7 +416,7 @@ function registerCommands(
 	timeoutMs: number,
 	reinitialize: () => Promise<void>,
 ): void {
-	for (const cd of descriptor.contributions.commands) {
+	for (const cd of descriptor.contributions?.commands ?? []) {
 		api.registerCommand({
 			name: cd.name,
 			description: cd.description,
@@ -357,36 +455,82 @@ function registerSimpleContributions(
 	api: AgentExtensionApi,
 	descriptor: SandboxedPluginDescriptor,
 ): void {
-	for (const sd of descriptor.contributions.shortcuts) {
-		api.registerShortcut({
-			name: sd.name,
-			value: sd.value ?? "",
-			description: sd.description,
+	for (const pd of descriptor.contributions?.providers ?? []) {
+		api.registerProvider({
+			name: pd.name,
+			description: pd.description,
+			metadata: pd.metadata,
 		});
 	}
 
-	for (const fd of descriptor.contributions.flags) {
-		api.registerFlag({
-			name: fd.name,
-			description: fd.description,
-			defaultValue: fd.defaultValue,
+	for (const eventType of descriptor.contributions?.automationEventTypes ??
+		[]) {
+		api.registerAutomationEventType({
+			eventType: eventType.eventType,
+			source: eventType.source,
+			description: eventType.description,
+			attributesSchema: eventType.attributesSchema,
+			payloadSchema: eventType.payloadSchema,
+			examples: eventType.examples,
+			metadata: eventType.metadata,
 		});
 	}
+}
 
-	for (const rd of descriptor.contributions.messageBuilders) {
+function registerMessageBuilders(
+	api: AgentExtensionApi,
+	sandbox: SubprocessSandbox,
+	descriptor: SandboxedPluginDescriptor,
+	timeoutMs: number,
+	reinitialize: () => Promise<void>,
+): void {
+	for (const bd of descriptor.contributions?.messageBuilders ?? []) {
 		api.registerMessageBuilder({
-			name: rd.name,
-			build: (m) => m,
+			name: bd.name,
+			async build(messages) {
+				try {
+					const result = await sandbox.call<unknown[]>(
+						"buildMessages",
+						{
+							pluginId: descriptor.pluginId,
+							contributionId: bd.id,
+							messages,
+						},
+						{ timeoutMs },
+					);
+					return isMessageArray(result) ? result : messages;
+				} catch (error) {
+					if (!isUnknownPluginIdError(error)) {
+						throw error;
+					}
+					await reinitialize();
+					const result = await sandbox.call<unknown[]>(
+						"buildMessages",
+						{
+							pluginId: descriptor.pluginId,
+							contributionId: bd.id,
+							messages,
+						},
+						{ timeoutMs },
+					);
+					return isMessageArray(result) ? result : messages;
+				}
+			},
 		});
 	}
+}
 
-	for (const pd of descriptor.contributions.providers) {
-		api.registerProvider({
-			name: pd.name,
-			description: pd.description,
-			metadata: pd.metadata,
-		});
-	}
+function isMessageArray(value: unknown): value is Message[] {
+	return (
+		Array.isArray(value) &&
+		value.every(
+			(entry) =>
+				typeof entry === "object" &&
+				entry !== null &&
+				"role" in entry &&
+				"content" in entry,
+		)
+	);
 }
 
 function makeHookHandler(

package/src/extensions/plugin/plugin-targeting.ts

@@ -0,0 +1,32 @@
+import type { PluginManifest } from "@clinebot/shared";
+
+export interface PluginTargeting {
+	providerId?: string;
+	modelId?: string;
+}
+
+export function matchesPluginManifestTargeting(
+	manifest: PluginManifest | undefined,
+	targeting: PluginTargeting | undefined,
+): boolean {
+	if (!manifest) {
+		return true;
+	}
+
+	if (manifest.providerIds?.length) {
+		if (
+			!targeting?.providerId ||
+			!manifest.providerIds.includes(targeting.providerId)
+		) {
+			return false;
+		}
+	}
+
+	if (manifest.modelIds?.length) {
+		if (!targeting?.modelId || !manifest.modelIds.includes(targeting.modelId)) {
+			return false;
+		}
+	}
+
+	return true;
+}

package/src/extensions/tools/constants.ts

@@ -18,6 +18,7 @@ export const DefaultToolNames = {
 	EDITOR: "editor",
 	SKILLS: "skills",
 	ASK: "ask_question",
+	SUBMIT_AND_EXIT: "submit_and_exit",
 } as const;
 
 /**
@@ -32,4 +33,5 @@ export const ALL_DEFAULT_TOOL_NAMES: DefaultToolName[] = [
 	DefaultToolNames.EDITOR,
 	DefaultToolNames.SKILLS,
 	DefaultToolNames.ASK,
+	DefaultToolNames.SUBMIT_AND_EXIT,
 ];

package/src/extensions/tools/definitions.ts

@@ -15,6 +15,7 @@ import {
 	formatReadFileQuery,
 	formatRunCommandQuery,
 	getEditorSizeError,
+	getReadFileRangeError,
 	normalizeReadFileRequests,
 	normalizeRunCommandsInput,
 	withTimeout,
@@ -92,6 +93,16 @@ export function createReadFilesTool(
 
 			return Promise.all(
 				requests.map(async (request): Promise<ToolOperationResult> => {
+					const rangeError = getReadFileRangeError(request);
+					if (rangeError) {
+						return {
+							query: formatReadFileQuery(request),
+							result: "",
+							error: `Invalid file range: ${rangeError}`,
+							success: false,
+						};
+					}
+
 					try {
 						const content = await withTimeout(
 							executor(request, context),
@@ -206,16 +217,23 @@ export function createBashTool(
 		maxRetries: 0,
 		execute: async (input, context) => {
 			const validate = validateWithZod(RunCommandsInputUnionSchema, input);
-			const commands = Array.isArray(validate)
-				? validate
-				: typeof validate === "object"
-					? Array.isArray(validate.commands)
-						? validate.commands
-						: [validate.commands]
-					: [validate];
+			let commands: string[];
+			if (typeof validate === "string") {
+				commands = [validate];
+			} else if (Array.isArray(validate)) {
+				commands = validate;
+			} else if ("commands" in validate) {
+				commands = Array.isArray(validate.commands)
+					? validate.commands
+					: [validate.commands];
+			} else if ("command" in validate) {
+				commands = [validate.command];
+			} else {
+				commands = [validate.cmd];
+			}
 
 			return Promise.all(
-				commands.map(async (command): Promise<ToolOperationResult> => {
+				commands.map(async (command: string): Promise<ToolOperationResult> => {
 					try {
 						const output = await withTimeout(
 							executor(command, cwd, context),
@@ -350,67 +368,48 @@ export function createWebFetchTool(
 	});
 }
 
-const APPLY_PATCH_TOOL_DESC = `This is a custom utility that makes it more convenient to add, remove, move, or edit code in a single file. \`apply_patch\` effectively allows you to execute a diff/patch against a file, but the format of the diff specification is unique to this task, so pay careful attention to these instructions. To use the \`apply_patch\` command, you should pass a message of the following structure as "input":
+const APPLY_PATCH_TOOL_DESC = `Use \`apply_patch\` to edit files with the canonical freeform patch grammar. Pass the patch text directly as the \`input\` string. Prefer the exact format below:
 
-%%bash
-apply_patch <<"EOF"
 *** Begin Patch
-[YOUR_PATCH]
+*** Update File: path/to/file.ts
+@@ optional section marker
+ [context before]
+-[old line]
++[new line]
+ [context after]
 *** End Patch
-EOF
-
-Where [YOUR_PATCH] is the actual content of your patch, specified in the following V4A diff format.
 
-*** [ACTION] File: [path/to/file] -> ACTION can be one of Add, Update, or Delete. 
+Supported actions:
+- \`*** Add File: <path>\`
+- \`*** Update File: <path>\`
+- \`*** Delete File: <path>\`
+- optional \`*** Move to: <new path>\` immediately after an Update File header
 
-In a Add File section, every line of the new file (including blank/empty lines) MUST start with a \`+\` prefix. Do not include any unprefixed lines inside an Add section
-In a Update/Delete section, repeat the following for each snippet of code that needs to be changed:
-[context_before] -> See below for further instructions on context.
-- [old_code] -> Precede the old code with a minus sign.
-+ [new_code] -> Precede the new, replacement code with a plus sign.
-[context_after] -> See below for further instructions on context.
+Rules:
+- In an Add File section, every file-content line must start with \`+\`.
+- In an Update section, use context lines plus \`-\` and \`+\` lines to describe the change.
+- Use \`@@\` markers when extra context is needed to disambiguate repeated code blocks.
+- Do not use line numbers; this format is context-based.
+- Prefer sending the patch body directly. Legacy shell wrappers such as \`%%bash\` and \`apply_patch <<"EOF"\` are accepted for compatibility but are not preferred.
 
-For instructions on [context_before] and [context_after]:
-- By default, show 3 lines of code immediately above and 3 lines immediately below each change. If a change is within 3 lines of a previous change, do NOT duplicate the first change’s [context_after] lines in the second change’s [context_before] lines.
-- If 3 lines of context is insufficient to uniquely identify the snippet of code within the file, use the @@ operator to indicate the class or function to which the snippet belongs. For instance, we might have:
-@@ class BaseClass
-[3 lines of pre-context]
-- [old_code]
-+ [new_code]
-[3 lines of post-context]
+Example:
 
-- If a code block is repeated so many times in a class or function such that even a single @@ statement and 3 lines of context cannot uniquely identify the snippet of code, you can use multiple \`@@\` statements to jump to the right context. For instance:
-
-@@ class BaseClass
-@@ 	def method():
-[3 lines of pre-context]
-- [old_code]
-+ [new_code]
-[3 lines of post-context]
-
-Note, then, that we do not use line numbers in this diff format, as the context is enough to uniquely identify code. An example of a message that you might pass as "input" to this function, in order to apply a patch, is shown below.
-
-%%bash
-apply_patch <<"EOF"
 *** Begin Patch
-*** Update File: pygorithm/searching/binary_search.py
-@@ class BaseClass
-@@     def search():
--          pass
-+          raise NotImplementedError()
-
-@@ class Subclass
-@@     def search():
--          pass
-+          raise NotImplementedError()
-
-*** End Patch
-EOF`;
+*** Update File: src/page.tsx
+@@
+   return (
+     <div>
+       <button onClick={() => console.log("clicked")}>Click me</button>
++      <button onClick={() => console.log("cancel clicked")}>Cancel</button>
+     </div>
+   );
+ }
+*** End Patch`;
 
 /**
  * Create the apply_patch tool
  *
- * Applies the legacy Cline patch format to one or more files.
+ * Applies the canonical apply_patch format to one or more files.
  */
 export function createApplyPatchTool(
 	executor: ApplyPatchExecutor,
@@ -583,11 +582,8 @@ export function createSkillsTool(
  */
 export function createAskQuestionTool(
 	executor: AskQuestionExecutor,
-	config: Pick<DefaultToolsConfig, "askQuestionTimeoutMs"> = {},
 ): Tool<AskQuestionInput, string> {
-	const timeoutMs = config.askQuestionTimeoutMs ?? 15000;
-
-	return createTool<AskQuestionInput, string>({
+	return {
 		name: "ask_question",
 		description:
 			"Ask user a question for clarifying or gathering information needed to complete the task. " +
@@ -596,18 +592,13 @@ export function createAskQuestionTool(
 			"Provide an array of 2-5 options for the user to choose from. " +
 			"Never include an option to toggle to Act mode.",
 		inputSchema: zodToJsonSchema(AskQuestionInputSchema),
-		timeoutMs,
 		retryable: false,
 		maxRetries: 0,
 		execute: async (input, context) => {
 			const validatedInput = validateWithZod(AskQuestionInputSchema, input);
-			return withTimeout(
-				executor(validatedInput.question, validatedInput.options, context),
-				timeoutMs,
-				`ask_question timed out after ${timeoutMs}ms`,
-			);
+			return executor(validatedInput.question, validatedInput.options, context);
 		},
-	});
+	};
 }
 
 export function createSubmitAndExitTool(
@@ -651,8 +642,7 @@ export function createSubmitAndExitTool(
  *
  * @example
  * ```typescript
- * import { Agent } from "@clinebot/agents"
- * import { createDefaultTools } from "@clinebot/core"
+ * import { Agent, createDefaultTools } from "@clinebot/core"
  * import * as fs from "fs/promises"
  * import { exec } from "child_process"
  *
@@ -738,7 +728,7 @@ export function createDefaultTools(options: CreateDefaultToolsOptions): Tool[] {
 
 	// Add ask_question tool if enabled and executor provided
 	if (enableAskQuestion && executors.askQuestion) {
-		tools.push(createAskQuestionTool(executors.askQuestion, config));
+		tools.push(createAskQuestionTool(executors.askQuestion));
 	} else if (enableSubmitAndExit && executors.submit) {
 		// Add submit_and_exit tool if enabled and executor provided
 		tools.push(createSubmitAndExitTool(executors.submit, config));