@troykelly/openclaw-projects 0.0.1

package/dist/context.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Context extraction utilities for OpenClaw plugin.
+ * Extracts user, agent, and session context from the OpenClaw runtime.
+ */
+/** User identity information */
+export interface UserContext {
+    /** Unique user identifier */
+    userId: string;
+    /** User display name (if available) */
+    displayName?: string;
+    /** User email (if available) */
+    email?: string;
+}
+/** Agent information */
+export interface AgentContext {
+    /** Agent identifier */
+    agentId: string;
+    /** Agent name */
+    name: string;
+    /** Agent version */
+    version?: string;
+}
+/** Session information */
+export interface SessionContext {
+    /** Session identifier */
+    sessionId: string;
+    /** Session start timestamp */
+    startedAt: Date;
+    /** Conversation thread ID (if part of a thread) */
+    threadId?: string;
+}
+/** Combined context from all sources */
+export interface PluginContext {
+    user?: UserContext;
+    agent: AgentContext;
+    session: SessionContext;
+}
+/**
+ * Extracts user context from OpenClaw runtime context.
+ * Returns undefined if user information is not available.
+ */
+export declare function extractUserContext(runtimeContext: unknown): UserContext | undefined;
+/**
+ * Extracts agent context from OpenClaw runtime context.
+ */
+export declare function extractAgentContext(runtimeContext: unknown): AgentContext;
+/**
+ * Extracts session context from OpenClaw runtime context.
+ */
+export declare function extractSessionContext(runtimeContext: unknown): SessionContext;
+/**
+ * Extracts complete plugin context from OpenClaw runtime.
+ */
+export declare function extractContext(runtimeContext: unknown): PluginContext;
+/**
+ * Validates a session key format.
+ * - Max length: 500 characters
+ * - Allowed characters: alphanumeric, colon, hyphen, underscore
+ */
+export declare function validateSessionKey(sessionKey: string | null | undefined): boolean;
+/**
+ * Parse agentId from session key.
+ * Session key format: agent:<agentId>:<channel>:...
+ * Returns "unknown" for invalid or missing keys.
+ */
+export declare function parseAgentIdFromSessionKey(sessionKey: string | null | undefined): string;
+/** Context for user scoping */
+export interface ScopingContext {
+    /** Agent ID for agent-level scoping */
+    agentId: string;
+    /** Full session key for session-level isolation */
+    sessionKey?: string;
+    /** External sender ID */
+    senderId?: string;
+    /** Communication channel */
+    channel?: string;
+    /** Canonical identity key for cross-agent queries */
+    identityKey?: string;
+}
+/**
+ * Get the user scope key based on configured scoping mode.
+ * @param context - User scoping context
+ * @param scopeMode - "agent" | "identity" | "session"
+ * @returns Scope key to pass to backend API
+ */
+export declare function getUserScopeKey(context: ScopingContext, scopeMode: 'agent' | 'identity' | 'session'): string;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,gCAAgC;AAChC,MAAM,WAAW,WAAW;IAC1B,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAA;IACd,uCAAuC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,wBAAwB;AACxB,MAAM,WAAW,YAAY;IAC3B,uBAAuB;IACvB,OAAO,EAAE,MAAM,CAAA;IACf,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,oBAAoB;IACpB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,0BAA0B;AAC1B,MAAM,WAAW,cAAc;IAC7B,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAA;IACjB,8BAA8B;IAC9B,SAAS,EAAE,IAAI,CAAA;IACf,mDAAmD;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,wCAAwC;AACxC,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,WAAW,CAAA;IAClB,KAAK,EAAE,YAAY,CAAA;IACnB,OAAO,EAAE,cAAc,CAAA;CACxB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,cAAc,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAiBnF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,cAAc,EAAE,OAAO,GAAG,YAAY,CAsBzE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,cAAc,EAAE,OAAO,GAAG,cAAc,CA2B7E;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,cAAc,EAAE,OAAO,GAAG,aAAa,CAMrE;AAQD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAQjF;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAsBxF;AAED,+BAA+B;AAC/B,MAAM,WAAW,cAAc;IAC7B,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAA;IACf,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,yBAAyB;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,4BAA4B;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,GAC1C,MAAM,CAgBR"}

