@gguf/claw
Version:
Multi-channel AI gateway with extensible messaging integrations
156 lines (155 loc) • 5.63 kB
TypeScript
/**
* Hook system for OpenClaw agent events
*
* Provides an extensible event-driven hook system for agent events
* like command processing, session lifecycle, etc.
*/
import type { WorkspaceBootstrapFile } from "../agents/workspace.js";
import type { CliDeps } from "../cli/deps.js";
import type { OpenClawConfig } from "../config/config.js";
export type InternalHookEventType = "command" | "session" | "agent" | "gateway" | "message";
export type AgentBootstrapHookContext = {
workspaceDir: string;
bootstrapFiles: WorkspaceBootstrapFile[];
cfg?: OpenClawConfig;
sessionKey?: string;
sessionId?: string;
agentId?: string;
};
export type AgentBootstrapHookEvent = InternalHookEvent & {
type: "agent";
action: "bootstrap";
context: AgentBootstrapHookContext;
};
export type GatewayStartupHookContext = {
cfg?: OpenClawConfig;
deps?: CliDeps;
workspaceDir?: string;
};
export type GatewayStartupHookEvent = InternalHookEvent & {
type: "gateway";
action: "startup";
context: GatewayStartupHookContext;
};
export type MessageReceivedHookContext = {
/** Sender identifier (e.g., phone number, user ID) */
from: string;
/** Message content */
content: string;
/** Unix timestamp when the message was received */
timestamp?: number;
/** Channel identifier (e.g., "telegram", "whatsapp") */
channelId: string;
/** Provider account ID for multi-account setups */
accountId?: string;
/** Conversation/chat ID */
conversationId?: string;
/** Message ID from the provider */
messageId?: string;
/** Additional provider-specific metadata */
metadata?: Record<string, unknown>;
};
export type MessageReceivedHookEvent = InternalHookEvent & {
type: "message";
action: "received";
context: MessageReceivedHookContext;
};
export type MessageSentHookContext = {
/** Recipient identifier */
to: string;
/** Message content */
content: string;
/** Whether the message was sent successfully */
success: boolean;
/** Error message if sending failed */
error?: string;
/** Channel identifier (e.g., "telegram", "whatsapp") */
channelId: string;
/** Provider account ID for multi-account setups */
accountId?: string;
/** Conversation/chat ID */
conversationId?: string;
/** Message ID returned by the provider */
messageId?: string;
};
export type MessageSentHookEvent = InternalHookEvent & {
type: "message";
action: "sent";
context: MessageSentHookContext;
};
export interface InternalHookEvent {
/** The type of event (command, session, agent, gateway, etc.) */
type: InternalHookEventType;
/** The specific action within the type (e.g., 'new', 'reset', 'stop') */
action: string;
/** The session key this event relates to */
sessionKey: string;
/** Additional context specific to the event */
context: Record<string, unknown>;
/** Timestamp when the event occurred */
timestamp: Date;
/** Messages to send back to the user (hooks can push to this array) */
messages: string[];
}
export type InternalHookHandler = (event: InternalHookEvent) => Promise<void> | void;
/**
* Register a hook handler for a specific event type or event:action combination
*
* @param eventKey - Event type (e.g., 'command') or specific action (e.g., 'command:new')
* @param handler - Function to call when the event is triggered
*
* @example
* ```ts
* // Listen to all command events
* registerInternalHook('command', async (event) => {
* console.log('Command:', event.action);
* });
*
* // Listen only to /new commands
* registerInternalHook('command:new', async (event) => {
* await saveSessionToMemory(event);
* });
* ```
*/
export declare function registerInternalHook(eventKey: string, handler: InternalHookHandler): void;
/**
* Unregister a specific hook handler
*
* @param eventKey - Event key the handler was registered for
* @param handler - The handler function to remove
*/
export declare function unregisterInternalHook(eventKey: string, handler: InternalHookHandler): void;
/**
* Clear all registered hooks (useful for testing)
*/
export declare function clearInternalHooks(): void;
/**
* Get all registered event keys (useful for debugging)
*/
export declare function getRegisteredEventKeys(): string[];
/**
* Trigger a hook event
*
* Calls all handlers registered for:
* 1. The general event type (e.g., 'command')
* 2. The specific event:action combination (e.g., 'command:new')
*
* Handlers are called in registration order. Errors are caught and logged
* but don't prevent other handlers from running.
*
* @param event - The event to trigger
*/
export declare function triggerInternalHook(event: InternalHookEvent): Promise<void>;
/**
* Create a hook event with common fields filled in
*
* @param type - The event type
* @param action - The action within that type
* @param sessionKey - The session key
* @param context - Additional context
*/
export declare function createInternalHookEvent(type: InternalHookEventType, action: string, sessionKey: string, context?: Record<string, unknown>): InternalHookEvent;
export declare function isAgentBootstrapEvent(event: InternalHookEvent): event is AgentBootstrapHookEvent;
export declare function isGatewayStartupEvent(event: InternalHookEvent): event is GatewayStartupHookEvent;
export declare function isMessageReceivedEvent(event: InternalHookEvent): event is MessageReceivedHookEvent;
export declare function isMessageSentEvent(event: InternalHookEvent): event is MessageSentHookEvent;