@calmo/task-runner 4.1.0 → 4.2.0

package/openspec/changes/add-middleware-support/proposal.md

@@ -0,0 +1,19 @@
+# Change: Add Middleware Support
+
+## Why
+
+Developers currently duplicate code for cross-cutting concerns like logging, error handling policies, context validation, and metrics across every task definition. This leads to code duplication, inconsistent behavior, and maintenance burden. There is no standard way to inject logic "around" task execution globally.
+
+## What Changes
+
+- **Middleware Interface**: Introduce a `Middleware<T>` type representing a function that wraps task execution.
+- **TaskRunnerBuilder**: Add a `.use(middleware)` method to register middleware functions.
+- **TaskRunner**:
+    - Store the chain of middleware.
+    - During execution, wrap the `Strategy.execute` call with the middleware chain (onion model).
+    - Ensure middleware runs *before* the task starts and *after* it finishes (or fails).
+
+## Impact
+
+- Affected specs: `task-runner`
+- Affected code: `TaskRunner.ts`, `TaskRunnerBuilder.ts`, `WorkflowExecutor.ts`, `contracts/Middleware.ts`

package/openspec/changes/add-middleware-support/specs/task-runner/spec.md

@@ -0,0 +1,34 @@
+## ADDED Requirements
+
+### Requirement: Global Middleware Support
+
+The system SHALL support registering global middleware functions that intercept and wrap the execution of every `TaskStep`.
+
+#### Scenario: Middleware Execution Order
+
+- **GIVEN** a `TaskRunner` with two middleware functions: `A` (outer) and `B` (inner)
+- **WHEN** a task is executed
+- **THEN** `A` runs before `B`
+- **AND** `B` runs before the task strategy
+- **AND** the task strategy runs
+- **AND** `B` runs after the task strategy
+- **AND** `A` runs after `B`.
+
+#### Scenario: Modifying Task Result
+
+- **GIVEN** a middleware that modifies the returned result
+- **WHEN** a task completes successfully
+- **THEN** the final result stored in the runner MUST match the result returned by the middleware.
+
+#### Scenario: Blocking Execution
+
+- **GIVEN** a middleware that returns a result *without* calling `next()`
+- **WHEN** the task is scheduled
+- **THEN** the task strategy SHALL NOT be executed
+- **AND** the task result SHALL be the one returned by the middleware.
+
+#### Scenario: Context Access
+
+- **GIVEN** a middleware function
+- **WHEN** it is invoked
+- **THEN** it SHALL have access to the current `TaskStep` and shared `context`.

package/openspec/changes/add-middleware-support/tasks.md

@@ -0,0 +1,9 @@
+## 1. Implementation
+
+- [ ] 1.1 Define `Middleware` and `MiddlewareNext` types in `src/contracts/Middleware.ts`.
+- [ ] 1.2 Update `TaskRunner` class to store a list of middleware functions.
+- [ ] 1.3 Implement `composeMiddleware` utility to create the onion chain.
+- [ ] 1.4 Update `WorkflowExecutor` or `TaskRunner` (wherever strategy is invoked) to wrap the strategy execution with composed middleware.
+- [ ] 1.5 Update `TaskRunnerBuilder` to expose `.use(middleware)` method.
+- [ ] 1.6 Add unit tests for Middleware composition and execution order.
+- [ ] 1.7 Add integration test demonstrating a Logging Middleware and a Policy Middleware (skipping task).

package/openspec/changes/add-resource-concurrency/tasks.md

@@ -7,3 +7,4 @@
 - [ ] 1.5 Update `WorkflowExecutor.executeTaskStep` (or equivalent completion logic) to release resources when a task finishes.
 - [ ] 1.6 Add unit tests for resource limiting in `tests/WorkflowExecutor.test.ts`.
 - [ ] 1.7 Add integration test for mixed resource usage in `tests/integration/resource-concurrency.test.ts`.
+- [ ] 1.8 Update README.md to include docs and examples on resource concurrency configuration

package/openspec/changes/allow-plugin-hooks/design.md

