OpenClaw Middleware Suite

Because 'Autonomous' shouldn't mean 'Uncontrolled.' 🦞

A 6-in-1 middleware suite for OpenClaw. These middlewares sit between your agent and and the systems it can affect — intercepting every turn and every tool call, enforcing Human-in-the-Loop gates, redacting PII, blocking prompt injection, routing to the right model, and capping token spend. All locally. Zero telemetry. Nothing leaves your machine.

Plugin  •  Programmatic Usage  •  Contributing

The Problem

A single OpenClaw session can read your codebase, run arbitrary shell commands, manage your Google Drive, send emails on your behalf, and push code to production — all autonomously. And every turn along the way spends tokens, picks a model, and accumulates context.

Today there is no layer between "the agent decided to do something" and "it happened." That gap hides three distinct problems — and they rarely share a solution:

• Safety gaps. Sandboxing stops the agent from escaping its container. Inside that container, it still holds the keys to the kingdom: API tokens, file system access, outbound network, email credentials. One hallucinated rm -rf, one prompt injection buried in a fetched document, one leaked SSN in a tool argument — and you're dealing with real damage.
• Runaway cost. Every turn re-sends the full context window. Every request picks whatever model was wired in, whether the task needs it or not. A long coding session on a frontier model can burn through dollars in minutes, most of it spent re-reading stale history at premium rates.
• Degrading context. As sessions grow, the agent loses its earliest instructions, forgets key decisions, and starts contradicting itself. Naive truncation throws away what matters; doing nothing blows the budget.

That's what this suite is for.

The Solution

Sapience AI acts as the control plane for OpenClaw. Six middlewares — each solving a distinct failure mode — work together in a single pipeline.

Four govern and protect the action surface:

• HITL — Human approval for dangerous actions
• Guardrail — Block prompt injection, data exfiltration, destructive commands
• PII Sanitizer — Detect & redact sensitive data before it leaves
• Tool Call Limit — Enforce session & request budgets

Two optimize the request itself:

• Context Editing — Intelligent context window compaction, preserving what matters
• Model Routing — Route requests to the right model for the job

Together, they ensure every turn is safe, observable, and cost-effective.

The Middlewares

The suite ships in two consumption modes, and the rest of this README is organized around that split:

• Plugin — install once, manage with the dashboard and sai CLI. Zero code. The OpenClaw gateway loads the middlewares for you and wires every hook.
• Programmatic Usage — import { ... } from '@sapience-ai-corporation/openclaw-middleware-suite/<middleware>'. Embed any subset directly in a Node app, bring your own pipeline, mix and match.

Both modes share the same on-disk config store, so you can start with the plugin and graduate into programmatic embedding without re-learning anything.

Plugin

The plugin is the zero-code path: install the npm package, configure once with sai init, and the OpenClaw gateway loads all six middlewares and wires every hook. Every operational concern — toggling middlewares on/off, editing policies, viewing audit logs, syncing model catalogs — happens through the dashboard or sai CLI.

Quick Start

1. Install

# From npm (published plugin)
openclaw plugins install @sapience-ai-corporation/openclaw-middleware-suite

# Or from source
git clone https://github.com/Sapience-AI/openclaw-middleware-suite.git
cd openclaw-middleware-suite
npm install && npm run build
openclaw plugins install --link .

# Expose the `sai` CLI on your PATH (Windows users — admin / Developer Mode required)
mkdir -p ~/.local/bin
chmod +x ~/.openclaw/extensions/sapience-ai-suite/dist/index.js
ln -sf ~/.openclaw/extensions/sapience-ai-suite/dist/index.js ~/.local/bin/sai

2. Configure

# Interactive wizard — walks you through security level, modules, and policies
sai init

# Start the gateway — dashboard served at http://localhost:9000/dashboard
openclaw gateway start

That's it. From here, every middleware can be toggled, configured, and inspected from the Dashboard or its dedicated sai <middleware> … CLI subcommand (links inside each middleware section below).

How the Plugin Works

A few facts that apply to all six middlewares once they're loaded as a plugin — worth knowing before you tweak anything:

