@context-action/core 0.8.8 → 0.9.2

package/README.md

@@ -53,6 +53,23 @@ await actions.dispatch('increment');
 await actions.dispatch('setCount', 42);
 ```
 
+## Tool protocol boundary
+
+MCP, JSON Schema, provider conversion, action schemas, and approval queues are
+owned by [`@context-action/tool-protocol`](../tool-protocol/README.md). Core
+only owns action registration and execution. This keeps the runtime usable
+without a tool-calling or Zod dependency.
+
+Install the protocol package separately when an integration needs it:
+
+```bash
+npm install @context-action/tool-protocol zod
+```
+
+The React-facing registry remains in `@context-action/react`; protocol symbols
+such as `defineAction`, `listAllTools`, and `ToolManagementInterface` must be
+imported from `@context-action/tool-protocol`.
+
 ## 🌟 Vanilla JavaScript Support
 
 **@context-action/core works perfectly with vanilla JavaScript!** No React, Vue, or any framework required.

package/dist/index.cjs

@@ -105,7 +105,6 @@ async function executeSequential(context, createController) {
 					}
 					i = jumpIndex;
 					context.jumpToPriority = void 0;
-					continue;
 				} else {
 					context.jumpToPriority = void 0;
 					i++;
@@ -986,55 +985,6 @@ function isActionRegisterDestroyedError(error) {
 
 //#endregion
 //#region src/ActionRegister.ts
-const dispatchOptionKeys = /* @__PURE__ */ new Set([
-	"autoAbort",
-	"debounce",
-	"executionMode",
-	"filter",
-	"immediate",
-	"queuePriority",
-	"result",
-	"retryOnError",
-	"signal",
-	"throttle",
-	"timeout"
-]);
-function isRecord(value) {
-	return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-function isOptionalNumber(value) {
-	return value === void 0 || typeof value === "number";
-}
-function isOptionalBoolean(value) {
-	return value === void 0 || typeof value === "boolean";
-}
-/**
-* Recognize the deprecated options-first void-action proxy call.
-*
-* Every supplied field is validated so ordinary payloads that merely overlap
-* one option name are not silently reinterpreted as dispatch options.
-*/
-function isDispatchOptions(value) {
-	if (!isRecord(value)) return false;
-	const keys = Object.keys(value);
-	if (keys.length === 0 || keys.some((key) => !dispatchOptionKeys.has(key))) return false;
-	return keys.every((key) => {
-		const optionValue = value[key];
-		switch (key) {
-			case "debounce":
-			case "queuePriority":
-			case "throttle":
-			case "timeout": return isOptionalNumber(optionValue);
-			case "immediate": return isOptionalBoolean(optionValue);
-			case "executionMode": return optionValue === void 0 || optionValue === "sequential" || optionValue === "parallel" || optionValue === "race";
-			case "signal": return optionValue === void 0 || isRecord(optionValue) && typeof optionValue.aborted === "boolean" && typeof optionValue.addEventListener === "function";
-			case "retryOnError": return optionValue === void 0 || isRecord(optionValue) && typeof optionValue.maxAttempts === "number" && typeof optionValue.delay === "number";
-			case "autoAbort": return optionValue === void 0 || isRecord(optionValue) && typeof optionValue.enabled === "boolean" && isOptionalBoolean(optionValue.allowHandlerAbort) && (optionValue.onControllerCreated === void 0 || typeof optionValue.onControllerCreated === "function");
-			case "filter": return optionValue === void 0 || isRecord(optionValue) && (optionValue.handlerIds === void 0 || Array.isArray(optionValue.handlerIds) && optionValue.handlerIds.every((item) => typeof item === "string")) && (optionValue.excludeHandlerIds === void 0 || Array.isArray(optionValue.excludeHandlerIds) && optionValue.excludeHandlerIds.every((item) => typeof item === "string")) && (optionValue.priority === void 0 || isRecord(optionValue.priority)) && (optionValue.custom === void 0 || typeof optionValue.custom === "function");
-			case "result": return optionValue === void 0 || isRecord(optionValue) && (optionValue.strategy === void 0 || optionValue.strategy === "first" || optionValue.strategy === "last" || optionValue.strategy === "all" || optionValue.strategy === "merge" || optionValue.strategy === "custom") && (optionValue.merger === void 0 || typeof optionValue.merger === "function") && isOptionalBoolean(optionValue.collect) && isOptionalNumber(optionValue.maxResults) && isOptionalBoolean(optionValue.includeErrors);
-		}
-	});
-}
 /**
 * Action Register for managing action handlers with priority-based execution
 * 
@@ -1057,10 +1007,8 @@ var ActionRegister = class {
 		this.actionExecutionModes = /* @__PURE__ */ new Map();
 		this.unregisterFunctions = /* @__PURE__ */ new Map();
 		this.lastRegisteredTimestamps = /* @__PURE__ */ new Map();
-		this.filterCacheDisabled = true;
 		this.handlerIdCounter = 0;
 		this.controllerPool = [];
-		this.maxControllerPoolSize = 10;
 		this.lifecycleState = "active";
 		this.lifecycleController = new AbortController();
 		this.activeDispatches = /* @__PURE__ */ new Set();
@@ -1098,7 +1046,6 @@ var ActionRegister = class {
 	* // Function-based dispatching
 	* await registry.actions.userLogin({ userId: '123', email: 'test@example.com' });
 	* await registry.actions.resetApp();
-	* await registry.actions.resetApp({ debounce: 100 }); // Legacy options-first form
 	* await registry.actions.resetApp(undefined, { debounce: 100 });
 	* ```
 	* 