@@ -0,0 +1,51 @@
+# Plugin Hooks Design
+
+## Architecture
+
+We will extend the `PluginManager` to manage a list of hooks. The `WorkflowExecutor` will call these hooks at appropriate times.
+
+### Hook Interfaces
+
+```typescript
+export type PreTaskHookResult<TContext> =
+  | { action: "continue" }
+  | { action: "skip"; message?: string }
+  | { action: "fail"; error: Error };
+
+export type PreTaskHook<TContext> = (
+  step: TaskStep<TContext>,
+  context: TContext
+) => Promise<PreTaskHookResult<TContext> | void> | void; // void implies continue
+
+export type PostTaskHook<TContext> = (
+  step: TaskStep<TContext>,
+  context: TContext,
+  result: TaskResult
+) => Promise<TaskResult | void> | void; // void implies return original result
+```
+
+### PluginContext Extension
+
+```typescript
+export interface PluginContext<TContext> {
+    events: EventBus<TContext>;
+    preTask(hook: PreTaskHook<TContext>): void;
+    postTask(hook: PostTaskHook<TContext>): void;
+}
+```
+
+### Execution Flow
+
+**In `WorkflowExecutor.executeTaskStep`:**
+
+1.  **Run Pre-Hooks (Sequential)**
+    -   Iterate through registered pre-hooks.
+    -   If any returns `skip`, mark task skipped and return.
+    -   If any returns `fail`, mark task failed and return.
+    -   (Future: allow modifying context contextually? Context is mutable so yes).
+
+2.  **Execute Task** (Original logic)
+
+3.  **Run Post-Hooks (Sequential)**
+    -   Pass the result to hooks.
+    -   Hooks can return a new `TaskResult` to overwrite the current one.

package/openspec/changes/allow-plugin-hooks/proposal.md

@@ -0,0 +1,12 @@
+# Allow Plugin hooks
+
+## Summary
+Introduce pre-task and post-task hooks to the Plugin System, allowing plugins to intercept task execution, modify behavior, or transform results.
+
+## Motivation
+Current plugins are limited to "observation" via read-only events. To enable advanced use cases like caching, validation, or policy enforcement, plugins need to be able to intervene in the execution flow.
+
+## Scope
+-   **Pre-Task Hooks**: Runs before a task. Can skip, fail, or modify task/context.
+-   **Post-Task Hooks**: Runs after a task. Can modify the result.
+-   **Hook Registration**: Add `registerPreHook` and `registerPostHook` to `PluginContext`.

package/openspec/changes/allow-plugin-hooks/specs/post-task/spec.md

@@ -0,0 +1,21 @@
+# Post-Task Hooks Requirements
+
+## ADDED Requirements
+
+### Requirement: Execute Post-Task Hooks after task execution
+
+The `WorkflowExecutor` MUST execute all registered post-task hooks after a task completes (success or failure).
+
+#### Scenario: Running post hooks
+Given registered post-task hooks
+When a task finishes execution
+Then hooks are executed sequentially with access to the task result
+
+### Requirement: Modify result via hook
+
+The runner MUST allow post-task hooks to modify the task result.
+
+#### Scenario: Modifying result status
+Given a post-task hook that returns a new `TaskResult`
+When a task finishes
+Then the final result of the task is updated to the one returned by the hook

package/openspec/changes/allow-plugin-hooks/specs/pre-task/spec.md

@@ -0,0 +1,32 @@
+# Pre-Task Hooks Requirements
+
+## ADDED Requirements
+
+### Requirement: Execute Pre-Task Hooks before task execution
+
+The `WorkflowExecutor` MUST execute all registered pre-task hooks before running a task.
+
+#### Scenario: Running multiple hooks
+Given multiple registered pre-task hooks
+When a task is about to run
+Then hooks are executed sequentially in registration order
+
+### Requirement: Skip task execution via hook
+
+The runner MUST skip task execution if a pre-task hook returns a skip action.
+
+#### Scenario: Skipping task
+Given a pre-task hook that returns `{ action: "skip" }`
+When a task is about to run
+Then the task is marked as skipped
+And execution proceeds to the next task
+
+### Requirement: Fail task execution via hook
+
+The runner MUST fail task execution if a pre-task hook returns a fail action.
+
+#### Scenario: Failing task
+Given a pre-task hook that returns `{ action: "fail", error: Error("Reason") }`
+When a task is about to run
+Then the task is marked as failed with the provided error
+And failure cascades to dependent tasks

