@clinebot/core 0.0.34 → 0.0.36

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

@@ -4,13 +4,18 @@
  * This file runs inside an isolated Node.js child process spawned by
  * {@link SubprocessSandbox}. It receives RPC calls over IPC and dynamically
  * imports plugin modules, wiring up their contributions (tools, commands,
- * shortcuts, flags, renderers, providers) and lifecycle hooks.
+ * message builders, providers) and lifecycle hooks.
  *
  * Because it executes in a separate process it must stay bundle-safe and only
  * depend on local helpers that can be inlined into the sandbox build.
  */
 
+import { normalizePluginManifest, type PluginManifest } from "@clinebot/shared";
 import { importPluginModule } from "./plugin-module-import";
+import {
+	matchesPluginManifestTargeting,
+	type PluginTargeting,
+} from "./plugin-targeting";
 
 // ---------------------------------------------------------------------------
 // Types (intentionally minimal – mirrors only what the RPC protocol needs)
@@ -31,18 +36,6 @@ interface PluginCommand {
 	handler?: (input: string) => Promise<string>;
 }
 
-interface PluginShortcut {
-	name: string;
-	value: string;
-	description?: string;
-}
-
-interface PluginFlag {
-	name: string;
-	description?: string;
-	defaultValue?: boolean | string | number;
-}
-
 interface PluginMessageBuilder {
 	name: string;
 	build: (message: unknown[]) => unknown[]; // Message[]
@@ -57,16 +50,18 @@ interface PluginProvider {
 interface PluginApi {
 	registerTool(tool: PluginTool): void;
 	registerCommand(command: PluginCommand): void;
-	registerShortcut(shortcut: PluginShortcut): void;
-	registerFlag(flag: PluginFlag): void;
 	registerMessageBuilder(builder: PluginMessageBuilder): void;
 	registerProvider(provider: PluginProvider): void;
 }
 
+interface PluginSetupCtx {
+	workspaceInfo?: unknown;
+}
+
 interface PluginModule {
 	name: string;
-	manifest: Record<string, unknown>;
-	setup?: (api: PluginApi) => void | Promise<void>;
+	manifest: PluginManifest;
+	setup?: (api: PluginApi, ctx: PluginSetupCtx) => void | Promise<void>;
 	[hookName: string]: unknown;
 }
 
@@ -86,14 +81,14 @@ interface PluginDescriptor {
 	pluginId: string;
 	pluginPath: string;
 	name: string;
-	manifest: Record<string, unknown>;
+	manifest: PluginManifest;
 	contributions: {
 		tools: ContributionDescriptor[];
 		commands: ContributionDescriptor[];
-		shortcuts: ContributionDescriptor[];
-		flags: ContributionDescriptor[];
 		messageBuilders: ContributionDescriptor[];
 		providers: ContributionDescriptor[];
+		shortcuts?: ContributionDescriptor[];
+		flags?: ContributionDescriptor[];
 	};
 }
 
@@ -132,6 +127,12 @@ function isObject(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null;
 }
 
+function hasValidStringArray(value: unknown): value is string[] {
+	return (
+		Array.isArray(value) && value.every((entry) => typeof entry === "string")
+	);
+}
+
 function assertValidPluginModule(
 	plugin: unknown,
 	pluginPath: string,
@@ -145,6 +146,29 @@ function assertValidPluginModule(
 	if (!isObject(plugin.manifest)) {
 		throw new Error(`Invalid plugin manifest: ${pluginPath}`);
 	}
+	if (
+		Object.hasOwn(plugin.manifest, "providerIds") &&
+		!hasValidStringArray(plugin.manifest.providerIds)
+	) {
+		throw new Error(`Invalid plugin manifest.providerIds: ${pluginPath}`);
+	}
+	if (
+		Object.hasOwn(plugin.manifest, "modelIds") &&
+		!hasValidStringArray(plugin.manifest.modelIds)
+	) {
+		throw new Error(`Invalid plugin manifest.modelIds: ${pluginPath}`);
+	}
+}
+
+function assertValidPluginSetupCtx(
+	ctx: unknown,
+): asserts ctx is PluginSetupCtx {
+	if (!isObject(ctx)) {
+		throw new Error("Plugin setup context must be an object");
+	}
+	if (ctx.workspaceInfo !== undefined && !isObject(ctx.workspaceInfo)) {
+		throw new Error("Plugin setup context workspaceInfo must be an object");
+	}
 }
 
 // ---------------------------------------------------------------------------
@@ -183,6 +207,16 @@ function emitEvent(name: string, payload?: unknown): void {
 // Expose event emitter to plugins.
 (globalThis as Record<string, unknown>).__clinePluginHost = { emitEvent };
 
+/**
+ * Session workspace env — populated by `initialize()` and available to any
+ * plugin code that executes before the setup hook, or cannot use hook context.
+ * Prefer using PluginSetupCtx from the setup function when possible.
+ */
+(globalThis as Record<string, unknown>).__clineSessionEnv = {
+	cwd: undefined as string | undefined,
+	workspaceInfo: undefined as unknown,
+};
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -214,16 +248,44 @@ function getPlugin(pluginId: string): PluginState {
 async function initialize(args: {
 	pluginPaths?: string[];
 	exportName?: string;
+	providerId?: string;
+	modelId?: string;
+	cwd?: string;
+	workspaceInfo?: unknown;
 }): Promise<InitializeResult> {
 	pluginState.clear();
 	pluginCounter = 0;
 	contributionCounters.clear();
 
+	// Apply the session's working directory so that process.cwd() and relative
+	// path resolution inside plugins reflect the correct workspace, not the
+	// host process's cwd (which may differ when --cwd was used without calling
+	// process.chdir() on the host side).
+	if (args.cwd) {
+		try {
+			process.chdir(args.cwd);
+		} catch {
+			// Ignore — best-effort; path may not exist in unusual environments.
+		}
+	}
+
+	// Keep the global escape-hatch in sync with the active session.
+	const sessionEnv = (globalThis as Record<string, unknown>)
+		.__clineSessionEnv as Record<string, unknown>;
+	if (sessionEnv) {
+		sessionEnv.cwd = args.cwd;
+		sessionEnv.workspaceInfo = args.workspaceInfo;
+	}
+
 	const descriptors: PluginDescriptor[] = [];
 	const failures: PluginInitializationFailure[] = [];
 	const warnings: PluginInitializationWarning[] = [];
 	const exportName = args.exportName || "plugin";
 	const pluginIndexByName = new Map<string, number>();
+	const targeting: PluginTargeting = {
+		providerId: args.providerId,
+		modelId: args.modelId,
+	};
 
 	for (const pluginPath of args.pluginPaths || []) {
 		let plugin: PluginModule | undefined;
@@ -232,15 +294,19 @@ async function initialize(args: {
 			plugin = (moduleExports.default ??
 				moduleExports[exportName]) as unknown as PluginModule;
 			assertValidPluginModule(plugin, pluginPath);
+			plugin.manifest = normalizePluginManifest(plugin.manifest);
+			if (!matchesPluginManifestTargeting(plugin.manifest, targeting)) {
+				continue;
+			}
 
 			const pluginId = `plugin_${++pluginCounter}`;
 			const contributions: PluginDescriptor["contributions"] = {
 				tools: [],
 				commands: [],
-				shortcuts: [],
-				flags: [],
 				messageBuilders: [],
 				providers: [],
+				shortcuts: [],
+				flags: [],
 			};
 			const handlers: PluginState["handlers"] = {
 				tools: new Map(),
@@ -272,22 +338,6 @@ async function initialize(args: {
 						description: command.description,
 					});
 				},
-				registerShortcut: (shortcut) => {
-					contributions.shortcuts.push({
-						id: makeId(pluginId, "shortcut"),
-						name: shortcut.name,
-						value: shortcut.value,
-						description: shortcut.description,
-					});
-				},
-				registerFlag: (flag) => {
-					contributions.flags.push({
-						id: makeId(pluginId, "flag"),
-						name: flag.name,
-						description: flag.description,
-						defaultValue: flag.defaultValue,
-					});
-				},
 				registerMessageBuilder: (builder) => {
 					const id = makeId(pluginId, "builder");
 					handlers.messageBuilders.set(id, builder.build);
@@ -305,7 +355,11 @@ async function initialize(args: {
 
 			if (typeof plugin.setup === "function") {
 				try {
-					await plugin.setup(api);
+					const setupCtx = {
+						workspaceInfo: args.workspaceInfo,
+					};
+					assertValidPluginSetupCtx(setupCtx);
+					await plugin.setup(api, setupCtx);
 				} catch (error) {
 					failures.push({
 						pluginPath,

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

@@ -2,17 +2,35 @@ 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,
+	HookStage,
+	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 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;
 }
 
 type AgentExtension = NonNullable<AgentConfig["extensions"]>[number];
@@ -25,8 +43,6 @@ type SandboxedContributionDescriptor = {
 	inputSchema?: unknown;
 	timeoutMs?: number;
 	retryable?: boolean;
-	value?: string;
-	defaultValue?: boolean | string | number;
 	metadata?: Record<string, unknown>;
 };
 
@@ -38,10 +54,10 @@ type SandboxedPluginDescriptor = {
 	contributions: {
 		tools: SandboxedContributionDescriptor[];
 		commands: SandboxedContributionDescriptor[];
-		shortcuts: SandboxedContributionDescriptor[];
-		flags: SandboxedContributionDescriptor[];
 		messageBuilders: SandboxedContributionDescriptor[];
 		providers: SandboxedContributionDescriptor[];
+		shortcuts?: SandboxedContributionDescriptor[];
+		flags?: SandboxedContributionDescriptor[];
 	};
 };
 
@@ -49,6 +65,22 @@ 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 ?? [],
+			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:");
@@ -181,6 +213,10 @@ export async function loadSandboxedPlugins(
 	const initArgs = {
 		pluginPaths: options.pluginPaths,
 		exportName: options.exportName,
+		providerId: options.providerId,
+		modelId: options.modelId,
+		cwd: options.cwd,
+		workspaceInfo: options.workspaceInfo,
 	};
 
 	// Guard against concurrent re-initialization when multiple tools/hooks
@@ -208,7 +244,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) => {
@@ -267,7 +303,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 +354,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,30 +393,14 @@ 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 fd of descriptor.contributions.flags) {
-		api.registerFlag({
-			name: fd.name,
-			description: fd.description,
-			defaultValue: fd.defaultValue,
-		});
-	}
-
-	for (const rd of descriptor.contributions.messageBuilders) {
+	for (const rd of descriptor.contributions?.messageBuilders ?? []) {
 		api.registerMessageBuilder({
 			name: rd.name,
 			build: (m) => m,
 		});
 	}
 
-	for (const pd of descriptor.contributions.providers) {
+	for (const pd of descriptor.contributions?.providers ?? []) {
 		api.registerProvider({
 			name: pd.name,
 			description: pd.description,

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/{tools → extensions/tools}/definitions.ts

@@ -81,7 +81,7 @@ export function createReadFilesTool(
 	return createTool<ReadFilesInput, ToolOperationResult[]>({
 		name: "read_files",
 		description:
-			"Read the full content of text files at the provided absolute paths, or return only an inclusive one-based line range when start_line/end_line are provided. " +
+			"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. " +
 			"Returns file contents or error messages for each path.",
 		inputSchema: zodToJsonSchema(ReadFilesInputSchema),
 		timeoutMs: timeoutMs * 2, // Account for multiple files
@@ -350,67 +350,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.
+Supported actions:
+- \`*** Add File: <path>\`
+- \`*** Update File: <path>\`
+- \`*** Delete File: <path>\`
+- optional \`*** Move to: <new path>\` immediately after an Update File header
 
-*** [ACTION] File: [path/to/file] -> ACTION can be one of Add, Update, or Delete. 
+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.
 
-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.
+Example:
 
-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]
-
-- 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,