• One authoritative disk store. All six share the same config file: ~/.openclaw/sapience-ai-suite/sapience-ai-suite.json. The dashboard, the sai CLI, and the middlewares themselves all read and write the same JSON. There is no per-middleware config file scattered around the filesystem.
• Plugin-level on/off flag. Each middleware has a boolean toggle at plugin_config.middlewares[name] in that file (managed via the dashboard's overview page or sai init). When the flag is false, the plugin runtime short-circuits the corresponding hook — the middleware code isn't executed, so disabling is free of cost.
• Operational config lives under each middleware's sub-tree. hitl, context_editing, model_routing, guardrail, pii_sanitizer, tool_call_limit — each owns its own block. (HITL nests its user config under hitl.policy; Context Editing under context_editing.configOverrides.) These are what the dashboard editors and sai <middleware> CLI subcommands manipulate.
• The plugin runtime always passes {} at initialize(). It relies entirely on the disk overlay for configuration. The one exception is Context Editing, which receives { pluginApi } so its ICC LLM extraction can dispatch through OpenClaw's plugin API. This is what makes plugin behavior fully reproducible: defaults + whatever's in sapience-ai-suite.json, nothing else.

Middlewares

Quick links: HITL · Context Editing · Model Routing · Guardrail · PII Sanitizer · Tool Call Limit.

:shield: Human-in-the-Loop (HITL)

The last line of defense. Every action your agent takes is evaluated against a security policy. Dangerous actions require explicit human approval before they execute.

Why It Exists

AI agents make mistakes. They hallucinate file paths, misinterpret instructions, and occasionally try to do things that would be catastrophic in production. HITL ensures that a human reviews high-risk actions before they happen — not after.

How It Works

Tool Call Arrives
  │
  ├─ Policy Lookup ─── ALLOW ──→ Execute immediately
  │
  ├─ Policy Lookup ─── DENY ───→ Block with reason
  │
  └─ Policy Lookup ─── ASK ────→ Risk Assessment
                                    │
                                    ├─ Destructive classifier
                                    ├─ Irreversibility scorer (0-100)
                                    └─ Memory risk forecaster
                                    │
                                    ▼
                                 Approval Queue
                                    │
                                    ├─ /approve ──→ Execute
                                    ├─ /approve <TOTP> ──→ Execute (MFA verified)
                                    └─ /deny ──→ Block

Features — vs. ClawReins

ClawReins is the closest comparable HITL layer for OpenClaw. The two share a common foundation — three-decision policies, irreversibility scoring, destructive command detection, and a WhatsApp/Telegram approval channel. Sapience HITL extends that foundation in two places that matter most: a broader set of protected tools, and an approval mechanism the agent can't bypass.

Legend: ✅ supported  ·  ❌ not present

Any unmapped tool falls through to defaultAction (ASK).

CLI

sai hitl policy           # View/manage security policies
sai hitl stats            # View approval statistics
sai hitl audit            # View decision audit trail
sai hitl reset            # Reset statistics

:brain: Context Editing

Intelligent context window compaction. Long sessions don't lose critical context — the middleware automatically compresses old messages while preserving what matters.

Why It Exists

LLM context windows are finite — and expensive. Every token in the context window costs money on every single request. As a session grows, you're paying to re-read thousands of tokens of stale conversation history that the agent no longer needs. A 120K-token session hitting Opus 4.7 on every turn can burn through dollars in minutes, most of it on context the model is barely using.

And it's not just cost. In long coding sessions, the agent gradually loses its earliest instructions, forgets key decisions, and starts contradicting itself as critical context gets pushed out by noise. Naive truncation throws away important context indiscriminately.

Context Editing solves both problems: it compresses old messages using LLM-powered extraction (ICC), keeping token counts — and costs — under control while preserving the context that actually matters.

How It Works

Turn Begins
  │
  └─ before_model_resolve hook ──→ (fires BEFORE OpenClaw's SessionManager opens the JSONL)
                                          │
                                          ├─ Walk session JSONL
                                          │    ├─ Count user messages
                                          │    └─ Sum assistant token usage
                                          │
                                          ├─ Evaluate triggers
                                          │    ├─ Token count > threshold?
                                          │    ├─ Message count > threshold?
                                          │    └─ Adaptive rules?
                                          │
                                          ▼  (if triggered)
                                        Run ICC extraction
                                          ├─ Priority Preservation
                                          ├─ Conflict Resolution
                                          └─ Entity Locks
                                          │
                                          ▼
                                        Append compaction entry to JSONL
                                          │
                                          ▼
  └─ OpenClaw opens SessionManager ──→  Reads compacted JSONL
                                          │
                                          ▼
                                        LLM call sees compacted history

The single-hook design does everything in one place: detect, extract, and write — all before OpenClaw's own SessionManager opens the JSONL, so there's no concurrent-SM-on-same-file race. The same turn's LLM call sees the compacted history (no one-turn lag). Per-turn assistant token usage is read directly from the persisted JSONL entries, so the tokensSaved metric stays provider-precise without needing a separate push hook.

ICC Pipeline (Intelligent Context Compression)

Features — vs. OpenClaw's Built-in Compaction

OpenClaw already ships a robust compaction pipeline: when a prompt would overflow the context window, it splits the transcript into chunks, summarizes each one, then merges the partials — a bulk summarizer built to survive oversized tool outputs, tool-call pairing constraints, and transient API failures. Sapience Context Editing does not replace that pipeline — it adds a cheaper, steerable fast path on top of it.

The fast path is a single LLM call whose output (the ICC extraction: entities, conflicts, priorities) is the compaction summary. One call means the prompt can be user-steered, the model can be swapped, and compaction can fire early on your own thresholds instead of waiting for overflow. If the ICC call ever fails — for example, on a transcript too large for the extraction model's window — the middleware simply skips that turn and OpenClaw's native overflow-triggered compaction handles it on the next prompt exactly as it would for a vanilla install. You never lose coverage; you just lose the steering on the overflow edge case.

Legend: ✅ supported  ·  ❌ not present

CLI

sai ctx stats     # Compaction state, token savings, and compaction history
sai ctx reset     # Clear compaction state

:zap: Model Routing

Route every request to the right model. Simple tasks go to fast, cheap models. Complex reasoning goes to the best. Automatic fallbacks, multi-provider support, and real-time cost tracking.

Why It Exists

Not every request needs GPT-5 or Claude Opus. A simple "list files in this directory" doesn't need a $0.015/1K-token model — but without routing, that's what it gets. Model Routing scores request complexity in real time and routes to the optimal model tier, cutting costs by up to 70% without sacrificing quality where it matters.

How It Works

Incoming Request
  │
  ├─ Complexity Scorer
  │    ├─ Message length
  │    ├─ Instruction complexity
  │    ├─ Tool usage patterns
  │    └─ Reasoning depth signals
  │
  ├─ Tier Assignment ──→ simple | standard | complex | reasoning
  │
  ├─ Model Selection ──→ Primary model for tier
  │    └─ Fallback chain if primary fails
  │
  └─ Provider Routing ──→ Route to correct API endpoint
       ├─ OpenAI format
       ├─ Anthropic format
       └─ Google format

Tier System

Features — vs. Manifest

Manifest is the closest comparable complexity-based model router — both share the same 23-dimension scoring core derived from the same lineage. The two target different deployment models: Manifest ships as a Docker service with a multi-tenant web dashboard and Postgres backend; Sapience Model Routing is an OpenClaw plugin running on the developer's machine with a local JSON config and CLI. The table below focuses on what Sapience adds on top of the shared scoring foundation — in particular per-session model pinning and auto prompt-cache marker injection, which compound to keep the provider's cached prefix warm across every turn of a pinned session.

Legend: ✅ supported  ·  ❌ not present

CLI

sai router stats       # Daily cost ledger + per-model breakdown + alerts
sai router config      # View / edit profile, thresholds, exclusions
sai router tiers       # Inspect tier-to-model assignments
sai router models      # Sync live model catalog (LiteLLM, 24h cache)
sai router test        # Score a sample request without forwarding
sai router reset       # Reset cost history / session state

Note: Toggling Model Routing on/off requires a gateway restart. The dashboard handles this automatically with a reconnection overlay.

:lock: Guardrail

Multi-layer defense against prompt injection, data exfiltration, and destructive commands. Scans both input and output surfaces with regex, heuristic, and entropy-based detection.

Why It Exists

Prompt injection is the #1 attack vector against AI agents. A single malicious instruction hidden in a document, email, or web page can hijack your agent's behavior — making it exfiltrate secrets, delete data, or execute arbitrary commands. Guardrail catches these attacks at multiple detection layers before they can cause harm.

Detection Layers

Guard Modules

Key Features

• Input + output scanning — Covers both prompt injection and data leakage
• Configurable actions — BLOCK, WARN, REDACT per rule
• Confidence filtering — Adjustable sensitivity to reduce false positives
• Dry-run mode — Log detections without blocking (for tuning)
• Custom patterns — Add your own regex rules for domain-specific threats

Features — vs. OpenClaw Shield & OpenGuardrails

The two closest comparables are OpenClaw Shield (Knostic) — a lightweight OpenClaw plugin with five independently-toggleable policy layers, including an advisory "security gate" tool that relies on the agent obeying injected instructions — and OpenGuardrails / MoltGuard — a full-stack platform with an agent-side plugin talking to a hosted Core service that runs a 10-scanner content model and a behavioral rule engine over tool-call sequences. Sapience Guardrail takes a different stance from both: everything runs in-process on OpenClaw's native hooks, and the before_message_write hook actually rewrites the persisted transcript so the LLM can never see the pre-redacted content — not just on the next turn, but on the current one. The rows below focus on the capabilities that actually differ; shared basics (regex scanning, OpenClaw plugin integration, PII redaction) are omitted.

Legend: ✅ supported  ·  ⚠️ partial  ·  ❌ not present

What's genuinely unique to each

• OpenClaw Shield — per-layer toggles (L1–L5) so you can ship a degraded config when a host lacks a given hook; advisory L5 gate relies on the agent obeying injected policy rather than host enforcement.
• OpenGuardrails / MoltGuard — hosted behavioral rule engine that catches multi-turn attack patterns (credential read → network write), a 10-scanner content model spanning NSFW / MCP poisoning / off-topic drift, and a managed dashboard with a quota system.
• Sapience Guardrail — synchronous transcript rewrite so the LLM never sees pre-redacted content; Unicode NFKC + homoglyph + zero-width normalization pre-scan; entropy-based obfuscation detection; full-depth L2 stack (sensitive-paths + egress allowlist + private-IP SSRF + destructive commands) firing before any tool executes; confidence-filtered matching to suppress rephrasing false positives.

What We Adopted From Each

Sapience Guardrail did not emerge in a vacuum. Both comparables contributed foundational ideas we built on — we name them explicitly below.

The one thing neither comparable does: combine pre-execution interception with post-execution transcript scanning. OpenGuardrails scans text but can't block tools. OpenClaw Shield blocks tools but can't scan transcripts. Sapience does both in the same pipeline.

Configuration

{
  "dryRunMode": false,
  "entropyThreshold": 4.0,
  "sensitivePaths": { "enabled": true, "action": "BLOCK" },
  "egressControl": { "enabled": true, "blockDataSending": true },
  "destructiveCommands": { "enabled": true, "action": "BLOCK" },
  "moderation": { "rewriteThreshold": "HIGH" },
  "outputScrubber": { "enabled": false, "dryRunMode": false }
}

The middleware's on/off switch is the plugin-level flag (plugin_config.middlewares.guardrail in sapience-ai-suite.json, managed via the dashboard or sai init), not a field inside this config. The sub-feature enabled flags above (sensitivePaths, egressControl, destructiveCommands, outputScrubber) toggle individual guards within the guardrail middleware when it's already running. Output scrubber is double-gated: the master Guardrail toggle must be on AND outputScrubber.enabled must be true. Both default to false so a fresh install ships with neither active — opt in via the dashboard's Guardrail → Output tab or sai guardrail output toggle enable.

moderation.rewriteThreshold controls the severity bar for the async → sync cache bridge. Accepts MEDIUM, HIGH, or CRITICAL — default is HIGH. Flags at or above the threshold trigger a transcript rewrite in before_message_write (hard block); flags below are logged audit-only and pass through so the LLM's own safety layer can handle the gray zone without a synthetic [GUARDRAIL] marker replacing the user's prompt. Set to MEDIUM for maximum strictness, or CRITICAL to only hard-block the most severe categories.

CLI

sai guardrail status                      # Show guardrail state
sai guardrail toggle dry-run              # Toggle dry-run mode on/off
sai guardrail list [category]             # List rules (optionally filtered)
sai guardrail rule-add <name> <category>  # Add a custom regex rule
sai guardrail rule-toggle <name>          # Enable/disable a rule
sai guardrail paths block <pattern>       # Block a sensitive path
sai guardrail egress allow <domain>       # Whitelist an egress domain
sai guardrail egress data-sending <on|off># Toggle outbound body blocking
sai guardrail destructive list            # List blocked command patterns
sai guardrail destructive add <pattern>   # Add a custom destructive pattern
sai guardrail config                      # Print resolved config
sai guardrail reset                       # Reset to defaults

Note: moderation.rewriteThreshold is currently file-level only — edit the guardrail key in sapience-ai-suite.json. A dedicated CLI subcommand is not yet wired up.

:detective: PII Sanitizer

Detect and redact personally identifiable information before it leaves your system. Field-level DLP policies with recursive deep scanning across all tool call arguments.

Why It Exists

AI agents process everything in their context — including sensitive data users paste into conversations. Without a PII layer, an agent can inadvertently pass SSNs, API keys, or email addresses to external APIs, log them to files, or include them in shell commands. The PII Sanitizer intercepts tool calls and applies data loss prevention policies before execution.

Detection Patterns

DLP Actions

Key Features

• Recursive deep scanning — Traverses nested objects, arrays, and stringified JSON
• Shell argument parsing — Extracts and scans literals from shell commands
• Field-level policies — Different actions per PII type and severity
• Severity classification — LOW, MEDIUM, HIGH, CRITICAL
• Integrates with HITL — ESCALATE action routes to human approval

CLI

sai dlp info                                    # Show DLP status, toggles, rules, tool mappings
sai dlp toggle <enable|disable|dry-run>         # Toggle DLP settings
sai dlp rule-add <name> [options]               # Add or update a PII scanning rule
sai dlp rule-rm <name>                          # Remove a PII scanning rule by name
sai dlp policy-set <tool> <field> <action>      # Set scanning policy for a tool field

:bar_chart: Tool Call Limit

Budget enforcement for AI agent execution. Prevents runaway loops and resource exhaustion with per-session and per-request call limits.

Why It Exists

An agent stuck in a loop can call the same tool hundreds of times in a single session — burning through API quotas, racking up costs, and producing garbage output. Tool Call Limits enforce hard boundaries on how many times each tool can be called, at both the session and request level.

Enforcement Model

Tool Call Arrives
  │
  ├─ Check session counter ─── Under limit ──→ PASS
  │                        └── Soft limit ───→ WARN + PASS
  │                        └── Hard limit ───→ BLOCK
  │
  └─ Check request counter ─── Under limit ──→ PASS
                           └── Soft limit ───→ WARN + PASS
                           └── Hard limit ───→ BLOCK

Default Budgets

Key Features

• Two enforcement scopes — Session-level and request-level budgets
• Soft + hard limits — Warn before blocking
• Per-method granularity — Different limits for FileSystem.read vs Gmail.send
• Rolling windows — 24-hour configurable window for counter resets
• Session tracking — Maps virtual session IDs to real session keys

vs. OpenClaw tools.loopDetection

OpenClaw core ships a built-in tools.loopDetection guard that detects degenerate call patterns — same tool + same params repeated, known polling with no state change, ping-pong alternation — over a sliding window. It is pattern-based and disabled by default. Sapience Tool Call Limits is budget-based: it counts cumulative calls against a numeric quota. The two solve different failure modes and are designed to run together.

Differentiators beyond pattern-vs-budget:

• Dual enforcement scopes — session (lifetime) and request (single turn) budgets evaluated on every call
• Per-module × per-method granularity — Gmail.send has a different budget than FileSystem.read
• Soft + hard tiers — warn before blocking, so operators see approach-to-limit
• Rolling 24h window — counters reset automatically rather than requiring manual intervention
• Built-in observability — sai limits status and the dashboard page expose live counters; OpenClaw's detector only logs when it fires

Recommended setup: enable both. OpenClaw's detector catches degenerate shapes cheap; Sapience Limits catches budget overruns the pattern detector can't see (distributed loops, cost blowups, request-level runaway).

CLI

sai limits stats     # View current usage
sai limits show      # View limit policies
sai limits reset     # Reset counters

Dashboard

Real-time configuration and monitoring UI for all six middlewares.

The dashboard is a Preact application served by the OpenClaw gateway. It provides live configuration, status monitoring, and log streaming for every middleware in the suite.

Pages:

Tech stack: Preact + preact-router, @preact/signals for state, uPlot for charts, SSE for real-time streaming.

Update

Pull a newer published version of the plugin:

# 1. Recommended: disable every middleware first via the dashboard or CLI so
#    no in-flight requests are mid-pipeline when the plugin reloads. Toggling
#    them back on after the gateway restart re-runs the persist-defaults
#    handlers cleanly.
sai disable

# 2. Pull the latest published version. `openclaw plugins update` upgrades
#    the tracked plugin to the newest version from its registered source.
openclaw plugins update sapience-ai-suite

# 3. Restart the gateway so the new plugin code is loaded in-process.
openclaw gateway restart

After the restart, re-enable the middlewares you turned off in step 1 (dashboard toggles, or sai enable).

For local dev installs (openclaw plugins install --link .), pull the upstream changes you want, run npm run build, then restart: openclaw gateway restart. No re-link needed because --link follows the working tree.

Uninstall

Reverse the install in three steps. The order matters: drop the CLI shim first so nothing on $PATH can dangle, then unregister the plugin from the gateway, then restart so the runtime stops loading it.

# 1. Remove the `sai` CLI symlink (skip this line if you used `npm install -g` instead)
rm ~/.local/bin/sai

# 2. Unregister the plugin and remove its runtime files from ~/.openclaw/extensions/
openclaw plugins uninstall sapience-ai-suite

# 3. Reload the gateway so the plugin is no longer loaded in-process
openclaw gateway restart

Config and audit data are kept by default. The on-disk config store at ~/.openclaw/sapience-ai-suite/ (HITL policies, model routes, guardrail rules, audit trail JSONL, MFA secrets) survives the uninstall — reinstalling later picks it back up automatically. To wipe it:

# Only continue after user confirmation — this permanently removes audit logs, MFA secrets, and policies.
rm -rf ~/.openclaw/sapience-ai-suite

Programmatic Usage

The suite is published as a single npm package with one subpath per middleware. Importing HITL doesn't pull in router or guardrail code, and each subpath is tree-shakeable on its own. You construct middlewares directly, optionally hand them to a MiddlewareRegistry, and call lifecycle methods yourself.

Quick Start

npm install @sapience-ai-corporation/openclaw-middleware-suite

import { MiddlewareRegistry } from '@sapience-ai-corporation/openclaw-middleware-suite';
import { HitlMiddleware } from '@sapience-ai-corporation/openclaw-middleware-suite/hitl';
import { GuardrailMiddleware } from '@sapience-ai-corporation/openclaw-middleware-suite/guardrail';

const hitl = new HitlMiddleware();
const guard = new GuardrailMiddleware();

await hitl.initialize({ defaultAction: 'ASK' });
await guard.initialize({ dryRunMode: false });

const registry = new MiddlewareRegistry();
registry.register(hitl);
registry.register(guard);

// In your tool-call dispatcher:
const result = await registry.runBeforeToolCall(ctx);
if (result.block) throw new Error(result.reason);

That's the full embedding shape: import → construct → initialize() → register → call lifecycle methods (runBeforeToolCall, runBeforeAgentStart, etc.). Everything else below is detail on the contract, the configuration paths, and the per-middleware programmatic surface.

Root Surface

The root package only exposes cross-cutting framework concerns — pipeline runner, base contract, plugin lifecycle. Middleware classes live under their own subpaths.

import {
  // Plugin lifecycle
  registerPlugin,
  unregisterPlugin,
  isPluginRegistered,

  // Pipeline runner
  MiddlewareRegistry,

  // Base pipeline contract
  Middleware,
  MiddlewareContext,
  MiddlewareResult,

  // Plugin entry (what OpenClaw's loader imports)
  SapienceMiddlewarePlugin,
  SapienceMiddlewareManifest,
} from '@sapience-ai-corporation/openclaw-middleware-suite';

Base pipeline contract:

interface Middleware {
  readonly name: string;
  readonly version: string;
  initialize(config: Record<string, unknown>): Promise<void>;

  // Tool-call pipeline
  beforeToolCall?(context: MiddlewareContext): Promise<MiddlewareResult>;
  afterToolCall?(context: MiddlewareContext, result: unknown): Promise<void>;

  // OpenClaw lifecycle events (implement only the surfaces you need)
  beforeAgentStart?(context: AgentStartContext): Promise<AgentStartResult | void>;
  beforeModelResolve?(context: ModelResolveContext): Promise<ModelResolveResult | void>;
  beforeMessageWrite?(
    context: MessageWriteContext
  ): MessageWriteResult | undefined | Promise<MessageWriteResult | undefined>;

  // Lifecycle / reporting
  getStatus(): { enabled: boolean; stats?: Record<string, unknown> };
  shutdown?(): Promise<void>;
}

interface MiddlewareResult {
  block: boolean;
  reason?: string;
  modifiedParams?: Record<string, unknown>;
  /** First-class "force human approval" signal — guardrail WARN and PII
   *  ESCALATE both surface here so orchestrators read one consistent field. */
  escalate?: boolean;
  escalateReason?: string;
  metadata?: Record<string, unknown>;
}

Every lifecycle context (MiddlewareContext, AgentStartContext, ModelResolveContext, MessageWriteContext) extends a shared LifecycleContext base, so session-scoped fields (sessionKey, agentId, runId, metadata) live in the same place regardless of which event fired.

MiddlewareResult.reason (pipeline-level) is distinct from BeforeToolCallResult.blockReason (the OpenClaw before_tool_call hook return contract). See the note under HITL → Programmatic API for why the two coexist.

Middleware Subpaths

Subpath exports require Node ≥ 18 and TypeScript ≥ 4.7 with moduleResolution: "node16" | "nodenext" | "bundler". A typesVersions fallback is provided in package.json for consumers on legacy moduleResolution: "node".

Precedence at initialize(config)

Every middleware in the suite resolves config the same way:

DEFAULTS  <  inline config  <  sapience-ai-suite.json disk overlay

Three things to know about how this plays out for embedded consumers:

1. The disk overlay is optional but always wins when present. If ~/.openclaw/sapience-ai-suite/sapience-ai-suite.json exists (because the user ran sai init, or the dashboard wrote to it, or another instance saved earlier), its values shadow whatever you pass inline. Apps that want fully reproducible config should ensure the file isn't on disk (see Hermetic embedding below).
2. The plugin runtime always passes {} (or { pluginApi } for Context Editing). That's why plugin behavior is "defaults + disk, nothing else" — there's no inline layer to compete with the dashboard's writes.
3. Three configuration paths. Each middleware supports the same three ways to set its config:
   • Inline at initialize(config) — pass a partial of the middleware's config type. Applied on top of defaults, below the disk overlay.
   • In-process updateConfig(partial) — patches the running instance in memory; no disk I/O, no cross-process visibility. Best for embedded apps that don't want to touch sapience-ai-suite.json.
   • Disk-backed Store.update() / Store.save() + reload — persists to sapience-ai-suite.json, survives restarts, propagates to other plugin instances watching the same file.

Best Practices

The five callouts below apply to all six middlewares; they're the things that bite embedded consumers most often. The per-middleware sections after this only call out the bits that deviate from these defaults.

Hermetic Embedding

The disk overlay is what lets the dashboard and sai CLI manage the plugin transparently — but for an embedded app that ships its own config, it's a footgun: a sapience-ai-suite.json left on the deployment host will silently override your inline initialize() values. Two ways out:

Option 1 — No file on disk. If sapience-ai-suite.json doesn't exist on the deployment machine, there's no overlay → inline wins fully:

await mw.initialize({ dryRunMode: true });   // applies; nothing shadowing it

Option 2 — updateConfig after init. Patches the resolved config in memory, bypassing the disk overlay regardless of whether the file exists:

await mw.initialize({});                     // pulls disk if any
mw.updateConfig({ dryRunMode: true });       // overrides disk in memory

Pick option 2 if you don't know whether a sapience-ai-suite.json exists on the deployment machine — it works in both modes. The MR proxy port and a few other "constructed-at-start" fields are special-cased; see the per-middleware notes.

updateConfig for In-Process Patches

mw.updateConfig(partial) is the primary in-process knob. It patches this.config directly, no I/O, no file-watcher event. Use it whenever you want a runtime change that only the current process sees — typically because either (a) you're embedded and don't want to touch disk, or (b) you want to override a disk-sourced value just for this instance.

Shallow Merge

Both Store.update() and mw.updateConfig(partial) shallow-merge at the top level only. Passing a partial like { modules: { ... } } replaces the entire modules map — wiping siblings. For nested patches, read the current value and spread the sub-map yourself:

const current = mw.getConfig();
mw.updateConfig({ modules: { ...current.modules, FileSystem: { /* … */ } } });

The per-middleware sections below call out which top-level fields are nested objects worth watching. One exception: ce.updateConfig deep-merges its three known sub-trees (icc / pruning / compaction) to match its initialize convention.

Reload Semantics

reloadPolicy() (HITL, PII) and reloadConfig() (CE, MR, Guardrail, TCL) re-read the disk overlay and re-merge it over the current in-memory state. In-process updateConfig() patches survive the reload for fields the disk doesn't set — but disk-set fields shadow them (same precedence as initialize()). Call updateConfig() again post-reload to re-assert an override.

Dumb-Delegator Pattern

Once initialize() is called, every lifecycle method just runs — no internal enabled gate. Disable a middleware in your own pipeline by simply not calling its methods; the plugin runtime gates each middleware upstream via Store.isPluginEnabled(). getStatus().enabled is hardcoded to true once initialized.

MR is the one exception. Its enabled field tracks whether the embedded HTTP proxy is bound to a port, so mr.initialize({ enabled: false }) is a meaningful "build config but don't start proxy" mode (used for in-process pickTier-only embedding), and mr.getStatus().enabled reflects the actual proxy state.

Middlewares

Every middleware ships a self-contained programmatic surface under its own subpath. The patterns are deliberately uniform — construct → await initialize(config?) → call lifecycle methods directly or hand the instance to MiddlewareRegistry.register(). Block / escalate / pass uses one shape: MiddlewareResult.block, escalate, escalateReason, modifiedParams. See the base contract above.

Each middleware below also documents a Standalone primitives subsection — pure-function or single-class exports that let you skip the full middleware instance for tests, one-off classification, or building your own pipeline shape.

Quick links: HITL · Context Editing · Model Routing · Guardrail · PII Sanitizer · Tool Call Limit.

HITL

import {
  HitlMiddleware,
  Interceptor,
  createToolCallHook,
  classifyDestructiveAction,
  scoreIrreversibility,
  MemoryRiskForecaster,
  trustRateLimiter,
  DEFAULT_POLICY,
  // types
  Decision,
  SecurityPolicy,
  SecurityRule,
  SystemThresholds,
  BeforeToolCallEvent,
  ToolContext,
  BeforeToolCallResult,
} from '@sapience-ai-corporation/openclaw-middleware-suite/hitl';

Disk overlay at sapience-ai-suite.json[hitl.policy]. Plugin gating: _hitl.isPluginEnabled() (proxies through HitlMiddleware to its underlying Interceptor). Watch out for shallow-merge wholesale-replacement on the nested-object fields: modules, systemThresholds.

import { MiddlewareRegistry } from '@sapience-ai-corporation/openclaw-middleware-suite';
import { HitlMiddleware, PolicyStore } from '@sapience-ai-corporation/openclaw-middleware-suite/hitl';

const hitl = new HitlMiddleware();

// Path 1: Inline at initialize
await hitl.initialize({
  defaultAction: 'DENY',
  modules: {
    Shell:      { bash:  { action: 'ASK' } },
    FileSystem: { write: { action: 'ASK', allowPaths: ['/tmp/**'] } },
  },
});
new MiddlewareRegistry().register(hitl);

// Path 2: In-process patch
hitl.updateConfig({ defaultAction: 'ALLOW' });

// Path 3: Disk-backed
await PolicyStore.update({ defaultAction: 'DENY' });
hitl.reloadPolicy();

Two layers, two field names. The OpenClaw before_tool_call hook contract (what createToolCallHook returns — BeforeToolCallResult) uses blockReason, because that's what the framework reads. The pipeline-level MiddlewareResult (what HitlMiddleware.beforeToolCall returns inside the MiddlewareRegistry) uses reason. Translation between the two happens at the plugin boundary in src/plugin/index.ts.

Standalone Primitives

If you don't want a HitlMiddleware instance at all, the risk-assessment building blocks are exported as free functions and small classes — same return shapes the middleware uses internally, but composable in your own pipeline:

import { Interceptor, createToolCallHook } from '@sapience-ai-corporation/openclaw-middleware-suite/hitl';

const interceptor = new Interceptor({
  defaultAction: 'DENY',
  modules: {
    FileSystem: {
      read: { action: 'ALLOW' },
      write: { action: 'ASK', allowPaths: ['/tmp/**'], denyPaths: ['**/.ssh/**'] },
    },
    Shell: { bash: { action: 'ASK' } },
  },
});

const hook = createToolCallHook(interceptor);

const result = await hook(
  { toolName: 'write', params: { path: '/tmp/out.txt', content: 'data' } },
  { toolName: 'write', sessionKey: 'session-1' }
);
// allow path → undefined (void)
// block path → { block: true, blockReason: '...' }

Context Editing

import {
  ContextEditingMiddleware,
  DEFAULT_CONTEXT_EDITING_CONFIG,
  ContextEditingPolicyStore,
  // types
  ContextEditingConfig,
  ContextEditingPolicyData,
  CompactionTrigger,
  CompactionResult,
  SessionBuffer,
  EntityLock,
  ConflictResolution,
} from '@sapience-ai-corporation/openclaw-middleware-suite/context-editing';

Disk overlay at sapience-ai-suite.json[context_editing][configOverrides]. Plugin gating: ContextEditingPolicyStore.isPluginEnabled(). The config arg has one CE-specific purpose: pass OpenClaw's pluginApi here when running inside the plugin so ICC's LLM extraction can dispatch through it. CE deep-merges the three nested sub-trees icc / pruning / compaction (in initialize, updateConfig, and reloadConfig) so a partial like { icc: { messagesKeptBeforeCompaction: 5 } } keeps icc.customPrompt, icc.customSchema, etc. intact — top-level fields shallow-merge as elsewhere in the suite.

import { MiddlewareRegistry } from '@sapience-ai-corporation/openclaw-middleware-suite';
import {
  ContextEditingMiddleware,
  ContextEditingPolicyStore,
  DEFAULT_CONTEXT_EDITING_CONFIG,
} from '@sapience-ai-corporation/openclaw-middleware-suite/context-editing';

const ce = new ContextEditingMiddleware();

// Path 1: Inline at initialize
await ce.initialize({
  triggerMode: 'both',          // 'token' | 'message' | 'both'
  tokenThreshold: 80_000,       // early compaction when transcript > 80k tokens
  messageThreshold: 50,         //                              or > 50 messages
  icc: {
    ...DEFAULT_CONTEXT_EDITING_CONFIG.icc,
    messagesKeptBeforeCompaction: 3,
  },
  // pluginApi: <OpenClaw plugin API>  // omit when embedding standalone —
  //                                    // ICC LLM calls will be skipped.
});
new MiddlewareRegistry().register(ce);

// Path 2: In-process patch (deep-merges icc/pruning/compaction).
ce.updateConfig({ triggerMode: 'token' });
ce.updateConfig({ icc: { messagesKeptBeforeCompaction: 5 } }); // keeps customPrompt etc.

// Path 3: Disk-backed
await ContextEditingPolicyStore.update({ triggerMode: 'token' });
ce.reloadConfig();

Two shapes. initialize(config) takes the nested ContextEditingConfig (with icc, pruning, compaction subtrees) — this is what the middleware consumes at runtime. ContextEditingPolicyStore reads/writes the flat ContextEditingPolicyData shape that lives on disk (e.g. flat pruningMode/ttl instead of nested pruning.mode/pruning.ttl). The translation happens inside the middleware's reloadConfig() path, so you only see the flat shape when calling the store directly.

Standalone Primitives

Context Editing is the most middleware-driven of the six — its trigger evaluation, scheduling, and ICC dispatch only make sense as a long-lived pipeline participant. Two exports are still useful standalone:

If you need the ICC extraction itself outside the middleware (e.g. for offline transcript analysis), the dispatch path is private — open an issue describing the use case and we'll consider exposing it.

Model Routing

import {
  ModelRoutingMiddleware,
  scoreRequest,
  RequestDeduplicator,
  ResponseCache,
  CostTracker,
  PluginRegistry,
  PROFILE_CONFIGS,
  VALID_PROFILES,
  isValidProfile,
  // types
  RouterPlugin,
  Tier,
  RoutingDecision,
  RoutingStats,
  ModelRoutingConfig,
} from '@sapience-ai-corporation/openclaw-middleware-suite/model-routing';

Two consumption modes. Model Routing can be embedded in your app two ways depending on how you call your LLMs:

1. Embedded HTTP proxy (default) — initialize() builds config and starts a localhost proxy on port. Point your existing OpenAI/Anthropic SDK at http://127.0.0.1:{port}/v1/chat/completions and routing happens transparently inside the proxy.
2. In-process scoring — call mr.pickTier(input) directly to get the chosen tier + confidence + dimension breakdown without binding a port. Useful when you'd rather forward to your own provider client.

Disk overlay at sapience-ai-suite.json[model_routing]. Watch out for shallow-merge wholesale-replacement on the nested-object fields: tiersByProfile, tierOverridesByProfile, weightOverrides, boundaryOverrides, providerConfigs. API key fallback — targetApiKey and per-provider keys fall back to environment variables (OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY) when neither inline config nor disk overlay specifies them.

import { MiddlewareRegistry } from '@sapience-ai-corporation/openclaw-middleware-suite';
import {
  ModelRoutingMiddleware,
  ModelRoutingPolicyStore,
} from '@sapience-ai-corporation/openclaw-middleware-suite/model-routing';

const mr = new ModelRoutingMiddleware();

// Path 1a — Mode 1 (embedded proxy, default): inline at initialize.
await mr.initialize({
  enabled: true,                     // auto-start proxy (default)
  port: 9000,
  // Absolute-fallback profile when a request doesn't specify one (no
  // sai-router/* model id, no X-Router-Profile header). Defaults to 'eco';
  // override here for programmatic consumers that want a different fallback.
  defaultProfile: 'eco',             // 'eco' | 'premium' | 'agentic'
  targetApiKey: process.env.OPENAI_API_KEY,
  // tiersByProfile (per-profile tier maps), providers, classifier, dedup,
  // session, momentum, responseCache, costAlerts — all optional, all merged
  // over DEFAULT_MODEL_ROUTING_CONFIG.
});
// Route your LLM client at http://127.0.0.1:9000/v1/chat/completions

// Path 1b — Mode 2 (in-process scoring): pass `enabled: false` to skip the proxy.
await mr.initialize({ enabled: false });
const result = mr.pickTier({
  body: {
    messages: [{ role: 'user', content: 'Refactor this code…' }],
    tools: [{ type: 'function', function: { name: 'edit_file', /* … */ } }],
  },
});
// result = { tier: 'COMPLEX', score: 47.2, confidence: 0.83, dimensions: [...] }
// Pick a profile and read that profile's tier map. The proxy uses this same
// shape — there's no flat `config.tiers` anymore.
const tierConfig = mr.getConfig().tiersByProfile.eco[result.tier];
// tierConfig = { primary: 'gpt-5', fallbacks: ['claude-opus-4-7'] }

// Path 2: In-process patch. Shallow-merges into this.config; if the proxy is
// running, propagates via proxy.updateConfig() so live HTTP traffic uses
// the new values. Use `tiersByProfile` to swap one or more profiles' tier
// maps without touching the others.
mr.updateConfig({
  tiersByProfile: {
    ...mr.getConfig().tiersByProfile,
    premium: {
      SIMPLE: { primary: 'gpt-4o', fallbacks: [] },
      STANDARD: { primary: 'claude-sonnet-4-6', fallbacks: ['gpt-4o'] },
      COMPLEX: { primary: 'claude-opus-4-6', fallbacks: ['claude-sonnet-4-6'] },
      REASONING: { primary: 'o3', fallbacks: ['claude-opus-4-6'] },
    },
  },
});
new MiddlewareRegistry().register(mr);

// Path 3: Disk-backed. CLI (`sai router …`) and dashboard use the same pair.
// `tierOverridesByProfile` slots are independent — writing one doesn't
// disturb the others.
await ModelRoutingPolicyStore.update({
  tierOverridesByProfile: {
    premium: {
      COMPLEX: { primary: 'claude-opus-4-6', fallbacks: ['claude-sonnet-4-6'] },
    },
  },
});
mr.reloadConfig();

Runtime control of the proxy. Toggle without re-initializing:

await mr.start();      // bind the proxy port (idempotent — no-op if running)
await mr.stop();       // tear down the proxy + cleanup; instance stays usable
await mr.start();      // re-bind without rebuilding config
await mr.shutdown();   // permanent teardown (Middleware-interface contract)

start() requires initialize() to have been called first so this.config is populated. initialize({ enabled: false }) is the way to build config without auto-starting the proxy.

Constructed-at-start fields need a stop/start to take effect. port, responseCache, and costAlerts are bound when start() runs. Patching them via updateConfig() updates this.config, but the running proxy / cache instance / cost tracker keeps its constructor-time settings until you call mr.stop() then mr.start() (or mr.shutdown() then mr.initialize() again). Per-request fields like tiersByProfile, weightOverrides, and defaultProfile (the absolute fallback) flow through immediately because they're read on every routing decision.

Standalone Primitives

Model Routing's internals are unusually composable — every stage of the pipeline is exported as a free function or small class so you can build your own router without ever instantiating ModelRoutingMiddleware:

import { scoreRequest, DEFAULT_SCORING_CONFIG } from '@sapience-ai-corporation/openclaw-middleware-suite/model-routing';

const result = scoreRequest(
  { body: { messages: [{ role: 'user', content: 'Refactor this code…' }] } },
  DEFAULT_SCORING_CONFIG,
);
// { tier: 'COMPLEX', score: 47.2, confidence: 0.83, dimensions: [...] }

Guardrail

import {
  GuardrailMiddleware,
  GuardrailScanner,
  executeGuardrailScan,
  createWriteScannerHook,
  createPromptGuardHook,
  createModerationGuardHook,
  consumeModerationResult,
  scrubMetadata,
  getPatternCount,
  GuardrailConfigStore,
  GuardrailDecisionLog,
  // types
  GuardrailConfig,
  GuardrailDetection,
  DetectionRule,
  OutputScrubberConfig,
  ScrubResult,
  ModerationCacheEntry,
} from '@sapience-ai-corporation/openclaw-middleware-suite/guardrail';

One-object access to every guard. GuardrailMiddleware implements every Middleware-interface lifecycle method guardrail cares about. Each takes a single normalized context extending LifecycleContext (from @sapience-ai-corporation/openclaw-middleware-suite), so the calling convention stays uniform with beforeToolCall:

Block / escalate / pass — same shape across the suite. beforeToolCall returns the standard MiddlewareResult. Hard BLOCK detections set block: true; WARN detections (which want HITL approval rather than a hard deny) set the first-class escalate: true + escalateReason fields instead — the same channel PiiSanitizerMiddleware uses for its ESCALATE-severity DLP rules, so orchestrators read one consistent field across middlewares:

const result = await gr.beforeToolCall(ctx);
if (result.block) reject(result.reason);
if (result.escalate) requestApproval(result.escalateReason);  // route to your own HITL
if (result.modifiedParams) ctx.params = result.modifiedParams;

Disk overlay at sapience-ai-suite.json[guardrail]. Plugin gating: GuardrailConfigStore.isPluginEnabled(). Watch out for shallow-merge wholesale-replacement on the nested-object fields: rules, sensitivePaths, egressControl, destructiveCommands, outputScrubber, moderation.

import { MiddlewareRegistry } from '@sapience-ai-corporation/openclaw-middleware-suite';
import {
  GuardrailMiddleware,
  GuardrailConfigStore,
} from '@sapience-ai-corporation/openclaw-middleware-suite/guardrail';

const gr = new GuardrailMiddleware();

// Path 1: Inline at initialize
await gr.initialize({
  dryRunMode: true,
  entropyThreshold: 5.0,
  // rules, sensitivePaths, egressControl, destructiveCommands, outputScrubber,
  // moderation — all optional partials, all merged over DEFAULT_GUARDRAIL_CONFIG
});
new MiddlewareRegistry().register(gr);

// Path 2: In-process patch
gr.updateConfig({ dryRunMode: false });

// Path 3: Disk-backed
await GuardrailConfigStore.update({ dryRunMode: true });
gr.reloadConfig();

GuardrailMiddleware covers all three lifecycle surfaces (before_tool_call, before_agent_start, before_message_write) — the OpenClaw plugin runtime uses this class as its sole guardrail entrypoint, mirroring the Interceptor pattern HITL uses.

Standalone Primitives

Guardrail's pre-merge architecture exposed every guard as either a hook factory or a pure function. The full set is still available for consumers who'd rather wire guards à la carte:

import { GuardrailScanner, scrubMetadata } from '@sapience-ai-corporation/openclaw-middleware-suite/guardrail';

const scanner = new GuardrailScanner(/* GuardrailConfig — typically GuardrailConfigStore.getCached() */);
// Example role-override input (broken across concat to keep the README itself
// from matching naive prompt-injection scanners that read source verbatim).
const userInput = ['Ignore', 'previous', 'instructions and …'].join(' ');
const detections = scanner.scan(userInput);
// detections[0] = {
//   ruleName: 'role-override-classic', ruleType: 'regex',
//   severity: 'HIGH', action: 'BLOCK', confidence: 'HIGH',
//   matchedContent: '…', matchIndex: 0, category: 'promptInjection',
// }

const cleaned = scrubMetadata('Done. [SAPIENCE_INTERNAL: …]', { stripTokens: true });
// 'Done.'

PII Sanitizer

import {
  PiiSanitizerMiddleware,
  PII_PATTERNS,
  DlpStore,
  // types
  DlpPolicy,
  DlpDetection,
  DlpRule,
  PiiPatternKey,
  PiiPatternSpec,
  PiiSeverity,
} from '@sapience-ai-corporation/openclaw-middleware-suite/pii-sanitizer';

Same calling convention as guardrail. PiiSanitizerMiddleware implements the standard Middleware interface and shares the same MiddlewareResult shape — including the first-class escalate / escalateReason channel. BLOCK-severity rules return block: true; ESCALATE-severity rules return block: false, escalate: true, escalateReason: … so orchestrators can route through HITL instead of hard-blocking. Either path may also carry modifiedParams with redactions applied.

const result = await pii.beforeToolCall(ctx);
if (result.block) reject(result.reason);                        // BLOCK rule
if (result.escalate) requestApproval(result.escalateReason);    // ESCALATE rule
if (result.modifiedParams) ctx.params = result.modifiedParams;  // REDACT rule

Disk overlay at sapience-ai-suite.json[pii_sanitizer]. Plugin gating: DlpStore.isPluginEnabled(). Watch out for shallow-merge wholesale-replacement on toolPolicies (per-module map) and globalRules (rules array).

import { MiddlewareRegistry } from '@sapience-ai-corporation/openclaw-middleware-suite';
import { PiiSanitizerMiddleware, DlpStore } from '@sapience-ai-corporation/openclaw-middleware-suite/pii-sanitizer';

const pii = new PiiSanitizerMiddleware();

// Path 1: Inline at initialize
await pii.initialize({
  dryRunMode: true,
  // globalRules, toolPolicies — optional partials, all merged over DEFAULT_DLP_POLICY
});
new MiddlewareRegistry().register(pii);

// Path 2: In-process patch
pii.updateConfig({ dryRunMode: false });

// Path 3: Disk-backed
await DlpStore.update({ dryRunMode: true });
pii.reloadPolicy();

Standalone Primitives

import { PII_PATTERNS } from '@sapience-ai-corporation/openclaw-middleware-suite/pii-sanitizer';

const text = 'Send the report to user@example.com';
for (const [key, spec] of Object.entries(PII_PATTERNS)) {
  if (spec.type !== 'regex') continue;
  if (new RegExp(spec.pattern).test(text)) console.log(`Found ${key} (${spec.severity})`);
}

Tool Call Limit

import {
  ToolCallLimitMiddleware,
  LimitPolicyStore,
  // types
  LimitPolicy,
  LimitRule,
  EnforcementStatus,
} from '@sapience-ai-corporation/openclaw-middleware-suite/tool-call-limit';

Disk overlay at sapience-ai-suite.json[tool_call_limit]. Plugin gating: LimitPolicyStore.isPluginEnabled(). Watch out for shallow-merge wholesale-replacement on the top-level modules map.

import { MiddlewareRegistry } from '@sapience-ai-corporation/openclaw-middleware-suite';
import { ToolCallLimitMiddleware, LimitPolicyStore } from '@sapience-ai-corporation/openclaw-middleware-suite/tool-call-limit';

const limits = new ToolCallLimitMiddleware();

// Path 1: Inline at initialize
await limits.initialize({
  globalSessionCallLimit: 100,
  globalRequestCallLimit: 20,
  // modules: per-tool rules — optional partial, merged over DEFAULT_LIMIT_POLICY
});
new MiddlewareRegistry().register(limits);

// Path 2: In-process patch
limits.updateConfig({ globalSessionCallLimit: 50 });

// Path 3: Disk-backed
await LimitPolicyStore.update({ globalSessionCallLimit: 200 });
limits.reloadConfig();

sai limits reset always reflects disk. The reset signal (set by the CLI via the resetAt field) is checked against LimitPolicyStore.getCached() directly, not the per-instance policy — so a reset issued by an out-of-process CLI is always picked up on the next tool call regardless of in-memory updateConfig() state.

Standalone Primitives

The counter trackers (SessionTracker / RequestTracker) are intentionally private — they're tightly coupled to the before_tool_call lifecycle and reset semantics. If you need session-budget enforcement outside the middleware, open an issue describing the use case.

Hook Pipeline

Each agent turn fires four OpenClaw hooks the suite cares about, in this order:

before_model_resolve   ◀── earliest, fires before SM_A opens the JSONL
  │
  └─ 1. Context Editing      → Open SM_B on session JSONL, walk getEntries()
  │                             to count user messages and sum assistant
  │                             usage, evaluate triggers, and run ICC +
  │                             appendCompaction inline if threshold met.
  │                             Same turn's LLM call sees compacted history.
  │
  ▼
before_agent_start
  │
  └─ 2. Guardrail            → Prompt-guard + moderation: scan the inbound
  │                             prompt and prepend a moderation prefix to
  │                             the system context if needed.
  │
  ▼
before_tool_call       ◀── per tool call inside the turn
  │
  ├─ 3. Guardrail scan       → Block injection, exfiltration, destructive
  │                             commands.
  ├─ 4. PII DLP scan         → Block or redact PII in tool params.
  ├─ 5. Tool call limit      → Enforce session / request budgets.
  └─ 6. HITL evaluation      → Apply policy; ASK → approval queue.
  │
  ▼
before_message_write   ◀── single Guardrail handler, two stages
  │
  ├─ 7. Guardrail write scan → Block injection, role impersonation,
  │                             canary leakback (all roles).
  └─ 8. Output scrubber      → Strip middleware tokens (assistant only,
                                gated on `outputScrubber.enabled`).

Environment Variables

Data Storage

All runtime data stored in ~/.openclaw/sapience-ai-suite/. Config lives in a single unified JSON store; each middleware gets its own directory for logs and runtime state:

~/.openclaw/sapience-ai-suite/
├── sapience-ai-suite.json              # Unified config store (all middleware config)
├── sapience-ai-suite.log              # Main application log
├── hitl/
│   ├── decisions.jsonl                # Approval decision audit trail
│   ├── stats.json                     # Approval statistics
│   ├── browser-sessions.json          # Encrypted browser automation state
│   └── totp.json                      # TOTP authenticator secret
├── context-editing/
│   ├── audit.jsonl                    # Compaction event audit trail
│   ├── stats.json                     # Compaction statistics
│   └── diagnostic.log                 # Verbose diagnostic output
├── model-routing/
│   ├── routing-audit.jsonl            # Routing decision audit trail
│   ├── proxy-audit.log               # Step-by-step request traces
│   ├── cost-tracker.json             # Real-time cost tracking
│   └── litellm-model-catalog.json    # Cached model pricing catalog
├── guardrail/
│   └── audit.jsonl                    # Guardrail detection audit trail
├── pii-sanitizer/
│   └── audit.jsonl                    # PII detection audit trail
└── tool-call-limit/
    ├── sessions.json                  # Session call trackers
    ├── requests.json                  # Request call trackers
    └── last_request.txt               # Virtual request ID tracking

Security Guarantees

• Zero Trust — Every action evaluated against policy, no implicit trust
• Synchronous Blocking — Agent waits for approval before executing
• No Bypass — Plugin hooks intercept all tool calls at the framework level
• Immutable Audit — JSON Lines append-only format for compliance
• Fail Secure — Unknown actions default to ASK
• ArgsHash Verification — Approved params are hash-checked on retry to prevent substitution attacks
• Defense in Depth — Multiple independent detection layers (guardrail, PII, HITL)

Development

git clone https://github.com/Sapience-AI/openclaw-middleware-suite.git
cd openclaw-middleware-suite
npm install
npm run build            # Compile TypeScript + Vite dashboard
npm test                 # Run Tests
npm run lint             # ESLint
npm run format           # Prettier

Contributing

PRs welcome! See CONTRIBUTING.md for setup, test commands, branch naming, and code style.

Get Involved

We'd love to hear how you're using the Sapience AI Middleware Suite.

License

Apache License, Version 2.0 — see LICENSE.

The Human-in-the-Loop middleware in src/middlewares/hitl/ is derived from the Reins project by Pegasi, used under the Apache License 2.0. The Model Routing middleware in src/middlewares/model-routing/ incorporates code from the Manifest project by MNFST, Inc. and the ClawRouter project by BlockRun, both used under the MIT License. The Guardrail middleware in src/middlewares/guardrail/ incorporates code, scanner logic, and detection patterns from the OpenClaw Shield project by Knostic and the OpenGuardrails project, both used under the Apache License 2.0 (OpenGuardrails carries additional upstream conditions on multi-tenant SaaS use and frontend brand attribution — this product uses it as a backend / SDK-style component only and does not embed its frontend or operate a multi-tenant SaaS based on its source). See NOTICE for the full attribution and the list of derived files. Per-file headers identify origin and modifications in accordance with Apache 2.0 §4(b).

Built by Sapience AI for a safer AI future.

_{If your agent can do it, the middleware sees it first.}