package/openspec/changes/allow-plugin-hooks/tasks.md

@@ -0,0 +1,7 @@
+- [-] Implement Plugin Hooks
+  - [ ] Define Hook Types and Interfaces <!-- id: 0 -->
+  - [ ] Update `PluginContext` to include `preTask` and `postTask` <!-- id: 1 -->
+  - [ ] Implement Hook Registry in `PluginManager` <!-- id: 2 -->
+  - [ ] Integrate Pre-Task Hooks in `WorkflowExecutor` <!-- id: 3 -->
+  - [ ] Integrate Post-Task Hooks in `WorkflowExecutor` <!-- id: 4 -->
+  - [ ] Add tests for hook execution and interruption <!-- id: 5 -->

package/openspec/changes/archive/2026-02-15-implement-plugin-system/design.md

@@ -0,0 +1,45 @@
+# Plugin System Design
+
+## Architecture
+
+The plugin system will resolve around a `PluginManager` that is owned by the `TaskRunner`.
+
+### Plugin Interface
+
+A plugin is defined as:
+
+```typescript
+export interface Plugin<TContext> {
+  name: string;
+  version: string;
+  install(context: PluginContext<TContext>): void | Promise<void>;
+}
+```
+
+### Plugin Context
+
+The `install` method receives a `PluginContext`, which exposes capabilities to the plugin:
+
+```typescript
+export interface PluginContext<TContext> {
+  events: EventBus<TContext>; // Access to listen/emit events
+  // Potentially other APIs in the future, e.g., registerTask, logger, etc.
+}
+```
+
+### Lifecycle
+
+1. **Registration**: Plugins are registered via `taskRunner.use(plugin)`.
+2. **Installation**: When `taskRunner.execute()` is called (or explicitly before), the `PluginManager` iterates over registered plugins and calls `install()`.
+3. **Execution**: Plugins listen to events or hooks during execution.
+
+### Error Handling
+
+- Implementation should handle plugin failures during `install` gracefully (fail fast or log and continue, defined by config).
+- Runtime errors in listeners should be caught to avoid crashing the runner, though `EventBus` current implementation might need review.
+
+## Components
+
+- `src/contracts/Plugin.ts`: Interface definition.
+- `src/PluginManager.ts`: Manages the list of plugins and their initialization.
+- `src/TaskRunner.ts`: Modified to include `use()` method and delegate to `PluginManager`.

package/openspec/changes/archive/2026-02-15-implement-plugin-system/proposal.md

@@ -0,0 +1,13 @@
+# Propose Plugin System
+
+## Summary
+Introduce a plugin system to the `task-runner` that allows external modules to alter behavior, listen to events, and interact with the execution context via a defined API.
+
+## Motivation
+Currently, extending the `task-runner` requires modifying the core codebase. To enable a more collaborative and decentralized development model, we need a way for developers to inject custom logic, middleware, or event listeners without touching the core.
+
+## Scope
+- Define a strict `Plugin` interface.
+- Implement a `PluginManager` to handle plugin lifecycle (registration, initialization).
+- Expose an `EventBus` and `PluginContext` to plugins.
+- Ensure plugins can intercept or react to workflow lifecycle events (`workflowStart`, `taskStart`, etc.).

package/openspec/changes/archive/2026-02-15-implement-plugin-system/specs/plugin-context/spec.md

@@ -0,0 +1,17 @@
+# Plugin Context Requirements
+
+## ADDED Requirements
+
+### Requirement: Expose EventBus to plugins
+
+The `PluginContext` passed to `install` MUST expose the `EventBus` (or equivalent API) to allow listening to events.
+
+#### Scenario: Listening to task events
+Given a plugin is being installed
+When it accesses `context.events`
+Then it can subscribe to `taskStart` and `taskEnd` events
+
+#### Scenario: Emitting custom events (Future)
+Given a plugin
+When it has access to the event bus
+Then it should be able to emit events (if allowed by design)