package/dist/context.js

@@ -0,0 +1,144 @@
+/**
+ * Context extraction utilities for OpenClaw plugin.
+ * Extracts user, agent, and session context from the OpenClaw runtime.
+ */
+/**
+ * Extracts user context from OpenClaw runtime context.
+ * Returns undefined if user information is not available.
+ */
+export function extractUserContext(runtimeContext) {
+    if (!runtimeContext || typeof runtimeContext !== 'object') {
+        return undefined;
+    }
+    const ctx = runtimeContext;
+    const user = ctx.user;
+    if (!user || typeof user.id !== 'string') {
+        return undefined;
+    }
+    return {
+        userId: user.id,
+        displayName: typeof user.displayName === 'string' ? user.displayName : undefined,
+        email: typeof user.email === 'string' ? user.email : undefined,
+    };
+}
+/**
+ * Extracts agent context from OpenClaw runtime context.
+ */
+export function extractAgentContext(runtimeContext) {
+    const defaultAgent = {
+        agentId: 'unknown',
+        name: 'Unknown Agent',
+    };
+    if (!runtimeContext || typeof runtimeContext !== 'object') {
+        return defaultAgent;
+    }
+    const ctx = runtimeContext;
+    const agent = ctx.agent;
+    if (!agent) {
+        return defaultAgent;
+    }
+    return {
+        agentId: typeof agent.id === 'string' ? agent.id : 'unknown',
+        name: typeof agent.name === 'string' ? agent.name : 'Unknown Agent',
+        version: typeof agent.version === 'string' ? agent.version : undefined,
+    };
+}
+/**
+ * Extracts session context from OpenClaw runtime context.
+ */
+export function extractSessionContext(runtimeContext) {
+    const defaultSession = {
+        sessionId: crypto.randomUUID(),
+        startedAt: new Date(),
+    };
+    if (!runtimeContext || typeof runtimeContext !== 'object') {
+        return defaultSession;
+    }
+    const ctx = runtimeContext;
+    const session = ctx.session;
+    if (!session) {
+        return defaultSession;
+    }
+    return {
+        sessionId: typeof session.id === 'string' ? session.id : crypto.randomUUID(),
+        startedAt: session.startedAt instanceof Date
+            ? session.startedAt
+            : typeof session.startedAt === 'string'
+                ? new Date(session.startedAt)
+                : new Date(),
+        threadId: typeof session.threadId === 'string' ? session.threadId : undefined,
+    };
+}
+/**
+ * Extracts complete plugin context from OpenClaw runtime.
+ */
+export function extractContext(runtimeContext) {
+    return {
+        user: extractUserContext(runtimeContext),
+        agent: extractAgentContext(runtimeContext),
+        session: extractSessionContext(runtimeContext),
+    };
+}
+/** Allowed characters in session keys: alphanumeric, colon, hyphen, underscore */
+const SESSION_KEY_REGEX = /^[a-zA-Z0-9:_-]+$/;
+/** Maximum length for session keys */
+const MAX_SESSION_KEY_LENGTH = 500;
+/**
+ * Validates a session key format.
+ * - Max length: 500 characters
+ * - Allowed characters: alphanumeric, colon, hyphen, underscore
+ */
+export function validateSessionKey(sessionKey) {
+    if (!sessionKey || sessionKey.length === 0) {
+        return false;
+    }
+    if (sessionKey.length > MAX_SESSION_KEY_LENGTH) {
+        return false;
+    }
+    return SESSION_KEY_REGEX.test(sessionKey);
+}
+/**
+ * Parse agentId from session key.
+ * Session key format: agent:<agentId>:<channel>:...
+ * Returns "unknown" for invalid or missing keys.
+ */
+export function parseAgentIdFromSessionKey(sessionKey) {
+    if (!sessionKey || sessionKey.length === 0) {
+        return 'unknown';
+    }
+    // Validate session key format first
+    if (!validateSessionKey(sessionKey)) {
+        return 'unknown';
+    }
+    // Parse format: agent:<agentId>:<channel>:...
+    const parts = sessionKey.split(':');
+    if (parts.length < 3 || parts[0] !== 'agent') {
+        return 'unknown';
+    }
+    const agentId = parts[1];
+    if (!agentId || agentId.length === 0) {
+        return 'unknown';
+    }
+    return agentId;
+}
+/**
+ * Get the user scope key based on configured scoping mode.
+ * @param context - User scoping context
+ * @param scopeMode - "agent" | "identity" | "session"
+ * @returns Scope key to pass to backend API
+ */
+export function getUserScopeKey(context, scopeMode) {
+    switch (scopeMode) {
+        case 'agent':
+            return context.agentId || 'unknown';
+        case 'identity':
+            // Prefer identity key if available, fall back to agent
+            return context.identityKey || context.agentId || 'unknown';
+        case 'session':
+            // Prefer full session key if available, fall back to agent
+            return context.sessionKey || context.agentId || 'unknown';
+        default:
+            return context.agentId || 'unknown';
+    }
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}

