@clinebot/core 0.0.36 → 0.0.37

package/src/extensions/plugin/plugin-config-loader.ts

@@ -1,5 +1,9 @@
 import { existsSync } from "node:fs";
-import type { AgentConfig, WorkspaceInfo } from "@clinebot/shared";
+import type {
+	AgentConfig,
+	PluginSetupContext,
+	WorkspaceInfo,
+} from "@clinebot/shared";
 import {
 	discoverPluginModulePaths as discoverPluginModulePathsFromShared,
 	resolveConfiguredPluginModulePaths,
@@ -69,6 +73,12 @@ export interface ResolveAndLoadAgentPluginsOptions
 	 * in the extension context.
 	 */
 	workspaceInfo?: WorkspaceInfo;
+	session?: PluginSetupContext["session"];
+	client?: PluginSetupContext["client"];
+	user?: PluginSetupContext["user"];
+	automation?: PluginSetupContext["automation"];
+	logger?: PluginSetupContext["logger"];
+	telemetry?: PluginSetupContext["telemetry"];
 }
 
 export async function resolveAndLoadAgentPlugins(
@@ -90,7 +100,13 @@ export async function resolveAndLoadAgentPlugins(
 			exportName: options.exportName,
 			providerId: options.providerId,
 			modelId: options.modelId,
+			session: options.session,
+			client: options.client,
+			user: options.user,
 			workspaceInfo: options.workspaceInfo,
+			automation: options.automation,
+			logger: options.logger,
+			telemetry: options.telemetry,
 		});
 		return {
 			extensions: report.plugins,
@@ -109,7 +125,11 @@ export async function resolveAndLoadAgentPlugins(
 		providerId: options.providerId,
 		modelId: options.modelId,
 		cwd: options.cwd,
+		session: options.session,
+		client: options.client,
+		user: options.user,
 		workspaceInfo: options.workspaceInfo,
+		logger: options.logger,
 	});
 	return {
 		extensions: sandboxed.extensions ?? [],

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

@@ -1,5 +1,5 @@
 import { resolve } from "node:path";
-import type { AgentConfig, PluginSetupContext } from "@clinebot/shared";
+import type { AgentExtension, PluginSetupContext } from "@clinebot/shared";
 import { normalizePluginManifest } from "@clinebot/shared";
 import type {
 	PluginInitializationFailure,
@@ -11,7 +11,6 @@ import {
 	type PluginTargeting,
 } from "./plugin-targeting";
 
-type AgentPlugin = NonNullable<AgentConfig["extensions"]>[number];
 type PluginLike = {
 	name: string;
 	manifest: {
@@ -26,7 +25,13 @@ export interface LoadAgentPluginFromPathOptions {
 	exportName?: string;
 	cwd?: string;
 	useCache?: boolean;
+	session?: PluginSetupContext["session"];
+	client?: PluginSetupContext["client"];
+	user?: PluginSetupContext["user"];
 	workspaceInfo?: PluginSetupContext["workspaceInfo"];
+	automation?: PluginSetupContext["automation"];
+	logger?: PluginSetupContext["logger"];
+	telemetry?: PluginSetupContext["telemetry"];
 }
 
 function isObject(value: unknown): value is Record<string, unknown> {
@@ -109,7 +114,7 @@ function validatePluginExport(
 export async function loadAgentPluginFromPath(
 	pluginPath: string,
 	options: LoadAgentPluginFromPathOptions = {},
-): Promise<AgentPlugin> {
+): Promise<AgentExtension> {
 	const absolutePath = resolve(options.cwd ?? process.cwd(), pluginPath);
 	const moduleExports = await importPluginModule(absolutePath, {
 		useCache: options.useCache,
@@ -119,14 +124,25 @@ export async function loadAgentPluginFromPath(
 		moduleExports[exportName]) as unknown;
 
 	validatePluginExport(plugin, absolutePath);
-	const pluginTyped = plugin as AgentPlugin;
+	const pluginTyped = plugin as AgentExtension;
 	const originalSetup = pluginTyped.setup;
 
 	// Wrap setup to inject workspace context
-	const setupWithContext: AgentPlugin["setup"] = originalSetup
+	const setupWithContext: AgentExtension["setup"] = originalSetup
 		? (api, _ctx) => {
+				const session = {
+					...options.session,
+					..._ctx.session,
+				};
 				const ctx = {
-					workspaceInfo: options.workspaceInfo,
+					..._ctx,
+					session: Object.keys(session).length > 0 ? session : undefined,
+					client: options.client ?? _ctx.client,
+					user: options.user ?? _ctx.user,
+					workspaceInfo: options.workspaceInfo ?? _ctx.workspaceInfo,
+					automation: options.automation ?? _ctx.automation,
+					logger: options.logger ?? _ctx.logger,
+					telemetry: options.telemetry ?? _ctx.telemetry,
 				};
 				return originalSetup(api, ctx);
 			}
@@ -142,7 +158,7 @@ export async function loadAgentPluginFromPath(
 export async function loadAgentPluginsFromPaths(
 	pluginPaths: string[],
 	options: LoadAgentPluginFromPathOptions & PluginTargeting = {},
-): Promise<AgentPlugin[]> {
+): Promise<AgentExtension[]> {
 	const report = await loadAgentPluginsFromPathsWithDiagnostics(
 		pluginPaths,
 		options,
@@ -154,7 +170,7 @@ export async function loadAgentPluginsFromPathsWithDiagnostics(
 	pluginPaths: string[],
 	options: LoadAgentPluginFromPathOptions & PluginTargeting = {},
 ): Promise<{
-	plugins: AgentPlugin[];
+	plugins: AgentExtension[];
 	failures: PluginInitializationFailure[];
 	warnings: PluginInitializationWarning[];
 }> {
@@ -162,7 +178,7 @@ export async function loadAgentPluginsFromPathsWithDiagnostics(
 	const warnings: PluginInitializationWarning[] = [];
 	const loadedByName = new Map<
 		string,
-		{ plugin: AgentPlugin; pluginPath: string; order: number }
+		{ plugin: AgentExtension; pluginPath: string; order: number }
 	>();
 	let order = 0;
 

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

@@ -10,7 +10,11 @@
  * depend on local helpers that can be inlined into the sandbox build.
  */
 
-import { normalizePluginManifest, type PluginManifest } from "@clinebot/shared";
+import {
+	type AutomationEventEnvelope,
+	normalizePluginManifest,
+	type PluginManifest,
+} from "@clinebot/shared";
 import { importPluginModule } from "./plugin-module-import";
 import {
 	matchesPluginManifestTargeting,
@@ -47,15 +51,37 @@ interface PluginProvider {
 	metadata?: Record<string, unknown>;
 }
 
+interface PluginAutomationEventType {
+	eventType: string;
+	source: string;
+	description?: string;
+	attributesSchema?: Record<string, unknown>;
+	payloadSchema?: Record<string, unknown>;
+	examples?: AutomationEventEnvelope[];
+	metadata?: Record<string, unknown>;
+}
+
 interface PluginApi {
 	registerTool(tool: PluginTool): void;
 	registerCommand(command: PluginCommand): void;
 	registerMessageBuilder(builder: PluginMessageBuilder): void;
 	registerProvider(provider: PluginProvider): void;
+	registerAutomationEventType(eventType: PluginAutomationEventType): void;
 }
 
 interface PluginSetupCtx {
+	session?: unknown;
+	client?: unknown;
+	user?: unknown;
 	workspaceInfo?: unknown;
+	automation?: {
+		ingestEvent(event: AutomationEventEnvelope): void | Promise<void>;
+	};
+	logger?: {
+		debug(message: string, metadata?: Record<string, unknown>): void;
+		log(message: string, metadata?: Record<string, unknown>): void;
+		error(message: string, metadata?: Record<string, unknown>): void;
+	};
 }
 
 interface PluginModule {
@@ -77,6 +103,17 @@ interface ContributionDescriptor {
 	metadata?: Record<string, unknown>;
 }
 
+interface AutomationEventTypeDescriptor {
+	id: string;
+	eventType: string;
+	source: string;
+	description?: string;
+	attributesSchema?: Record<string, unknown>;
+	payloadSchema?: Record<string, unknown>;
+	examples?: AutomationEventEnvelope[];
+	metadata?: Record<string, unknown>;
+}
+
 interface PluginDescriptor {
 	pluginId: string;
 	pluginPath: string;
@@ -87,6 +124,7 @@ interface PluginDescriptor {
 		commands: ContributionDescriptor[];
 		messageBuilders: ContributionDescriptor[];
 		providers: ContributionDescriptor[];
+		automationEventTypes: AutomationEventTypeDescriptor[];
 		shortcuts?: ContributionDescriptor[];
 		flags?: ContributionDescriptor[];
 	};
@@ -166,9 +204,32 @@ function assertValidPluginSetupCtx(
 	if (!isObject(ctx)) {
 		throw new Error("Plugin setup context must be an object");
 	}
+	if (ctx.session !== undefined && !isObject(ctx.session)) {
+		throw new Error("Plugin setup context session must be an object");
+	}
+	if (ctx.client !== undefined && !isObject(ctx.client)) {
+		throw new Error("Plugin setup context client must be an object");
+	}
+	if (ctx.user !== undefined && !isObject(ctx.user)) {
+		throw new Error("Plugin setup context user must be an object");
+	}
 	if (ctx.workspaceInfo !== undefined && !isObject(ctx.workspaceInfo)) {
 		throw new Error("Plugin setup context workspaceInfo must be an object");
 	}
+	if (ctx.automation !== undefined && !isObject(ctx.automation)) {
+		throw new Error("Plugin setup context automation must be an object");
+	}
+	if (
+		ctx.automation !== undefined &&
+		typeof ctx.automation.ingestEvent !== "function"
+	) {
+		throw new Error(
+			"Plugin setup context automation.ingestEvent must be a function",
+		);
+	}
+	if (ctx.logger !== undefined && !isObject(ctx.logger)) {
+		throw new Error("Plugin setup context logger must be an object");
+	}
 }
 
 // ---------------------------------------------------------------------------
@@ -226,6 +287,45 @@ function sanitizeObject(value: unknown): Record<string, unknown> {
 	return value as Record<string, unknown>;
 }
 
+function sanitizeLogMetadata(
+	value: unknown,
+): Record<string, unknown> | undefined {
+	if (!value || typeof value !== "object") {
+		return undefined;
+	}
+	const metadata = { ...(value as Record<string, unknown>) };
+	if (metadata.error instanceof Error) {
+		metadata.error = {
+			name: metadata.error.name,
+			message: metadata.error.message,
+			stack: metadata.error.stack,
+		};
+	}
+	return metadata;
+}
+
+function createPluginLogger(
+	pluginName: string,
+): NonNullable<PluginSetupCtx["logger"]> {
+	const emitLog = (
+		level: "debug" | "log" | "error",
+		message: string,
+		metadata?: Record<string, unknown>,
+	) => {
+		emitEvent("plugin_log", {
+			level,
+			pluginName,
+			message,
+			metadata: sanitizeLogMetadata(metadata),
+		});
+	};
+	return {
+		debug: (message, metadata) => emitLog("debug", message, metadata),
+		log: (message, metadata) => emitLog("log", message, metadata),
+		error: (message, metadata) => emitLog("error", message, metadata),
+	};
+}
+
 function makeId(pluginId: string, prefix: string): string {
 	const key = `${pluginId}:${prefix}`;
 	const next = (contributionCounters.get(key) ?? 0) + 1;
@@ -233,6 +333,30 @@ function makeId(pluginId: string, prefix: string): string {
 	return `${pluginId}_${prefix}_${next}`;
 }
 
+function normalizeAutomationEventType(
+	eventType: PluginAutomationEventType,
+): PluginAutomationEventType {
+	const normalizedEventType =
+		typeof eventType.eventType === "string" ? eventType.eventType.trim() : "";
+	const source =
+		typeof eventType.source === "string" ? eventType.source.trim() : "";
+	if (!normalizedEventType) {
+		throw new Error("Automation event type contribution requires eventType");
+	}
+	if (!source) {
+		throw new Error("Automation event type contribution requires source");
+	}
+	return {
+		...eventType,
+		eventType: normalizedEventType,
+		source,
+		examples: eventType.examples ? [...eventType.examples] : undefined,
+		metadata: eventType.metadata
+			? sanitizeObject(eventType.metadata)
+			: undefined,
+	};
+}
+
 function getPlugin(pluginId: string): PluginState {
 	const state = pluginState.get(pluginId);
 	if (!state) {
@@ -251,7 +375,11 @@ async function initialize(args: {
 	providerId?: string;
 	modelId?: string;
 	cwd?: string;
+	session?: unknown;
+	client?: unknown;
+	user?: unknown;
 	workspaceInfo?: unknown;
+	loggerEnabled?: boolean;
 }): Promise<InitializeResult> {
 	pluginState.clear();
 	pluginCounter = 0;
@@ -305,6 +433,7 @@ async function initialize(args: {
 				commands: [],
 				messageBuilders: [],
 				providers: [],
+				automationEventTypes: [],
 				shortcuts: [],
 				flags: [],
 			};
@@ -351,12 +480,33 @@ async function initialize(args: {
 						metadata: sanitizeObject(provider.metadata),
 					});
 				},
+				registerAutomationEventType: (eventType) => {
+					contributions.automationEventTypes.push({
+						id: makeId(pluginId, "automation_event"),
+						...normalizeAutomationEventType(eventType),
+					});
+				},
 			};
 
 			if (typeof plugin.setup === "function") {
 				try {
 					const setupCtx = {
+						session: args.session,
+						client: args.client,
+						user: args.user,
 						workspaceInfo: args.workspaceInfo,
+						...(args.loggerEnabled
+							? { logger: createPluginLogger(plugin.name) }
+							: {}),
+						...(plugin.manifest.capabilities.includes("automationEvents")
+							? {
+									automation: {
+										ingestEvent: (event: AutomationEventEnvelope) => {
+											emitEvent("automation_event", event);
+										},
+									},
+								}
+							: {}),
 					};
 					assertValidPluginSetupCtx(setupCtx);
 					await plugin.setup(api, setupCtx);

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

@@ -4,7 +4,10 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import type {
 	AgentConfig,
+	AgentExtensionAutomationEventType,
 	HookStage,
+	Message,
+	PluginSetupContext,
 	Tool,
 	WorkspaceInfo,
 } from "@clinebot/shared";
@@ -12,6 +15,11 @@ import { SubprocessSandbox } from "../../runtime/subprocess-sandbox";
 import type { PluginLoadDiagnostics } from "./plugin-load-report";
 import type { PluginTargeting } from "./plugin-targeting";
 
+export type SandboxedPluginSetupContext = Pick<
+	PluginSetupContext,
+	"session" | "client" | "user" | "workspaceInfo" | "logger"
+>;
+
 export interface PluginSandboxOptions extends PluginTargeting {
 	pluginPaths: string[];
 	exportName?: string;
@@ -31,6 +39,11 @@ export interface PluginSandboxOptions extends PluginTargeting {
 	 * 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];
@@ -46,6 +59,11 @@ type SandboxedContributionDescriptor = {
 	metadata?: Record<string, unknown>;
 };
 
+type SandboxedAutomationEventTypeDescriptor =
+	AgentExtensionAutomationEventType & {
+		id: string;
+	};
+
 type SandboxedPluginDescriptor = {
 	pluginId: string;
 	pluginPath: string;
@@ -56,6 +74,7 @@ type SandboxedPluginDescriptor = {
 		commands: SandboxedContributionDescriptor[];
 		messageBuilders: SandboxedContributionDescriptor[];
 		providers: SandboxedContributionDescriptor[];
+		automationEventTypes: SandboxedAutomationEventTypeDescriptor[];
 		shortcuts?: SandboxedContributionDescriptor[];
 		flags?: SandboxedContributionDescriptor[];
 	};
@@ -75,6 +94,8 @@ function normalizeDescriptor(
 			commands: descriptor.contributions?.commands ?? [],
 			messageBuilders: descriptor.contributions?.messageBuilders ?? [],
 			providers: descriptor.contributions?.providers ?? [],
+			automationEventTypes:
+				descriptor.contributions?.automationEventTypes ?? [],
 			shortcuts: descriptor.contributions?.shortcuts ?? [],
 			flags: descriptor.contributions?.flags ?? [],
 		},
@@ -145,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",
@@ -165,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",
@@ -216,7 +267,11 @@ export async function loadSandboxedPlugins(
 		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
@@ -266,6 +321,13 @@ export async function loadSandboxedPlugins(
 						contributionTimeoutMs,
 						reinitialize,
 					);
+					registerMessageBuilders(
+						api,
+						sandbox,
+						descriptor,
+						contributionTimeoutMs,
+						reinitialize,
+					);
 					registerSimpleContributions(api, descriptor);
 				},
 			};
@@ -393,13 +455,6 @@ function registerSimpleContributions(
 	api: AgentExtensionApi,
 	descriptor: SandboxedPluginDescriptor,
 ): void {
-	for (const rd of descriptor.contributions?.messageBuilders ?? []) {
-		api.registerMessageBuilder({
-			name: rd.name,
-			build: (m) => m,
-		});
-	}
-
 	for (const pd of descriptor.contributions?.providers ?? []) {
 		api.registerProvider({
 			name: pd.name,
@@ -407,6 +462,75 @@ function registerSimpleContributions(
 			metadata: pd.metadata,
 		});
 	}
+
+	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,
+		});
+	}
+}
+
+function registerMessageBuilders(
+	api: AgentExtensionApi,
+	sandbox: SubprocessSandbox,
+	descriptor: SandboxedPluginDescriptor,
+	timeoutMs: number,
+	reinitialize: () => Promise<void>,
+): void {
+	for (const bd of descriptor.contributions?.messageBuilders ?? []) {
+		api.registerMessageBuilder({
+			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;
+				}
+			},
+		});
+	}
+}
+
+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/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,
 ];