package/openspec/changes/archive/2026-02-15-implement-plugin-system/specs/plugin-loading/spec.md

@@ -0,0 +1,27 @@
+# Plugin Loading Requirements
+
+## ADDED Requirements
+
+### Requirement: Support registering plugins
+
+The `TaskRunner` MUST allow registering plugins via a `use` method or configuration.
+
+#### Scenario: Registering a valid plugin
+Given a `TaskRunner` instance
+When I call `use` with a valid plugin object
+Then the plugin is added to the internal plugin list
+
+#### Scenario: Registering an invalid plugin
+Given a `TaskRunner` instance
+When I call `use` with an invalid object (missing install method)
+Then it should throw an error or reject the plugin
+
+### Requirement: Initialize plugins before execution
+
+Plugins MUST be initialized (have their `install` method called) before the workflow starts.
+
+#### Scenario: Plugin initialization
+Given a registered plugin
+When `execute` is called on the `TaskRunner`
+Then the plugin's `install` method is called with the plugin context
+And the workflow execution proceeds only after `install` completes

package/openspec/changes/archive/2026-02-15-implement-plugin-system/tasks.md

@@ -0,0 +1,7 @@
+- [x] Implement Plugin System
+  - [x] Define `Plugin` and `PluginContext` interfaces <!-- id: 0 -->
+  - [x] Implement `PluginManager` class <!-- id: 1 -->
+  - [x] Update `TaskRunner` to support `use()` method <!-- id: 2 -->
+  - [x] Integrate `PluginManager` into `TaskRunner` lifecycle <!-- id: 3 -->
+  - [x] Verify `EventBus` exposure to plugins <!-- id: 4 -->
+  - [x] Add integration tests for a sample plugin <!-- id: 5 -->

package/openspec/changes/feat-completion-dependencies/proposal.md

@@ -0,0 +1,58 @@
+# Feature: Completion Dependencies (Finally Tasks)
+
+## User Story
+"As a developer, I want to define tasks that run even if their dependencies fail (e.g., cleanup/teardown), so that I can ensure resources are released and the system is left in a clean state regardless of workflow success."
+
+## The "Why"
+Currently, the `TaskRunner` strictly propagates failures: if Task A fails, all tasks depending on A are automatically skipped. This behavior is correct for logical dependencies (e.g., "Build" -> "Deploy"), but strictly prohibits "Teardown" or "Compensation" patterns (e.g., "Provision" -> "Test" -> "Deprovision").
+
+If "Test" fails, "Deprovision" is skipped, leaving expensive resources running.
+
+While a `continueOnError` proposal exists, it marks a task as "Optional" (allowing *all* dependents to proceed). It does not support the case where:
+1. "Test" is CRITICAL (if it fails, the workflow should eventually fail).
+2. "Deprovision" MUST run after "Test".
+3. "Publish Results" (dependent on "Test") MUST skip if "Test" fails.
+
+We need a way to define **Dependency Behavior** at the edge level.
+
+## The "What"
+We will extend the `dependencies` property in `TaskStep` to support granular configuration.
+
+### Current
+```typescript
+dependencies: ["TaskA", "TaskB"]
+```
+
+### Proposed
+```typescript
+dependencies: [
+  "TaskA",
+  { step: "TaskB", runCondition: "always" } // or 'complete'
+]
+```
+
+The `runCondition` determines when the dependent becomes ready:
+- `success` (Default): Ready only if dependency succeeds.
+- `always`: Ready if dependency succeeds OR fails. (If dependency is *skipped*, the dependent is still skipped, as the parent never ran).
+
+## Acceptance Criteria
+- [ ] Support `dependencies` as an array of `string | DependencyConfig`.
+- [ ] `DependencyConfig` schema: `{ step: string; runCondition?: 'success' | 'always' }`.
+- [ ] **Scenario 1 (Success):** A -> B(always). A succeeds. B runs.
+- [ ] **Scenario 2 (Failure):** A -> B(always). A fails. B runs.
+- [ ] **Scenario 3 (Skip):** X(fail) -> A -> B(always). X fails, A skips. B skips (because A never ran).
+- [ ] **Scenario 4 (Hybrid):** A(fail) -> B(always) -> C(standard).
+    - A fails.
+    - B runs (cleanup).
+    - C skips (because B succeeded, but C implicitly depends on the *chain*? No, standard DAG. C depends on B. If B succeeds, C runs. Wait.)
+
+**Refining Scenario 4:**
+If C depends on B, and B runs (cleaning up A), C runs.
+This might not be desired if C assumes A succeeded.
+*Constraint:* If C depends on B, it only cares about B. If C cares about A, it must depend on A explicitly.
+*User Responsibility:* Users must ensure that if C depends on B (cleanup), C can handle the fact that A might have failed. Or, C should also depend on A (standard) if it needs A's success.
+
+## Constraints
+- **Backward Compatibility:** Existing `string[]` syntax must work exactly as before.
+- **Cycle Detection:** The validator must treat `{ step: "A" }` identical to `"A"` for cycle checks.
+- **Type Safety:** The context passed to the task remains `TContext`. The task must safeguard against missing data if a dependency failed (e.g., checking `ctx.data` before use).

