Skip to content
Prefactor Docs

@prefactor/openclaw-prefactor-plugin

Prefactor TypeScript SDK

Prefactor TypeScript SDK / @prefactor/openclaw-prefactor-plugin

@prefactor/openclaw-prefactor-plugin

Section titled “@prefactor/openclaw-prefactor-plugin”

OpenClaw plugin for Prefactor observability. Provides automatic tracing of agent lifecycle events including sessions, user interactions, agent runs, and tool calls.

@prefactor/openclaw-prefactor-plugin overview

Section titled “@prefactor/openclaw-prefactor-plugin overview”

This plugin hooks into OpenClaw’s lifecycle events to create a hierarchical span structure for distributed tracing. The span hierarchy follows:

session (24hr lifetime, root span)
  └─ user_interaction (5min idle timeout)
      ├─ user_message (instant, auto-closed)
      ├─ agent_run (child of interaction)
      │   ├─ tool_call (concurrent, children of agent_run)
      │   └─ tool_call
      └─ assistant_response (instant, auto-closed)

Hook handlers

Section titled “Hook handlers”

The plugin registers 14 hooks that automatically create and manage spans:

  • Gateway: gateway_start, gateway_stop
  • Session: session_start, session_end
  • Agent: before_agent_start, agent_end
  • Compaction: before_compaction, after_compaction
  • Tool: before_tool_call, after_tool_call, tool_result_persist
  • Message: message_received, message_sending, message_sent

Span types

Section titled “Span types”
  • openclaw:session - Root span for the OpenClaw session (24hr lifetime)
  • openclaw:user_interaction - User interaction context (5min idle timeout)
  • openclaw:user_message - Inbound user message event
  • openclaw:agent_run - Agent execution run
  • openclaw:tool_call - Tool execution (supports concurrent calls)
  • openclaw:assistant_response - Assistant response event

Exports

Section titled “Exports”
  • Agent - HTTP client for Prefactor API (span CRUD, instance lifecycle)
  • SessionStateManager - Manages span hierarchy and timeouts per session
  • Logger - Structured logger for plugin diagnostics
  • register - Plugin entry point (used by OpenClaw, not imported directly)

Functions

Section titled “Functions”

Interfaces

Section titled “Interfaces”

Type Aliases

Section titled “Type Aliases”

Variables

Section titled “Variables”