@clinebot/core 0.0.11 → 0.0.13

package/src/agents/plugin-sandbox.ts

@@ -1,3 +1,6 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import type { AgentConfig, Tool } from "@clinebot/agents";
 import { SubprocessSandbox } from "../runtime/sandbox/subprocess-sandbox";
 
@@ -7,6 +10,7 @@ export interface PluginSandboxOptions {
 	importTimeoutMs?: number;
 	hookTimeoutMs?: number;
 	contributionTimeoutMs?: number;
+	onEvent?: (event: { name: string; payload?: unknown }) => void;
 }
 
 type AgentExtension = NonNullable<AgentConfig["extensions"]>[number];
@@ -48,192 +52,87 @@ type SandboxedPluginDescriptor = {
 	};
 };
 
-const PLUGIN_SANDBOX_BOOTSTRAP = `
-const { pathToFileURL } = require("node:url");
-let pluginCounter = 0;
-const pluginState = new Map();
-
-function toErrorPayload(error) {
-  const message = error instanceof Error ? error.message : String(error);
-  const stack = error instanceof Error ? error.stack : undefined;
-  return { message, stack };
-}
-
-function sendResponse(id, ok, result, error) {
-  if (!process.send) return;
-  process.send({ type: "response", id, ok, result, error });
-}
-
-function sanitizeObject(value) {
-  if (!value || typeof value !== "object") return {};
-  return value;
-}
-
-async function initialize(args) {
-  const descriptors = [];
-  const exportName = (args && args.exportName) || "plugin";
-  for (const pluginPath of args.pluginPaths || []) {
-    const moduleExports = await import(pathToFileURL(pluginPath).href);
-    const plugin = moduleExports.default || moduleExports[exportName];
-    if (!plugin || typeof plugin !== "object") {
-      throw new Error(\`Invalid plugin module: \${pluginPath}\`);
-    }
-    if (typeof plugin.name !== "string" || !plugin.name) {
-      throw new Error(\`Invalid plugin name: \${pluginPath}\`);
-    }
-    if (!plugin.manifest || typeof plugin.manifest !== "object") {
-      throw new Error(\`Invalid plugin manifest: \${pluginPath}\`);
-    }
-
-    const pluginId = \`plugin_\${++pluginCounter}\`;
-    const contributions = {
-      tools: [],
-      commands: [],
-      shortcuts: [],
-      flags: [],
-      messageRenderers: [],
-      providers: [],
-    };
-    const handlers = {
-      tools: new Map(),
-      commands: new Map(),
-      messageRenderers: new Map(),
-    };
-
-    const makeId = (prefix) => \`\${pluginId}_\${prefix}_\${Math.random().toString(36).slice(2, 10)}\`;
-    const api = {
-      registerTool: (tool) => {
-        const id = makeId("tool");
-        handlers.tools.set(id, tool.execute);
-        contributions.tools.push({
-          id,
-          name: tool.name,
-          description: tool.description,
-          inputSchema: tool.inputSchema,
-          timeoutMs: tool.timeoutMs,
-          retryable: tool.retryable,
-        });
-      },
-      registerCommand: (command) => {
-        const id = makeId("command");
-        if (typeof command.handler === "function") {
-          handlers.commands.set(id, command.handler);
-        }
-        contributions.commands.push({
-          id,
-          name: command.name,
-          description: command.description,
-        });
-      },
-      registerShortcut: (shortcut) => {
-        contributions.shortcuts.push({
-          id: makeId("shortcut"),
-          name: shortcut.name,
-          value: shortcut.value,
-          description: shortcut.description,
-        });
-      },
-      registerFlag: (flag) => {
-        contributions.flags.push({
-          id: makeId("flag"),
-          name: flag.name,
-          description: flag.description,
-          defaultValue: flag.defaultValue,
-        });
-      },
-      registerMessageRenderer: (renderer) => {
-        const id = makeId("renderer");
-        handlers.messageRenderers.set(id, renderer.render);
-        contributions.messageRenderers.push({ id, name: renderer.name });
-      },
-      registerProvider: (provider) => {
-        contributions.providers.push({
-          id: makeId("provider"),
-          name: provider.name,
-          description: provider.description,
-          metadata: sanitizeObject(provider.metadata),
-        });
-      },
-    };
-
-    if (typeof plugin.setup === "function") {
-      await plugin.setup(api);
-    }
-
-    pluginState.set(pluginId, { plugin, handlers });
-    descriptors.push({
-      pluginId,
-      name: plugin.name,
-      manifest: plugin.manifest,
-      contributions,
-    });
-  }
-  return descriptors;
-}
-
-function getPlugin(pluginId) {
-  const state = pluginState.get(pluginId);
-  if (!state) {
-    throw new Error(\`Unknown sandbox plugin id: \${pluginId}\`);
-  }
-  return state;
-}
-
-async function invokeHook(args) {
-  const state = getPlugin(args.pluginId);
-  const handler = state.plugin[args.hookName];
-  if (typeof handler !== "function") {
-    return undefined;
-  }
-  return await handler(args.payload);
-}
-
-async function executeTool(args) {
-  const state = getPlugin(args.pluginId);
-  const handler = state.handlers.tools.get(args.contributionId);
-  if (typeof handler !== "function") {
-    throw new Error("Unknown sandbox tool contribution");
-  }
-  return await handler(args.input, args.context);
-}
-
-async function executeCommand(args) {
-  const state = getPlugin(args.pluginId);
-  const handler = state.handlers.commands.get(args.contributionId);
-  if (typeof handler !== "function") {
-    return "";
-  }
-  return await handler(args.input);
-}
-
-async function renderMessage(args) {
-  const state = getPlugin(args.pluginId);
-  const handler = state.handlers.messageRenderers.get(args.contributionId);
-  if (typeof handler !== "function") {
-    return "";
-  }
-  return await handler(args.message);
+/**
+ * Resolve the bootstrap for the sandbox subprocess.
+ *
+ * In production (bundled), the compiled `.js` file lives next to this module
+ * and can be passed directly as a file to spawn. In development/test
+ * (unbundled, where only the `.ts` source exists), we load the TypeScript
+ * bootstrap through jiti from an inline script.
+ */
+function resolveBootstrap(): { file: string } | { script: string } {
+	const dir = dirname(fileURLToPath(import.meta.url));
+	// In dev, the bootstrap sits next to this file in src/agents/.
+	// In production, the main bundle is at dist/ but bootstrap is at dist/agents/.
+	const candidates = [
+		join(dir, "plugin-sandbox-bootstrap.js"),
+		join(dir, "agents", "plugin-sandbox-bootstrap.js"),
+	];
+	for (const candidate of candidates) {
+		if (existsSync(candidate)) return { file: candidate };
+	}
+	const tsPath = join(dir, "plugin-sandbox-bootstrap.ts");
+	return {
+		script: [
+			"const createJiti = require('jiti');",
+			`const jiti = createJiti(${JSON.stringify(tsPath)}, { cache: false, requireCache: false, esmResolve: true, interopDefault: false });`,
+			`Promise.resolve(jiti.import(${JSON.stringify(tsPath)}, {})).catch((error) => {`,
+			"  console.error(error);",
+			"  process.exitCode = 1;",
+			"});",
+		].join("\n"),
+	};
 }
 
-const methods = { initialize, invokeHook, executeTool, executeCommand, renderMessage };
-
-process.on("message", async (message) => {
-  if (!message || message.type !== "call") {
-    return;
-  }
-  const method = methods[message.method];
-  if (!method) {
-    sendResponse(message.id, false, undefined, { message: \`Unknown method: \${String(message.method)}\` });
-    return;
-  }
-  try {
-    const result = await method(message.args || {});
-    sendResponse(message.id, true, result);
-  } catch (error) {
-    sendResponse(message.id, false, undefined, toErrorPayload(error));
-  }
-});
-`;
+const BOOTSTRAP = resolveBootstrap();
+
+/**
+ * Map from hook stage names in the manifest to the property name on AgentExtension
+ * and the corresponding hook method name inside the sandbox subprocess.
+ */
+const HOOK_BINDINGS: Array<{
+	stage: HookStage;
+	extensionKey: keyof AgentExtension;
+	sandboxHookName: string;
+}> = [
+	{ stage: "input", extensionKey: "onInput", sandboxHookName: "onInput" },
+	{
+		stage: "session_start",
+		extensionKey: "onSessionStart",
+		sandboxHookName: "onSessionStart",
+	},
+	{
+		stage: "before_agent_start",
+		extensionKey: "onBeforeAgentStart",
+		sandboxHookName: "onBeforeAgentStart",
+	},
+	{
+		stage: "tool_call_before",
+		extensionKey: "onToolCall",
+		sandboxHookName: "onToolCall",
+	},
+	{
+		stage: "tool_call_after",
+		extensionKey: "onToolResult",
+		sandboxHookName: "onToolResult",
+	},
+	{
+		stage: "turn_end",
+		extensionKey: "onAgentEnd",
+		sandboxHookName: "onAgentEnd",
+	},
+	{
+		stage: "session_shutdown",
+		extensionKey: "onSessionShutdown",
+		sandboxHookName: "onSessionShutdown",
+	},
+	{
+		stage: "runtime_event",
+		extensionKey: "onRuntimeEvent",
+		sandboxHookName: "onRuntimeEvent",
+	},
+	{ stage: "error", extensionKey: "onError", sandboxHookName: "onError" },
+];
 
 function hasHookStage(extension: AgentExtension, stage: HookStage): boolean {
 	return extension.manifest.hookStages?.includes(stage) === true;
@@ -254,7 +153,10 @@ export async function loadSandboxedPlugins(
 }> {
 	const sandbox = new SubprocessSandbox({
 		name: "plugin-sandbox",
-		bootstrapScript: PLUGIN_SANDBOX_BOOTSTRAP,
+		...("file" in BOOTSTRAP
+			? { bootstrapFile: BOOTSTRAP.file }
+			: { bootstrapScript: BOOTSTRAP.script }),
+		onEvent: options.onEvent,
 	});
 	const importTimeoutMs = withTimeoutFallback(options.importTimeoutMs, 4000);
 	const hookTimeoutMs = withTimeoutFallback(options.hookTimeoutMs, 3000);
@@ -286,177 +188,13 @@ export async function loadSandboxedPlugins(
 				name: descriptor.name,
 				manifest: descriptor.manifest,
 				setup: (api: AgentExtensionApi) => {
-					for (const toolDescriptor of descriptor.contributions.tools) {
-						const tool: Tool = {
-							name: toolDescriptor.name,
-							description: toolDescriptor.description ?? "",
-							inputSchema: (toolDescriptor.inputSchema ?? {
-								type: "object",
-								properties: {},
-							}) as Tool["inputSchema"],
-							timeoutMs: toolDescriptor.timeoutMs,
-							retryable: toolDescriptor.retryable,
-							execute: async (input: unknown, context: unknown) =>
-								await sandbox.call(
-									"executeTool",
-									{
-										pluginId: descriptor.pluginId,
-										contributionId: toolDescriptor.id,
-										input,
-										context,
-									},
-									{ timeoutMs: contributionTimeoutMs },
-								),
-						};
-						api.registerTool(tool);
-					}
-
-					for (const commandDescriptor of descriptor.contributions.commands) {
-						api.registerCommand({
-							name: commandDescriptor.name,
-							description: commandDescriptor.description,
-							handler: async (input: string) =>
-								await sandbox.call<string>(
-									"executeCommand",
-									{
-										pluginId: descriptor.pluginId,
-										contributionId: commandDescriptor.id,
-										input,
-									},
-									{ timeoutMs: contributionTimeoutMs },
-								),
-						});
-					}
-
-					for (const shortcutDescriptor of descriptor.contributions.shortcuts) {
-						api.registerShortcut({
-							name: shortcutDescriptor.name,
-							value: shortcutDescriptor.value ?? "",
-							description: shortcutDescriptor.description,
-						});
-					}
-
-					for (const flagDescriptor of descriptor.contributions.flags) {
-						api.registerFlag({
-							name: flagDescriptor.name,
-							description: flagDescriptor.description,
-							defaultValue: flagDescriptor.defaultValue,
-						});
-					}
-
-					for (const rendererDescriptor of descriptor.contributions
-						.messageRenderers) {
-						api.registerMessageRenderer({
-							name: rendererDescriptor.name,
-							render: () =>
-								`[sandbox renderer ${rendererDescriptor.name} requires async bridge]`,
-						});
-					}
-
-					for (const providerDescriptor of descriptor.contributions.providers) {
-						api.registerProvider({
-							name: providerDescriptor.name,
-							description: providerDescriptor.description,
-							metadata: providerDescriptor.metadata,
-						});
-					}
+					registerTools(api, sandbox, descriptor, contributionTimeoutMs);
+					registerCommands(api, sandbox, descriptor, contributionTimeoutMs);
+					registerSimpleContributions(api, descriptor);
 				},
 			};
 
-			if (hasHookStage(extension, "input")) {
-				extension.onInput = async (payload: unknown) =>
-					await sandbox.call(
-						"invokeHook",
-						{ pluginId: descriptor.pluginId, hookName: "onInput", payload },
-						{ timeoutMs: hookTimeoutMs },
-					);
-			}
-			if (hasHookStage(extension, "session_start")) {
-				extension.onSessionStart = async (payload: unknown) =>
-					await sandbox.call(
-						"invokeHook",
-						{
-							pluginId: descriptor.pluginId,
-							hookName: "onSessionStart",
-							payload,
-						},
-						{ timeoutMs: hookTimeoutMs },
-					);
-			}
-			if (hasHookStage(extension, "before_agent_start")) {
-				extension.onBeforeAgentStart = async (payload: unknown) =>
-					await sandbox.call(
-						"invokeHook",
-						{
-							pluginId: descriptor.pluginId,
-							hookName: "onBeforeAgentStart",
-							payload,
-						},
-						{ timeoutMs: hookTimeoutMs },
-					);
-			}
-			if (hasHookStage(extension, "tool_call_before")) {
-				extension.onToolCall = async (payload: unknown) =>
-					await sandbox.call(
-						"invokeHook",
-						{ pluginId: descriptor.pluginId, hookName: "onToolCall", payload },
-						{ timeoutMs: hookTimeoutMs },
-					);
-			}
-			if (hasHookStage(extension, "tool_call_after")) {
-				extension.onToolResult = async (payload: unknown) =>
-					await sandbox.call(
-						"invokeHook",
-						{
-							pluginId: descriptor.pluginId,
-							hookName: "onToolResult",
-							payload,
-						},
-						{ timeoutMs: hookTimeoutMs },
-					);
-			}
-			if (hasHookStage(extension, "turn_end")) {
-				extension.onAgentEnd = async (payload: unknown) =>
-					await sandbox.call(
-						"invokeHook",
-						{ pluginId: descriptor.pluginId, hookName: "onAgentEnd", payload },
-						{ timeoutMs: hookTimeoutMs },
-					);
-			}
-			if (hasHookStage(extension, "session_shutdown")) {
-				extension.onSessionShutdown = async (payload: unknown) =>
-					await sandbox.call(
-						"invokeHook",
-						{
-							pluginId: descriptor.pluginId,
-							hookName: "onSessionShutdown",
-							payload,
-						},
-						{ timeoutMs: hookTimeoutMs },
-					);
-			}
-			if (hasHookStage(extension, "runtime_event")) {
-				extension.onRuntimeEvent = async (payload: unknown) => {
-					await sandbox.call(
-						"invokeHook",
-						{
-							pluginId: descriptor.pluginId,
-							hookName: "onRuntimeEvent",
-							payload,
-						},
-						{ timeoutMs: hookTimeoutMs },
-					);
-				};
-			}
-			if (hasHookStage(extension, "error")) {
-				extension.onError = async (payload: unknown) => {
-					await sandbox.call(
-						"invokeHook",
-						{ pluginId: descriptor.pluginId, hookName: "onError", payload },
-						{ timeoutMs: hookTimeoutMs },
-					);
-				};
-			}
+			bindHooks(extension, sandbox, descriptor.pluginId, hookTimeoutMs);
 
 			return extension;
 		},
@@ -469,3 +207,135 @@ export async function loadSandboxedPlugins(
 		},
 	};
 }
+
+// ---------------------------------------------------------------------------
+// Contribution registration helpers
+// ---------------------------------------------------------------------------
+
+function registerTools(
+	api: AgentExtensionApi,
+	sandbox: SubprocessSandbox,
+	descriptor: SandboxedPluginDescriptor,
+	timeoutMs: number,
+): void {
+	for (const td of descriptor.contributions.tools) {
+		const tool: Tool = {
+			name: td.name,
+			description: td.description ?? "",
+			inputSchema: (td.inputSchema ?? {
+				type: "object",
+				properties: {},
+			}) as Tool["inputSchema"],
+			timeoutMs: td.timeoutMs,
+			retryable: td.retryable,
+			execute: async (input: unknown, context: unknown) =>
+				await sandbox.call(
+					"executeTool",
+					{
+						pluginId: descriptor.pluginId,
+						contributionId: td.id,
+						input,
+						context,
+					},
+					{ timeoutMs },
+				),
+		};
+		api.registerTool(tool);
+	}
+}
+
+function registerCommands(
+	api: AgentExtensionApi,
+	sandbox: SubprocessSandbox,
+	descriptor: SandboxedPluginDescriptor,
+	timeoutMs: number,
+): void {
+	for (const cd of descriptor.contributions.commands) {
+		api.registerCommand({
+			name: cd.name,
+			description: cd.description,
+			handler: async (input: string) =>
+				await sandbox.call<string>(
+					"executeCommand",
+					{
+						pluginId: descriptor.pluginId,
+						contributionId: cd.id,
+						input,
+					},
+					{ timeoutMs },
+				),
+		});
+	}
+}
+
+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.messageRenderers) {
+		api.registerMessageRenderer({
+			name: rd.name,
+			render: () => `[sandbox renderer ${rd.name} requires async bridge]`,
+		});
+	}
+
+	for (const pd of descriptor.contributions.providers) {
+		api.registerProvider({
+			name: pd.name,
+			description: pd.description,
+			metadata: pd.metadata,
+		});
+	}
+}
+
+function makeHookHandler(
+	sandbox: SubprocessSandbox,
+	pluginId: string,
+	hookName: string,
+	timeoutMs: number,
+): (payload: unknown) => Promise<unknown> {
+	return async (payload: unknown) =>
+		await sandbox.call(
+			"invokeHook",
+			{ pluginId, hookName, payload },
+			{ timeoutMs },
+		);
+}
+
+function bindHooks(
+	extension: AgentExtension,
+	sandbox: SubprocessSandbox,
+	pluginId: string,
+	hookTimeoutMs: number,
+): void {
+	for (const { stage, extensionKey, sandboxHookName } of HOOK_BINDINGS) {
+		if (hasHookStage(extension, stage)) {
+			const handler = makeHookHandler(
+				sandbox,
+				pluginId,
+				sandboxHookName,
+				hookTimeoutMs,
+			);
+			// Each hook property on AgentExtension accepts (payload: unknown) => Promise<unknown>.
+			// TypeScript cannot narrow a union of optional callback keys via computed access,
+			// so we use Object.assign to set the property safely.
+			Object.assign(extension, { [extensionKey]: handler });
+		}
+	}
+}