package/openspec/changes/feat-completion-dependencies/tasks.md

@@ -0,0 +1,46 @@
+# Engineering Tasks: Completion Dependencies
+
+## 1. Contracts & Types
+- [ ] **Modify `src/TaskStep.ts`**
+    - Define `export type TaskRunCondition = 'success' | 'always';`
+    - Define `export interface TaskDependencyConfig { step: string; runCondition?: TaskRunCondition; }`
+    - Update `TaskStep` interface: `dependencies?: (string | TaskDependencyConfig)[];`
+
+## 2. Validation Logic
+- [ ] **Update `src/TaskGraphValidator.ts`**
+    - Update `validate` method to handle mixed string/object arrays.
+    - Extract the dependency name correctly for cycle detection and adjacency lists.
+    - Ensure `checkMissingDependencies` checks the `step` property of config objects.
+
+## 3. Core Logic (TaskStateManager)
+- [ ] **Update `src/TaskStateManager.ts`**
+    - **Data Structures**:
+        - Change `dependencyGraph` to store metadata: `Map<string, { step: TaskStep<TContext>, condition: TaskRunCondition }[]>`.
+    - **Initialization**:
+        - Parse the mixed `dependencies` array during `initialize`.
+        - Store the `runCondition` (default 'success') in the graph.
+    - **Failure Handling (`cascadeFailure`)**:
+        - When a task fails (or is skipped? No, only Failures trigger 'always'. Skips should still cascade Skips):
+        - Iterate dependents.
+        - If dependent has `condition === 'always'`:
+            - Treat as "success" (call `handleSuccess` logic or equivalent: decrement count).
+            - Do NOT add to `cascade` queue.
+        - If dependent has `condition === 'success'`:
+            - Mark skipped (existing logic).
+            - Add to `cascade` queue.
+    - **Skip Handling**:
+        - If a task is SKIPPED, dependents with `runCondition: 'always'` should ALSO be skipped (because the parent never ran).
+        - Ensure `cascadeFailure` distinguishes between "Failed" vs "Skipped" when checking the condition.
+
+## 4. Testing
+- [ ] **Unit Tests (`tests/TaskStateManager.test.ts`)**
+    - Test initialization with mixed types.
+    - Test failure propagation with 'always' condition (dependent runs).
+    - Test skip propagation with 'always' condition (dependent skips).
+- [ ] **Integration Tests (`tests/TaskRunner.test.ts`)**
+    - Create a "Teardown" scenario:
+        - Step 1: Setup (Success)
+        - Step 2: Work (Failure) -> Depends on 1
+        - Step 3: Cleanup (Success) -> Depends on 2 (Always)
+    - Verify Step 3 runs.
+    - Verify final Workflow status (should be Failure because Step 2 failed).

