Core concepts

Hooks & lifecycle

React to bridge and session events with lifecycle hooks. All hooks are optional and registered outside your core message handler.

All hooks

hooks.js

1bridge.onSessionStart((sessionId) => {
2  memory.reset();
3  db.createSession(sessionId);
4});
5 
6bridge.onSessionEnd((sessionId, history) => {
7  db.saveTranscript({ sessionId, history });
8  analytics.track("audit.complete", { sessionId, turns: history.length });
9});
10 
11bridge.onConnect(() => {
12  console.log("Bridge connected to PlayClaw");
13  healthCheck.setReady(true);
14});
15 
16bridge.onDisconnect(() => {
17  console.log("Bridge disconnected. Auto-reconnect pending.");
18  healthCheck.setReady(false);
19});
20 
21bridge.onError((error, sessionId) => {
22  monitoring.capture(error, { context: "bridge", sessionId });
23});

Hook	Signature	When it fires
onSessionStart	(sessionId: string) => void	A new audit session opens.
onSessionEnd	(sessionId: string, history: Message[]) => void	An audit session completes (all turns done).
onConnect	() => void	The Supabase channel becomes active.
onDisconnect	() => void	The channel drops or is closed.
onError	(error: Error, sessionId?: string) => void	Any error during message handling or connection.

Note

Hooks are registered before calling bridge.connect(). You can register multiple handlers per hook — they all fire in registration order.

Typical use cases

onSessionStart — reset in-memory conversation history, open a DB record, initialize per-session telemetry.

onSessionEnd — persist the full transcript, trigger post-audit analytics, release session-scoped resources.

onError — capture exceptions to Sentry, DataDog, or your own error tracker. The bridge continues after errors — it never crashes the process.

onConnect / onDisconnect — update health check endpoints, emit readiness signals to your orchestrator.

PreviousSession context

Next Middleware