package/dist/gateway/rpc-methods.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Gateway RPC methods for real-time updates.
+ * Part of Epic #310, Issue #324.
+ *
+ * Provides bidirectional communication between OpenClaw agents and
+ * the openclaw-projects backend via the Gateway protocol.
+ *
+ * @see https://docs.openclaw.ai/gateway/protocol.md
+ */
+import type { ApiClient } from '../api-client.js';
+import type { Logger } from '../logger.js';
+/** Valid notification event types */
+export type NotificationEvent = 'message.new' | 'message.delivered' | 'task.due' | 'task.overdue' | 'memory.created';
+/** Subscribe method parameters */
+export interface SubscribeParams {
+    /** Event types to subscribe to */
+    events: string[];
+}
+/** Subscribe method result */
+export interface SubscribeResult {
+    /** Events successfully subscribed to */
+    subscribed: NotificationEvent[];
+}
+/** Unsubscribe method parameters */
+export interface UnsubscribeParams {
+}
+/** Unsubscribe method result */
+export interface UnsubscribeResult {
+    /** Whether unsubscribe was successful */
+    unsubscribed: boolean;
+}
+/** Get notifications parameters */
+export interface GetNotificationsParams {
+    /** ISO timestamp to get notifications since */
+    since?: string;
+    /** Maximum notifications to return (default: 20) */
+    limit?: number;
+}
+/** Notification object */
+export interface Notification {
+    /** Unique notification ID */
+    id: string;
+    /** Event type */
+    event: NotificationEvent;
+    /** Event-specific payload */
+    payload: Record<string, unknown>;
+    /** When the notification was created */
+    createdAt: string;
+}
+/** Get notifications result */
+export interface GetNotificationsResult {
+    /** Notifications matching the query */
+    notifications: Notification[];
+    /** Whether there are more notifications available */
+    hasMore: boolean;
+}
+/** Options for creating gateway methods */
+export interface GatewayMethodsOptions {
+    /** Logger instance */
+    logger: Logger;
+    /** API client for backend calls */
+    apiClient: ApiClient;
+    /** User ID for scoping */
+    userId: string;
+}
+/** Gateway methods interface */
+export interface GatewayMethods {
+    /** Subscribe to event notifications */
+    subscribe: (params: SubscribeParams) => Promise<SubscribeResult>;
+    /** Unsubscribe from all event notifications */
+    unsubscribe: (params: UnsubscribeParams) => Promise<UnsubscribeResult>;
+    /** Get pending notifications */
+    getNotifications: (params: GetNotificationsParams) => Promise<GetNotificationsResult>;
+    /** Get currently subscribed events (for internal use) */
+    getSubscribedEvents: () => NotificationEvent[];
+}
+/**
+ * Create Gateway RPC method handlers.
+ *
+ * @param options - Configuration options
+ * @returns Gateway method handlers
+ */
+export declare function createGatewayMethods(options: GatewayMethodsOptions): GatewayMethods;
+/**
+ * Register Gateway RPC methods with the OpenClaw API.
+ *
+ * @param api - OpenClaw Plugin API
+ * @param methods - Gateway method handlers
+ */
+export declare function registerGatewayRpcMethods(api: {
+    registerGatewayMethod: <T, R>(name: string, handler: (params: T) => Promise<R>) => void;
+}, methods: GatewayMethods): void;
+//# sourceMappingURL=rpc-methods.d.ts.map