package/openspec/changes/feat-task-loop/proposal.md

@@ -0,0 +1,22 @@
+# Change: feat-task-loop
+
+## Why
+
+Users often need to orchestrate tasks that involve waiting for a condition to be met, such as polling an API for a deployment status or waiting for a database to be healthy. Currently, this logic must be implemented imperatively within the `run` method of a task, which obscures the intent and mixes orchestration concerns with business logic.
+
+## What Changes
+
+- Add a `loop` configuration to the `TaskStep` interface.
+- Introduce a `LoopingExecutionStrategy` that wraps other strategies to handle conditional re-execution.
+- The `loop` configuration will support:
+    - `interval`: Time in milliseconds to wait between iterations.
+    - `maxIterations`: Maximum number of times to run the task.
+    - `until`: A predicate function `(context, result) => boolean` that determines when the loop should stop.
+
+## Impact
+
+- **Affected Specs**: `task-runner`
+- **Affected Code**:
+    - `src/TaskStep.ts`: Update interface.
+    - `src/strategies/LoopingExecutionStrategy.ts`: New file.
+    - `src/TaskRunnerBuilder.ts`: Integrate the new strategy.

package/openspec/changes/feat-task-loop/specs/task-runner/spec.md

@@ -0,0 +1,34 @@
+## ADDED Requirements
+
+### Requirement: Task Looping
+
+The `TaskStep` interface SHALL support an optional `loop` property of type `TaskLoopConfig` to enable conditional re-execution of a task (polling).
+
+#### Scenario: Loop until condition met
+
+- **GIVEN** a task with a `loop` configuration
+- **AND** the `loop.until` predicate returns `false`
+- **THEN** the task SHALL re-execute after the specified `interval`.
+- **WHEN** the `loop.until` predicate returns `true`
+- **THEN** the task SHALL complete successfully with the last result.
+
+#### Scenario: Max iterations reached
+
+- **GIVEN** a task with a `loop` configuration
+- **AND** the task has re-executed `maxIterations` times without the predicate returning `true`
+- **THEN** the task SHALL fail with an error indicating the loop limit was reached.
+
+#### Scenario: Integration with Retries
+
+- **GIVEN** a task with both `retry` and `loop` configurations
+- **WHEN** the task fails (throws an error)
+- **THEN** the `RetryingExecutionStrategy` SHALL handle the retry logic first.
+- **AND** the loop iteration SHALL only count once the task executes successfully (or fails after retries).
+
+#### Scenario: Loop Config Structure
+
+- **GIVEN** a `TaskLoopConfig` object
+- **THEN** it SHALL support:
+  - `interval`: Time in milliseconds to wait between iterations (default: 0).
+  - `maxIterations`: Maximum number of iterations (default: 1).
+  - `until`: A predicate function `(context: TContext, result: TaskResult) => boolean`.

package/openspec/changes/feat-task-loop/tasks.md

@@ -0,0 +1,8 @@
+## 1. Implementation
+
+- [ ] 1.1 Define `TaskLoopConfig` interface in `src/contracts/TaskLoopConfig.ts`.
+- [ ] 1.2 Update `TaskStep` interface in `src/TaskStep.ts` to include optional `loop: TaskLoopConfig`.
+- [ ] 1.3 Implement `LoopingExecutionStrategy` in `src/strategies/LoopingExecutionStrategy.ts`.
+- [ ] 1.4 Update `TaskRunnerBuilder` in `src/TaskRunnerBuilder.ts` to include `LoopingExecutionStrategy`.
+- [ ] 1.5 Add unit tests for `LoopingExecutionStrategy`.
+- [ ] 1.6 Verify integration with `RetryingExecutionStrategy` (looping should happen outside retries).

package/openspec/specs/plugin-context/spec.md

