@context-action/core 0.8.6 → 0.9.0

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.
@@ -225,12 +242,21 @@ await actions.dispatch('backgroundTask', data, {
   queuePriority: 5
 });
 
-// Execution timeout
-await actions.dispatch('timedAction', data, {
-  timeout: 5000
-});
+// Wall-clock timeout (queue wait + retry delay included).
+// Rejects with ActionTimeoutError while the internal operation drains safely.
+await actions.dispatch('timedAction', data, { timeout: 5000 });
 ```
 
+The default queue is single-slot. When a handler awaits another dispatch on
+the **same** register, make that nested call explicit with `{ immediate: true }`
+so it can run inside the current queue turn. Likewise, do not set
+`queuePriority` on an awaited nested `dispatchWithResult` call. Independent
+top-level dispatches should keep the queue defaults.
+
+Handlers that perform cancellable I/O can observe `controller.signal`. It is
+aborted for caller cancellation, timeout, provider teardown, and register
+shutdown.
+
 ### Result Collection with Strategies
 
 ```typescript
@@ -406,7 +432,7 @@ actions.register('riskyOperation', async (data, controller) => {
 // With retry configuration
 await actions.dispatch('apiCall', data, {
   retryOnError: {
-    maxAttempts: 3,
+    maxAttempts: 3, // Total attempts, including the first call
     delay: 1000
   }
 });
@@ -440,8 +466,11 @@ const registry = new ActionRegister({ name: 'MyApp' });
 
 // Use the registry...
 
-// Clean up all resources
-registry.destroy(); // Cleans up pipelines, guards, queues, stats
+// Begin terminal cleanup. New work is rejected immediately.
+registry.destroy();
+
+// Or await proof that started handlers settled and cleanup callbacks ran.
+await registry.destroyAsync();
 ```
 
 ## API Reference
@@ -472,7 +501,8 @@ registry.destroy(); // Cleans up pipelines, guards, queues, stats
 #### Utility Methods
 - `getName()` - Get registry name
 - `isDebugEnabled()` - Check if debug mode is enabled
-- `destroy()` - Clean up all resources
+- `destroy()` - Begin terminal cleanup without waiting
+- `destroyAsync()` - Resolve after started handlers settle and cleanup completes
 
 ### Configuration Interfaces
 
@@ -576,7 +606,7 @@ actions.destroy();
 1. **Use handler IDs** for better debugging and filtering
 2. **Enable replaceExisting** for React components to prevent duplicates
 3. **Use immediate: false** (default) to benefit from queue optimizations  
-4. **Call destroy()** when registry is no longer needed
+4. **Await destroyAsync()** when shutdown completion must be guaranteed
 5. **Use priority filtering** instead of excludeHandlerIds for better performance
 6. **Cache ActionRegister instances** - don't create new ones frequently
 
@@ -591,4 +621,4 @@ Apache-2.0
 - [Vanilla JS Guide](../../docs/en/guide/vanilla-js-guide.md) - Complete vanilla JavaScript guide
 - [Vanilla JS Examples](../../examples/vanilla-js/) - Interactive examples (counter, todo app)
 - [React Package](../react/README.md) - React integration
-- [Examples](../../example/README.md) - React example application
+- [Examples](../../example/README.md) - React example application