package/src/index.node.ts

@@ -138,6 +138,11 @@ export {
 	saveLocalProviderOAuthCredentials,
 	saveLocalProviderSettings,
 } from "./providers/local-provider-service";
+export type { AvailableRuntimeCommand } from "./runtime/commands";
+export {
+	listAvailableRuntimeCommandsFromWatcher,
+	resolveRuntimeSlashCommandFromWatcher,
+} from "./runtime/commands";
 export {
 	formatRulesForSystemPrompt,
 	isRuleEnabled,
@@ -159,6 +164,11 @@ export type {
 	RuntimeBuilderInput,
 	SessionRuntime,
 } from "./runtime/session-runtime";
+export type { AvailableSkill } from "./runtime/skills";
+export {
+	listAvailableSkillsFromWatcher,
+	resolveSkillsSlashCommandFromWatcher,
+} from "./runtime/skills";
 export {
 	type DesktopToolApprovalOptions,
 	requestDesktopToolApproval,
@@ -207,6 +217,10 @@ export {
 	SqliteRpcSessionBackend,
 	type SqliteRpcSessionBackendOptions,
 } from "./session/sqlite-rpc-session-backend";
+export {
+	accumulateUsageTotals,
+	createInitialAccumulatedUsage,
+} from "./session/utils/usage";
 export type {
 	WorkspaceManager,
 	WorkspaceManagerEvent,