package/dist/gateway/rpc-methods.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc-methods.d.ts","sourceRoot":"","sources":["../../src/gateway/rpc-methods.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAE1C,qCAAqC;AACrC,MAAM,MAAM,iBAAiB,GACzB,aAAa,GACb,mBAAmB,GACnB,UAAU,GACV,cAAc,GACd,gBAAgB,CAAA;AAWpB,kCAAkC;AAClC,MAAM,WAAW,eAAe;IAC9B,kCAAkC;IAClC,MAAM,EAAE,MAAM,EAAE,CAAA;CACjB;AAED,8BAA8B;AAC9B,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,UAAU,EAAE,iBAAiB,EAAE,CAAA;CAChC;AAED,oCAAoC;AACpC,MAAM,WAAW,iBAAiB;CAEjC;AAED,gCAAgC;AAChC,MAAM,WAAW,iBAAiB;IAChC,yCAAyC;IACzC,YAAY,EAAE,OAAO,CAAA;CACtB;AAED,mCAAmC;AACnC,MAAM,WAAW,sBAAsB;IACrC,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,0BAA0B;AAC1B,MAAM,WAAW,YAAY;IAC3B,6BAA6B;IAC7B,EAAE,EAAE,MAAM,CAAA;IACV,iBAAiB;IACjB,KAAK,EAAE,iBAAiB,CAAA;IACxB,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAChC,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,+BAA+B;AAC/B,MAAM,WAAW,sBAAsB;IACrC,uCAAuC;IACvC,aAAa,EAAE,YAAY,EAAE,CAAA;IAC7B,qDAAqD;IACrD,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,2CAA2C;AAC3C,MAAM,WAAW,qBAAqB;IACpC,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,mCAAmC;IACnC,SAAS,EAAE,SAAS,CAAA;IACpB,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAA;CACf;AAED,gCAAgC;AAChC,MAAM,WAAW,cAAc;IAC7B,uCAAuC;IACvC,SAAS,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,OAAO,CAAC,eAAe,CAAC,CAAA;IAChE,+CAA+C;IAC/C,WAAW,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAA;IACtE,gCAAgC;IAChC,gBAAgB,EAAE,CAAC,MAAM,EAAE,sBAAsB,KAAK,OAAO,CAAC,sBAAsB,CAAC,CAAA;IACrF,yDAAyD;IACzD,mBAAmB,EAAE,MAAM,iBAAiB,EAAE,CAAA;CAC/C;AAcD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,cAAc,CA4HnF;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE;IACH,qBAAqB,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,CAAA;CACxF,EACD,OAAO,EAAE,cAAc,GACtB,IAAI,CAeN"}

package/dist/gateway/rpc-methods.js