@@ -1107,9 +1054,8 @@ var ActionRegister = class {
 	get actions() {
 		if (!this._actionsProxy) this._actionsProxy = new Proxy({}, { get: (_target, prop) => {
 			const actionKey = prop;
-			if (typeof prop === "string" && this.pipelines.has(actionKey)) return (payloadOrOptions, options) => {
-				if (isDispatchOptions(payloadOrOptions)) return this.dispatch(actionKey, void 0, payloadOrOptions);
-				return this.dispatch(actionKey, payloadOrOptions, options);
+			if (typeof prop === "string" && this.pipelines.has(actionKey)) return (payload, options) => {
+				return this.dispatch(actionKey, payload, options);
 			};
 		} });
 		return this._actionsProxy;
@@ -1144,9 +1090,8 @@ var ActionRegister = class {
 	get actionsWithResult() {
 		if (!this._actionsWithResultProxy) this._actionsWithResultProxy = new Proxy({}, { get: (_target, prop) => {
 			const actionKey = prop;
-			if (typeof prop === "string" && this.pipelines.has(actionKey)) return (payloadOrOptions, options) => {
-				if (isDispatchOptions(payloadOrOptions)) return this.dispatchWithResult(actionKey, void 0, payloadOrOptions);
-				return this.dispatchWithResult(actionKey, payloadOrOptions, options);
+			if (typeof prop === "string" && this.pipelines.has(actionKey)) return (payload, options) => {
+				return this.dispatchWithResult(actionKey, payload, options);
 			};
 		} });
 		return this._actionsWithResultProxy;
@@ -1279,7 +1224,7 @@ var ActionRegister = class {
 			const existing = pipeline[existingIndex];
 			const existingUnregister = this.unregisterFunctions.get(handlerId);
 			if (registration.config.replaceExisting) {
-				if (existing && existing.config.cleanup && typeof existing.config.cleanup === "function") try {
+				if (existing?.config.cleanup && typeof existing.config.cleanup === "function") try {
 					existing.config.cleanup();
 				} catch (cleanupError) {
 					this.log(`Cleanup error for replaced handler: ${String(action)}`, cleanupError, "warn");
@@ -1950,21 +1895,6 @@ var ActionRegister = class {
 		return null;
 	}
 	/**
-	* 🔧 Generate optimized cache key for filter options
-	*/
-	generateFilterCacheKey(filterOptions) {
-		if (!filterOptions) return "no-filter";
-		const parts = [];
-		if (filterOptions.handlerIds?.length) parts.push(`h:${filterOptions.handlerIds.slice().sort().join(",")}`);
-		if (filterOptions.excludeHandlerIds?.length) parts.push(`e:${filterOptions.excludeHandlerIds.slice().sort().join(",")}`);
-		if (filterOptions.priority) {
-			const { min, max } = filterOptions.priority;
-			if (min !== void 0 || max !== void 0) parts.push(`p:${min ?? "*"}-${max ?? "*"}`);
-		}
-		if (filterOptions.custom) return "custom-" + Date.now() + Math.random();
-		return parts.length > 0 ? parts.join("|") : "no-filter";
-	}
-	/**
 	* 🔧 Create or reuse PipelineController from pool for better performance
 	*/
 	getControllerFromPool(context, autoAbortController, autoAbortOptions) {
@@ -2004,12 +1934,6 @@ var ActionRegister = class {
 		};
 		return controller;
 	}
-	/**
-	* 🔧 Return controller to pool for reuse
-	*/
-	returnControllerToPool(controller) {
-		if (this.controllerPool.length < this.maxControllerPoolSize) this.controllerPool.push(controller);
-	}
 	filterHandlers(handlers, filterOptions) {
 		if (!filterOptions) return handlers;
 		const handlerIdSet = filterOptions.handlerIds ? new Set(filterOptions.handlerIds) : null;
@@ -2017,7 +1941,7 @@ var ActionRegister = class {
 		return handlers.filter((registration) => {
 			const config = registration.config;
 			if (handlerIdSet && !handlerIdSet.has(config.id)) return false;
-			if (excludeIdSet && excludeIdSet.has(config.id)) return false;
+			if (excludeIdSet?.has(config.id)) return false;
 			if (filterOptions.priority) {
 				const priority = config.priority;
 				if (filterOptions.priority.min !== void 0 && priority < filterOptions.priority.min) return false;
@@ -2300,7 +2224,7 @@ var ActionRegister = class {
 	removeRegistration(action, registration, runCleanup = true) {
 		const pipeline = this.pipelines.get(action);
 		if (!pipeline) return false;
-		const index = pipeline.findIndex((candidate) => candidate === registration);
+		const index = pipeline.indexOf(registration);
 		if (index === -1) return false;
 		pipeline.splice(index, 1);
 		this.unregisterFunctions.delete(registration.id);
@@ -2411,359 +2335,15 @@ var ActionRegister = class {
 	}
 };
 
-//#endregion
-//#region src/react-helpers.ts
-/**
-* 🔧 Create action handler registration configuration for React components
-* 
-* Creates a configuration object that can be used with React's useEffect to properly
-* register and unregister action handlers with lifecycle management and cleanup.
-* This is NOT a hook - it's a factory function for React hook integration.
-* 
-* @template T - ActionPayloadMap type
-* @template K - Action key type
-* 
-* @param registry - ActionRegister instance
-* @param action - Action name to register handler for
-* @param handler - Handler function (should be memoized with useCallback)
-* @param config - Handler configuration
-* 
-* @returns Configuration object with register/unregister functions
-* 
-* @example Basic Usage with useEffect
-* ```tsx
-* import { useCallback, useEffect } from 'react';
-* import { createActionHandler } from '@context-action/core/react-helpers';
-* 
-* function MyComponent() {
-*   const registry = useActionRegister();
-*   
-*   const handleUserUpdate = useCallback(async (payload, controller) => {
-*     // Handler logic here
-*   }, []);
-*   
-*   useEffect(() => {
-*     const { register, unregister } = createActionHandler(
-*       registry,
-*       'updateUser',
-*       handleUserUpdate,
-*       { priority: 10 }
-*     );
-*     
-*     const cleanup = register();
-*     return () => {
-*       cleanup();
-*       unregister();
-*     };
-*   }, [registry, handleUserUpdate]);
-* }
-* ```
-* 
-* @example With Automatic Cleanup
-* ```tsx
-* const [userId, setUserId] = useState('123');
-* 
-* const handleUserUpdate = useCallback(async (payload, controller) => {
-*   console.log('Updating user:', userId, payload);
-* }, [userId]);
-* 
-* useEffect(() => {
-*   const handlerManager = createActionHandler(
-*     registry,
-*     'updateUser',
-*     handleUserUpdate,
-*     { priority: 10 }
-*   );
-*   
-*   // Simplified registration with automatic cleanup
-*   return handlerManager.registerWithCleanup();
-* }, [registry, handleUserUpdate, userId]);
-* ```
-* 
-* @public
-*/
-function createActionHandler(registry, action, handler, config) {
-	const timestamp = Date.now();
-	const random = Math.random().toString(36).substr(2, 5);
-	const finalConfig = {
-		priority: config?.priority ?? 0,
-		id: config?.id || `react_${String(action)}_${timestamp}_${random}`,
-		blocking: config?.blocking ?? false,
-		once: config?.once ?? false,
-		debounce: config?.debounce ?? void 0,
-		throttle: config?.throttle ?? void 0,
-		replaceExisting: true
-	};
-	let currentUnregister;
-	let isRegistered = false;
-	return {
-		/**
-		* Register the handler and return cleanup function
-		*/
-		register() {
-			if (isRegistered && currentUnregister) currentUnregister();
-			currentUnregister = registry.register(action, handler, finalConfig);
-			isRegistered = true;
-			return currentUnregister;
-		},
-		/**
-		* Unregister the handler if currently registered
-		*/
-		unregister() {
-			if (isRegistered && currentUnregister) {
-				currentUnregister();
-				currentUnregister = void 0;
-				isRegistered = false;
-			}
-		},
-		/**
-		* Register and return cleanup function (React useEffect pattern)
-		*/
-		registerWithCleanup() {
-			const unregisterFn = this.register();
-			return () => {
-				unregisterFn();
-				this.unregister();
-			};
-		},
-		config: finalConfig
-	};
-}
-/**
-* 🆕 React development utilities
-* 
-* Provides debugging and development helpers specifically for React environments.
-*/
-const ReactDevUtils = {
-	/**
-	* Enable detailed React integration debugging
-	*/
-	enableDebugMode() {
-		if (typeof window !== "undefined") window.__CONTEXT_ACTION_REACT_DEBUG__ = true;
-	},
-	/**
-	* Disable React integration debugging
-	*/
-	disableDebugMode() {
-		if (typeof window !== "undefined") window.__CONTEXT_ACTION_REACT_DEBUG__ = false;
-	},
-	/**
-	* Check if React debug mode is enabled
-	*/
-	isDebugMode() {
-		return typeof window !== "undefined" && Boolean(window.__CONTEXT_ACTION_REACT_DEBUG__);
-	},
-	/**
-	* Log React-specific debugging information
-	*/
-	log(component, action, message, data) {
-		if (this.isDebugMode()) console.log(`🎯 [React-ActionRegister] [${component}] ${action}: ${message}`, data || "");
-	},
-	/**
-	* Get React integration statistics
-	*/
-	getStats(registry) {
-		const registryInfo = registry.getRegistryInfo();
-		let reactHandlers = 0;
-		registry.getRegisteredActions().forEach((action) => {
-			const stats = registry.getActionStats(action);
-			if (stats) stats.handlersByPriority.forEach((priorityGroup) => {
-				priorityGroup.handlers.forEach((handler) => {
-					if (handler.id.includes("react")) reactHandlers++;
-				});
-			});
-		});
-		return {
-			totalHandlers: registryInfo.totalHandlers,
-			reactHandlers,
-			registryInfo
-		};
-	}
-};
-/**
-* 🆕 React Error Boundary integration
-* 
-* Utilities for integrating ActionRegister errors with React Error Boundaries.
-*/
-var ReactActionError = class ReactActionError extends Error {
-	constructor(message, action, payload, handlerId = void 0, originalError) {
-		super(message);
-		this.name = "ReactActionError";
-		this.action = action;
-		this.payload = payload;
-		this.handlerId = handlerId;
-		this.timestamp = Date.now();
-		if (originalError && originalError.stack) this.stack = originalError.stack;
-	}
-	/**
-	* Create a React Error Boundary compatible error
-	*/
-	static fromActionError(originalError, action, payload, handlerId) {
-		return new ReactActionError(`Action '${action}' failed: ${originalError.message}`, action, payload, handlerId, originalError);
-	}
-};
-/**
-* 🆕 Type guard for React Action Errors
-* 
-* @param error - Error to check
-* @returns True if error is a ReactActionError
-*/
-function isReactActionError(error) {
-	return error instanceof ReactActionError;
-}
-
-//#endregion
-//#region src/action-schema.ts
-/**
-* Zod 스키마를 JSON Schema로 변환 (Zod 4 네이티브 API)
-*
-* @param schema - Zod 스키마
-* @returns JSON Schema (draft-7)
-*/
-function zodToJsonSchema(schema, zodModule) {
-	return zodModule.toJSONSchema(schema, {
-		target: "draft-7",
-		metadata: zodModule.globalRegistry
-	});
-}
-/**
-* Zod 스키마 기반 Action 정의
-*
-* defineTool 패턴을 기반으로 context-action에 맞게 구현:
-* - Single Source of Truth: Zod 스키마로 타입 + 검증 + 메타데이터 통합
-* - 런타임 검증: validate(), safeParse()
-* - Tool Chain 호환: toMCP(), toOpenAI(), toAnthropic()
-*
-* @param options - Action 정의 옵션
-* @param zodModule - Zod 모듈 (peerDependency로 주입)
-* @returns UnifiedAction 인스턴스
-*
-* @example
-* ```typescript
-* import { z } from 'zod';
-* import { defineAction } from '@context-action/core';
-*
-* const updateUserAction = defineAction({
-*   name: 'updateUser',
-*   description: 'Update user profile',
-*   parameters: z.object({
-*     id: z.string().min(1).meta({ description: 'User ID' }),
-*     name: z.string().min(2).max(50).meta({ description: 'User name' }),
-*     email: z.string().email().optional(),
-*   }),
-* }, z);
-*
-* // 검증
-* const validated = updateUserAction.validate({ id: '123', name: 'John' });
-*
-* // Tool chain 변환
-* const mcpTool = updateUserAction.toMCP();
-* ```
-*/
-function defineAction(options, zodModule) {
-	const { name, description, parameters } = options;
-	const jsonSchema = zodToJsonSchema(parameters, zodModule);
-	return {
-		name,
-		description,
-		zodSchema: parameters,
-		jsonSchema,
-		validate: (payload) => {
-			return parameters.parse(payload);
-		},
-		safeParse: (payload) => {
-			return parameters.safeParse(payload);
-		},
-		toJSONSchema: () => jsonSchema,
-		toMCP: () => ({
-			name,
-			description,
-			inputSchema: jsonSchema
-		}),
-		toOpenAI: () => ({
-			type: "function",
-			function: {
-				name,
-				description,
-				parameters: {
-					type: "object",
-					properties: jsonSchema.properties ?? {},
-					required: jsonSchema.required
-				}
-			}
-		}),
-		toAnthropic: () => ({
-			name,
-			description,
-			input_schema: jsonSchema
-		})
-	};
-}
-/**
-* 다중 Action 스키마 생성
-*
-* 여러 defineAction을 묶어서 ActionSchemaMap 생성
-*
-* @param actions - UnifiedAction 맵
-* @returns ActionSchemaMap
-*
-* @example
-* ```typescript
-* const userActionSchema = createActionSchema({
-*   updateUser: defineAction({ ... }, z),
-*   deleteUser: defineAction({ ... }, z),
-* });
-*
-* type UserActions = InferActionPayloadMap<typeof userActionSchema>;
-* ```
-*/
-function createActionSchema(actions) {
-	return actions;
-}
-/**
-* Zod 모듈을 바인딩한 defineAction 팩토리 생성
-*
-* 매번 z 모듈을 전달하지 않아도 되도록 팩토리 패턴 제공
-*
-* @param zodModule - Zod 모듈
-* @returns defineAction 함수 (z 바인딩됨)
-*
-* @example
-* ```typescript
-* import { z } from 'zod';
-* import { createActionFactory } from '@context-action/core';
-*
-* const defineAction = createActionFactory(z);
-*
-* const updateUser = defineAction({
-*   name: 'updateUser',
-*   parameters: z.object({ id: z.string() }),
-* });
-* ```
-*/
-function createActionFactory(zodModule) {
-	return (options) => {
-		return defineAction(options, zodModule);
-	};
-}
-
 //#endregion
 exports.ActionGuard = ActionGuard;
 exports.ActionRegister = ActionRegister;
 exports.ActionRegisterDestroyedError = ActionRegisterDestroyedError;
 exports.ActionTimeoutError = ActionTimeoutError;
 exports.ActionValidationError = ActionValidationError;
-exports.ReactActionError = ReactActionError;
-exports.ReactDevUtils = ReactDevUtils;
-exports.createActionFactory = createActionFactory;
-exports.createActionHandler = createActionHandler;
-exports.createActionSchema = createActionSchema;
-exports.defineAction = defineAction;
 exports.executeParallel = executeParallel;
 exports.executeRace = executeRace;
 exports.executeSequential = executeSequential;
 exports.isActionRegisterDestroyedError = isActionRegisterDestroyedError;
 exports.isActionTimeoutError = isActionTimeoutError;
-exports.isActionValidationError = isActionValidationError;
-exports.isReactActionError = isReactActionError;
-exports.zodToJsonSchema = zodToJsonSchema;
+exports.isActionValidationError = isActionValidationError;