Middleware Extensibility

As discussed in the Architecture section, Cascaide is a graph executor that uses Redux to model local state.

Every Redux store in Cascaide comes with three built-in middlewares, applied in the following order:

Order	Middleware	Role
1	Persistence Middleware	Persists state changes to the configured persistor.
2	Hydration Middleware	Handles rehydrating state from persistence on load.
3	Orchestration Middleware	Drives the workflow execution — spawning nodes, routing actions, managing the lifecycle.

Every action must pass through these middlewares in the above order before it hits the store.

Adding Custom Middlewares

You can pass in extra middlewares to modify the stack. Any middlewares you provide will be inserted after the Persistence and Hydration middlewares.

This opens up three categories of extension:

Observe — Log or monitor actions.
Intercept — Block specific agent actions based on custom business logic (e.g., rate limiting, auth checks, etc.).
Augment — Inject extra data into an action’s payload before processing.

💡

Because custom middlewares run after Persistence and Hydration but before the action hits the store, they are well-positioned to gate or enrich actions without interfering with the core persistence guarantees.

Practical Guide

Let us set up a simple middleware that simply logs every time a new node is activated. We will add it to the client as server middleware stacks.

Middleware definition


import { Middleware } from '@reduxjs/toolkit';
import { addActiveNode} from '@cascaide-ts/core'
export const exampleMiddleware = (): Middleware => {
    return (store) => (next) => async (action: any) => {
        if (addActiveNode.match(action)) {
            console.log('NEW NODE ACTIVATED');
        }
        return next(action);
    }
}

Adding to Middleware Stack

Client


export default function HomePage() {
  return (
    <WorkflowProvider 
      initialNodeId="chat_init"
      initialNodeName="chat"
      config={clientWorkflowConfig}
      actionRelayEndpoint='/api/workflow/action'
      persistenceEndpoint='/api/workflow/persistence'
      extraMiddlewares={[extraMiddleware()]}
    >
      <WorkflowRenderer />
    </WorkflowProvider>
  );
}

server


export const serverWorkflowConfig:WorkflowHandlerConfig={
  workflowGraph:serverWorkflowGraph,
  persistor: workflowpersistor, 
  maxExecutionTime: MAX_EXECUTION_TIME,
  safeBuffer: SAFE_BUFFER,
  extraMiddlewares:[extraMiddleware()]
}