@@ -0,0 +1,145 @@
+/**
+ * Gateway RPC methods for real-time updates.
+ * Part of Epic #310, Issue #324.
+ *
+ * Provides bidirectional communication between OpenClaw agents and
+ * the openclaw-projects backend via the Gateway protocol.
+ *
+ * @see https://docs.openclaw.ai/gateway/protocol.md
+ */
+/** All valid event types for validation */
+const VALID_EVENTS = [
+    'message.new',
+    'message.delivered',
+    'task.due',
+    'task.overdue',
+    'memory.created',
+];
+/**
+ * Validate event types and filter to only valid ones.
+ *
+ * @param events - Array of event type strings
+ * @returns Array of valid NotificationEvent types
+ */
+function filterValidEvents(events) {
+    return events.filter((e) => VALID_EVENTS.includes(e));
+}
+/**
+ * Create Gateway RPC method handlers.
+ *
+ * @param options - Configuration options
+ * @returns Gateway method handlers
+ */
+export function createGatewayMethods(options) {
+    const { logger, apiClient, userId } = options;
+    // Local subscription state
+    let subscribedEvents = [];
+    return {
+        /**
+         * Subscribe to event notifications.
+         *
+         * Registers the user to receive notifications for specified event types.
+         * Invalid event types are filtered out.
+         */
+        async subscribe(params) {
+            const validEvents = filterValidEvents(params.events);
+            // Update local subscription state
+            subscribedEvents = validEvents;
+            logger.info('Gateway subscribe', {
+                userId,
+                requestedEvents: params.events,
+                subscribedEvents: validEvents,
+            });
+            return {
+                subscribed: validEvents,
+            };
+        },
+        /**
+         * Unsubscribe from all event notifications.
+         */
+        async unsubscribe(_params) {
+            const previousEvents = subscribedEvents;
+            // Clear local subscription state
+            subscribedEvents = [];
+            logger.info('Gateway unsubscribe', {
+                userId,
+                previousEvents,
+            });
+            return {
+                unsubscribed: true,
+            };
+        },
+        /**
+         * Get pending notifications for the user.
+         *
+         * Fetches notifications from the backend, optionally filtered by timestamp.
+         */
+        async getNotifications(params) {
+            const { since, limit = 20 } = params;
+            logger.debug('Gateway getNotifications', {
+                userId,
+                since,
+                limit,
+            });
+            try {
+                // Build query parameters
+                const queryParams = new URLSearchParams();
+                queryParams.set('limit', String(limit));
+                if (since) {
+                    queryParams.set('since', since);
+                }
+                const response = await apiClient.get(`/api/notifications?${queryParams}`, { userId });
+                if (!response.success) {
+                    logger.error('Gateway getNotifications API error', {
+                        userId,
+                        error: response.error.message,
+                    });
+                    return {
+                        notifications: [],
+                        hasMore: false,
+                    };
+                }
+                const { notifications, total } = response.data;
+                logger.debug('Gateway getNotifications success', {
+                    userId,
+                    count: notifications.length,
+                    total,
+                });
+                return {
+                    notifications,
+                    hasMore: notifications.length >= limit && total > notifications.length,
+                };
+            }
+            catch (error) {
+                logger.error('Gateway getNotifications failed', {
+                    userId,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                return {
+                    notifications: [],
+                    hasMore: false,
+                };
+            }
+        },
+        /**
+         * Get currently subscribed events.
+         *
+         * Internal method for checking subscription state.
+         */
+        getSubscribedEvents() {
+            return [...subscribedEvents];
+        },
+    };
+}
+/**
+ * Register Gateway RPC methods with the OpenClaw API.
+ *
+ * @param api - OpenClaw Plugin API
+ * @param methods - Gateway method handlers
+ */
+export function registerGatewayRpcMethods(api, methods) {
+    api.registerGatewayMethod('openclaw-projects.subscribe', methods.subscribe);
+    api.registerGatewayMethod('openclaw-projects.unsubscribe', methods.unsubscribe);
+    api.registerGatewayMethod('openclaw-projects.getNotifications', methods.getNotifications);
+}
+//# sourceMappingURL=rpc-methods.js.map

package/dist/gateway/rpc-methods.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc-methods.js","sourceRoot":"","sources":["../../src/gateway/rpc-methods.ts"],"names":[],"mappings":"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"}

package/dist/hooks.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Plugin lifecycle hooks implementation.
+ * Provides auto-recall and auto-capture functionality.
+ */
+import type { ApiClient } from './api-client.js';
+import type { Logger } from './logger.js';
+import type { PluginConfig } from './config.js';
+/** Event data for auto-recall hook */
+export interface AutoRecallEvent {
+    prompt: string;
+}
+/** Result from auto-recall hook */
+export interface AutoRecallResult {
+    prependContext: string;
+}
+/** Event data for auto-capture hook */
+export interface AutoCaptureEvent {
+    messages: Array<{
+        role: string;
+        content: string;
+    }>;
+}
+/** Options for creating auto-recall hook */
+export interface AutoRecallHookOptions {
+    client: ApiClient;
+    logger: Logger;
+    config: PluginConfig;
+    userId: string;
+    timeoutMs?: number;
+}
+/** Options for creating auto-capture hook */
+export interface AutoCaptureHookOptions {
+    client: ApiClient;
+    logger: Logger;
+    config: PluginConfig;
+    userId: string;
+    timeoutMs?: number;
+}
+/** Options for creating health check */
+export interface HealthCheckOptions {
+    client: ApiClient;
+    logger: Logger;
+}
+/** Health check result */
+export interface HealthCheckResult {
+    healthy: boolean;
+    error?: string;
+}
+/**
+ * Creates the auto-recall hook (before_agent_start).
+ *
+ * This hook fetches relevant context from the backend based on the user's prompt
+ * and returns it to be prepended to the conversation.
+ */
+export declare function createAutoRecallHook(options: AutoRecallHookOptions): (event: AutoRecallEvent) => Promise<AutoRecallResult | null>;
+/**
+ * Creates the auto-capture hook (agent_end).
+ *
+ * This hook analyzes the completed conversation and stores important
+ * information as memories.
+ */
+export declare function createAutoCaptureHook(options: AutoCaptureHookOptions): (event: AutoCaptureEvent) => Promise<void>;
+/** Options for graph-aware auto-recall hook */
+export interface GraphAwareRecallHookOptions {
+    client: ApiClient;
+    logger: Logger;
+    config: PluginConfig;
+    userId: string;
+    timeoutMs?: number;
+}
+/**
+ * Creates a graph-aware auto-recall hook (before_agent_start).
+ *
+ * This hook uses the graph-aware context retrieval API to fetch memories
+ * across the user's relationship graph (personal, contact, group, relationship
+ * scopes). Falls back to basic memory search if the graph-aware endpoint
+ * is unavailable.
+ *
+ * Part of Epic #486, Issue #497.
+ */
+export declare function createGraphAwareRecallHook(options: GraphAwareRecallHookOptions): (event: AutoRecallEvent) => Promise<AutoRecallResult | null>;
+/**
+ * Creates the health check function.
+ */
+export declare function createHealthCheck(options: HealthCheckOptions): () => Promise<HealthCheckResult>;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAkB/C,sCAAsC;AACtC,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAA;CACf;AAED,mCAAmC;AACnC,MAAM,WAAW,gBAAgB;IAC/B,cAAc,EAAE,MAAM,CAAA;CACvB;AAED,uCAAuC;AACvC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,KAAK,CAAC;QACd,IAAI,EAAE,MAAM,CAAA;QACZ,OAAO,EAAE,MAAM,CAAA;KAChB,CAAC,CAAA;CACH;AAED,4CAA4C;AAC5C,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,SAAS,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,YAAY,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,6CAA6C;AAC7C,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,SAAS,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,YAAY,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,wCAAwC;AACxC,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,SAAS,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;CACf;AAED,0BAA0B;AAC1B,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AA6BD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,qBAAqB,GAC7B,CAAC,KAAK,EAAE,eAAe,KAAK,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAmD9D;AA4DD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,sBAAsB,GAC9B,CAAC,KAAK,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CA8C5C;AAgDD,+CAA+C;AAC/C,MAAM,WAAW,2BAA2B;IAC1C,MAAM,EAAE,SAAS,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,YAAY,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AA6BD;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,2BAA2B,GACnC,CAAC,KAAK,EAAE,eAAe,KAAK,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAmD9D;AAqDD;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,kBAAkB,GAC1B,MAAM,OAAO,CAAC,iBAAiB,CAAC,CA2BlC"}