@sisu-ai/mw-error-boundary

v10.0.0

Published

4 days ago

Prevent pipeline crashes by catching middleware errors and returning controlled fallbacks.

0High
0Medium
0Low

lejahmie

sisu ai ai-agent agentic middleware error-boundary

@sisu-ai/mw-error-boundary

Prevent pipeline crashes by catching middleware errors and returning controlled fallbacks.

Setup

npm i @sisu-ai/mw-error-boundary

Exports

errorBoundary(onError: (err, ctx, next) => Promise<void>)
- Call early in your stack to ensure all downstream errors are caught.
- Inside onError, you typically:
  - log the error (ctx.log.error(err)),
  - push a friendly assistant message to ctx.messages,
  - optionally write to ctx.stream if you’re mid‑stream.

What It Does

Wraps the rest of your pipeline in a try/catch.
Invokes your handler with the error and context, so you can log and produce a user‑friendly fallback.
Prevents crashes from bubbling to the caller while keeping control in your app.

How It Works

errorBoundary(onError) returns middleware that does:

try {
  await next();
} catch (err) {
  await onError(err, ctx, async () => {}); // next is a no-op in error state
}

Your onError receives (err, ctx, next) where next is a no‑op to signal the boundary is terminal for that request.

Usage

import { Agent } from '@sisu-ai/core';
import { errorBoundary } from '@sisu-ai/mw-error-boundary';

const app = new Agent()
  .use(errorBoundary(async (err, ctx) => {
    ctx.log.error(err);
    // If streaming UI, consider writing to the stream instead/as well.
    ctx.messages.push({ role: 'assistant', content: 'Sorry, something went wrong.' });
  }))
  // ... other middleware

Placement & Ordering

Put errorBoundary at or near the top to catch as much as possible.
Combine with tracing/usage middleware as needed; if placed before them, those middlewares may not observe the error.
If you use a server adapter, ensure it wraps request handling so per‑request errors are isolated.

When To Use

Any production app to avoid unhandled rejections crashing the process.
CLIs and demos where you want graceful failure and a helpful message.
Around tool‑calling loops where third‑party tools may throw.

When Not To Use

If you want errors to propagate to an outer boundary (e.g., framework handler) and be handled there.
Highly controlled test scenarios where you prefer tests to fail fast instead of being swallowed.

Notes & Gotchas

The boundary swallows the error after onError runs; rethrow inside onError if you want upstream handling.
Be careful not to leak secrets when logging errors — consider the redacting logger createRedactingLogger from @sisu-ai/core.
If you are streaming tokens, write an error notice to ctx.stream and call ctx.stream.end() to close the client stream cleanly.
Keep onError fast and robust; avoid throwing inside it.

Community & Support

Discover what you can do through examples or documentation. Check it out at https://github.com/finger-gun/sisu. Example projects live under examples/ in the repo.