@@ -0,0 +1,19 @@
+# plugin-context Specification
+
+## Purpose
+TBD - created by archiving change implement-plugin-system. Update Purpose after archive.
+## Requirements
+### Requirement: Expose EventBus to plugins
+
+The `PluginContext` passed to `install` MUST expose the `EventBus` (or equivalent API) to allow listening to events.
+
+#### Scenario: Listening to task events
+Given a plugin is being installed
+When it accesses `context.events`
+Then it can subscribe to `taskStart` and `taskEnd` events
+
+#### Scenario: Emitting custom events (Future)
+Given a plugin
+When it has access to the event bus
+Then it should be able to emit events (if allowed by design)
+

package/openspec/specs/plugin-loading/spec.md

@@ -0,0 +1,29 @@
+# plugin-loading Specification
+
+## Purpose
+TBD - created by archiving change implement-plugin-system. Update Purpose after archive.
+## Requirements
+### Requirement: Support registering plugins
+
+The `TaskRunner` MUST allow registering plugins via a `use` method or configuration.
+
+#### Scenario: Registering a valid plugin
+Given a `TaskRunner` instance
+When I call `use` with a valid plugin object
+Then the plugin is added to the internal plugin list
+
+#### Scenario: Registering an invalid plugin
+Given a `TaskRunner` instance
+When I call `use` with an invalid object (missing install method)
+Then it should throw an error or reject the plugin
+
+### Requirement: Initialize plugins before execution
+
+Plugins MUST be initialized (have their `install` method called) before the workflow starts.
+
+#### Scenario: Plugin initialization
+Given a registered plugin
+When `execute` is called on the `TaskRunner`
+Then the plugin's `install` method is called with the plugin context
+And the workflow execution proceeds only after `install` completes
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calmo/task-runner",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "A lightweight, type-safe, and domain-agnostic task orchestration engine. It resolves a Directed Acyclic Graph (DAG) of steps, executes independent tasks in parallel, and manages a shared context across the pipeline.",
   "repository": {
     "type": "git",

package/src/EventBus.ts

@@ -61,11 +61,10 @@ export class EventBus<TContext> {
       | undefined;
     if (listeners) {
       for (const listener of listeners) {
-        // We use Promise.resolve().then() to schedule the listener on the microtask queue,
+        // We use queueMicrotask() to schedule the listener on the microtask queue,
         // ensuring the emit method remains non-blocking.
-        // The final .catch() ensures that any errors in the promise infrastructure itself are logged.
-        Promise.resolve()
-          .then(() => {
+        queueMicrotask(() => {
+          try {
             try {
               const result = listener(data);
               if (result instanceof Promise) {
@@ -84,14 +83,14 @@ export class EventBus<TContext> {
                 error
               );
             }
-          })
-          .catch((error) => {
-            // detailed handling for the promise chain itself
+          } catch (error) {
+            // detailed handling for the microtask execution itself
             console.error(
               `Unexpected error in event bus execution for ${String(event)}:`,
               error
             );
-          });
+          }
+        });
       }
     }
   }

package/src/PluginManager.ts

@@ -0,0 +1,41 @@
+import { Plugin, PluginContext } from "./contracts/Plugin.js";
+
+/**
+ * Manages the lifecycle of plugins.
+ */
+export class PluginManager<TContext> {
+  private plugins: Plugin<TContext>[] = [];
+
+  constructor(private context: PluginContext<TContext>) {}
+
+  /**
+   * Registers a plugin.
+   * @param plugin The plugin to register.
+   */
+  public use(plugin: Plugin<TContext>): void {
+    // Check if plugin is already registered
+    if (this.plugins.some((p) => p.name === plugin.name)) {
+      // For now, we allow overwriting or just warn?
+      // Let's just allow it but maybe log it if we had a logger.
+      // Strict check: don't allow duplicate names.
+      throw new Error(`Plugin with name '${plugin.name}' is already registered.`);
+    }
+    this.plugins.push(plugin);
+  }
+
+  /**
+   * Initializes all registered plugins.
+   */
+  public async initialize(): Promise<void> {
+    for (const plugin of this.plugins) {
+      await plugin.install(this.context);
+    }
+  }
+
+  /**
+   * Returns the list of registered plugins.
+   */
+  public getPlugins(): ReadonlyArray<Plugin<TContext>> {
+    return this.plugins;
+  }
+}