@revealui/ai 0.1.0

package/dist/audit/types.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Audit Trail Types
+ *
+ * Defines the schema for all audit events, entries, policies, and alerts.
+ * The audit trail is an append-only, immutable log of all agent activity.
+ * Agents receive a write-only emitter; humans control the observer.
+ */
+import { z } from 'zod';
+/** All possible audit event types */
+export declare const AuditEventType: z.ZodEnum<{
+    "agent:registered": "agent:registered";
+    "agent:unregistered": "agent:unregistered";
+    "agent:task:started": "agent:task:started";
+    "agent:task:completed": "agent:task:completed";
+    "agent:task:failed": "agent:task:failed";
+    "agent:task:timeout": "agent:task:timeout";
+    "agent:tool:called": "agent:tool:called";
+    "agent:tool:result": "agent:tool:result";
+    "agent:tool:denied": "agent:tool:denied";
+    "agent:llm:request": "agent:llm:request";
+    "agent:llm:response": "agent:llm:response";
+    "agent:llm:error": "agent:llm:error";
+    "agent:memory:read": "agent:memory:read";
+    "agent:memory:write": "agent:memory:write";
+    "agent:memory:delete": "agent:memory:delete";
+    "agent:delegation:requested": "agent:delegation:requested";
+    "agent:delegation:completed": "agent:delegation:completed";
+    "agent:delegation:denied": "agent:delegation:denied";
+    "policy:violation": "policy:violation";
+    "policy:warning": "policy:warning";
+    "byok:key:accessed": "byok:key:accessed";
+    "human:agent:halted": "human:agent:halted";
+    "human:agent:resumed": "human:agent:resumed";
+    "human:fleet:halted": "human:fleet:halted";
+    "human:fleet:resumed": "human:fleet:resumed";
+    "human:policy:added": "human:policy:added";
+    "human:policy:removed": "human:policy:removed";
+    "human:alert:acknowledged": "human:alert:acknowledged";
+}>;
+export type AuditEventType = z.infer<typeof AuditEventType>;
+export declare const AuditSeverity: z.ZodEnum<{
+    critical: "critical";
+    info: "info";
+    warn: "warn";
+}>;
+export type AuditSeverity = z.infer<typeof AuditSeverity>;
+/** A single immutable audit log entry */
+export declare const AuditEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    timestamp: z.ZodDate;
+    eventType: z.ZodEnum<{
+        "agent:registered": "agent:registered";
+        "agent:unregistered": "agent:unregistered";
+        "agent:task:started": "agent:task:started";
+        "agent:task:completed": "agent:task:completed";
+        "agent:task:failed": "agent:task:failed";
+        "agent:task:timeout": "agent:task:timeout";
+        "agent:tool:called": "agent:tool:called";
+        "agent:tool:result": "agent:tool:result";
+        "agent:tool:denied": "agent:tool:denied";
+        "agent:llm:request": "agent:llm:request";
+        "agent:llm:response": "agent:llm:response";
+        "agent:llm:error": "agent:llm:error";
+        "agent:memory:read": "agent:memory:read";
+        "agent:memory:write": "agent:memory:write";
+        "agent:memory:delete": "agent:memory:delete";
+        "agent:delegation:requested": "agent:delegation:requested";
+        "agent:delegation:completed": "agent:delegation:completed";
+        "agent:delegation:denied": "agent:delegation:denied";
+        "policy:violation": "policy:violation";
+        "policy:warning": "policy:warning";
+        "byok:key:accessed": "byok:key:accessed";
+        "human:agent:halted": "human:agent:halted";
+        "human:agent:resumed": "human:agent:resumed";
+        "human:fleet:halted": "human:fleet:halted";
+        "human:fleet:resumed": "human:fleet:resumed";
+        "human:policy:added": "human:policy:added";
+        "human:policy:removed": "human:policy:removed";
+        "human:alert:acknowledged": "human:alert:acknowledged";
+    }>;
+    severity: z.ZodEnum<{
+        critical: "critical";
+        info: "info";
+        warn: "warn";
+    }>;
+    agentId: z.ZodString;
+    taskId: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    policyViolations: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type AuditEntry = z.infer<typeof AuditEntrySchema>;
+/** Filters for querying audit entries (human-side only) */
+export interface AuditFilter {
+    agentId?: string;
+    taskId?: string;
+    sessionId?: string;
+    eventTypes?: AuditEventType[];
+    severity?: AuditSeverity[];
+    startTime?: Date;
+    endTime?: Date;
+    limit?: number;
+    offset?: number;
+}
+/** Action to take when a policy is violated */
+export declare const PolicyAction: z.ZodEnum<{
+    alert: "alert";
+    halt_agent: "halt_agent";
+    halt_all: "halt_all";
+}>;
+export type PolicyAction = z.infer<typeof PolicyAction>;
+/** A human-defined policy rule */
+export interface AuditPolicy {
+    /** Unique policy ID */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** What this policy enforces */
+    description: string;
+    /** Severity when triggered */
+    severity: AuditSeverity;
+    /** Action to take on violation */
+    action: PolicyAction;
+    /** Condition function: receives the current entry and recent history */
+    condition: (entry: AuditEntry, recentHistory: AuditEntry[]) => boolean;
+    /** Whether this policy is active */
+    enabled: boolean;
+    /** Who created this policy */
+    createdBy: string;
+    /** When this policy was created */
+    createdAt: Date;
+}
+/** An alert generated by a policy violation */
+export interface AuditAlert {
+    /** Unique alert ID */
+    id: string;
+    /** Policy that triggered this alert */
+    policyId: string;
+    /** Policy name for display */
+    policyName: string;
+    /** The audit entry that triggered it */
+    triggeringEntryId: string;
+    /** Agent involved */
+    agentId: string;
+    /** Alert severity */
+    severity: AuditSeverity;
+    /** Action taken (or recommended) */
+    action: PolicyAction;
+    /** When the alert was generated */
+    createdAt: Date;
+    /** Whether a human has acknowledged this alert */
+    acknowledged: boolean;
+    /** Who acknowledged it */
+    acknowledgedBy?: string;
+    /** When it was acknowledged */
+    acknowledgedAt?: Date;
+}
+/** Tracked status of an agent from the audit system's perspective */
+export interface AuditAgentStatus {
+    agentId: string;
+    halted: boolean;
+    haltedBy?: string;
+    haltedAt?: Date;
+    haltReason?: string;
+    totalEvents: number;
+    totalViolations: number;
+    lastEventAt?: Date;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/audit/types.d.ts.map

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

package/dist/audit/types.js

@@ -0,0 +1,80 @@
+/**
+ * Audit Trail Types
+ *
+ * Defines the schema for all audit events, entries, policies, and alerts.
+ * The audit trail is an append-only, immutable log of all agent activity.
+ * Agents receive a write-only emitter; humans control the observer.
+ */
+import { z } from 'zod';
+// ─── Event Types ────────────────────────────────────────────────────────────
+/** All possible audit event types */
+export const AuditEventType = z.enum([
+    // Agent lifecycle
+    'agent:registered',
+    'agent:unregistered',
+    // Task execution
+    'agent:task:started',
+    'agent:task:completed',
+    'agent:task:failed',
+    'agent:task:timeout',
+    // Tool usage
+    'agent:tool:called',
+    'agent:tool:result',
+    'agent:tool:denied',
+    // LLM interactions
+    'agent:llm:request',
+    'agent:llm:response',
+    'agent:llm:error',
+    // Memory operations
+    'agent:memory:read',
+    'agent:memory:write',
+    'agent:memory:delete',
+    // Delegation
+    'agent:delegation:requested',
+    'agent:delegation:completed',
+    'agent:delegation:denied',
+    // Policy and safety
+    'policy:violation',
+    'policy:warning',
+    // BYOK key lifecycle
+    'byok:key:accessed',
+    // Human actions
+    'human:agent:halted',
+    'human:agent:resumed',
+    'human:fleet:halted',
+    'human:fleet:resumed',
+    'human:policy:added',
+    'human:policy:removed',
+    'human:alert:acknowledged',
+]);
+// ─── Severity ───────────────────────────────────────────────────────────────
+export const AuditSeverity = z.enum(['info', 'warn', 'critical']);
+// ─── Audit Entry ────────────────────────────────────────────────────────────
+/** A single immutable audit log entry */
+export const AuditEntrySchema = z.object({
+    /** Unique entry ID (UUID v4) */
+    id: z.string().uuid(),
+    /** When the event occurred */
+    timestamp: z.date(),
+    /** Type of event */
+    eventType: AuditEventType,
+    /** Severity classification */
+    severity: AuditSeverity,
+    /** Agent that triggered the event */
+    agentId: z.string(),
+    /** Task ID if applicable */
+    taskId: z.string().optional(),
+    /** Session or orchestration run ID */
+    sessionId: z.string().optional(),
+    /** Event-specific data */
+    payload: z.record(z.string(), z.unknown()),
+    /** Policy violations triggered by this event */
+    policyViolations: z.array(z.string()).default([]),
+});
+// ─── Policy Types ───────────────────────────────────────────────────────────
+/** Action to take when a policy is violated */
+export const PolicyAction = z.enum([
+    'alert', // Generate an alert for human review
+    'halt_agent', // Immediately halt the violating agent
+    'halt_all', // Halt the entire agent fleet (emergency)
+]);

package/dist/client/hooks/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * React Hooks for AI System
+ *
+ * Frontend integration hooks:
+ * - useWorkingMemory: Working memory management
+ * - useEpisodicMemory: Episodic memory management
+ * - useAgentContext: Agent context management
+ * - useAgentEvents: Real-time agent event monitoring
+ * - useAgentMetrics: Agent metrics and statistics
+ * - useEventQuery: Advanced event querying
+ * - useEventStream: Real-time event streaming
+ * - usePaginatedEvents: Paginated event display
+ * - useAgentStream: SSE streaming for agent responses
+ *
+ * @packageDocumentation
+ */
+export { type UseAgentContextOptions, type UseAgentContextReturn, useAgentContext, } from './useAgentContext.js';
+export { useAgentEvents, useAgentMetrics, useEventQuery, useEventStream, useLLMUsageStats, useMetricsSummary, usePaginatedEvents, useToolUsageStats, } from './useAgentEvents.js';
+export { type AgentStreamChunk, type AgentStreamRequest, type UseAgentStreamReturn, type UseAgentStreamState, useAgentStream, } from './useAgentStream.js';
+export { type UseEpisodicMemoryReturn, useEpisodicMemory, } from './useEpisodicMemory.js';
+export { type UseWorkingMemoryOptions, type UseWorkingMemoryReturn, useWorkingMemory, } from './useWorkingMemory.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/client/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/hooks/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EACL,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,eAAe,GAChB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EACL,cAAc,EACd,eAAe,EACf,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,cAAc,GACf,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,KAAK,uBAAuB,EAC5B,iBAAiB,GAClB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,gBAAgB,GACjB,MAAM,uBAAuB,CAAA"}

package/dist/client/hooks/index.js

@@ -0,0 +1,21 @@
+/**
+ * React Hooks for AI System
+ *
+ * Frontend integration hooks:
+ * - useWorkingMemory: Working memory management
+ * - useEpisodicMemory: Episodic memory management
+ * - useAgentContext: Agent context management
+ * - useAgentEvents: Real-time agent event monitoring
+ * - useAgentMetrics: Agent metrics and statistics
+ * - useEventQuery: Advanced event querying
+ * - useEventStream: Real-time event streaming
+ * - usePaginatedEvents: Paginated event display
+ * - useAgentStream: SSE streaming for agent responses
+ *
+ * @packageDocumentation
+ */
+export { useAgentContext, } from './useAgentContext.js';
+export { useAgentEvents, useAgentMetrics, useEventQuery, useEventStream, useLLMUsageStats, useMetricsSummary, usePaginatedEvents, useToolUsageStats, } from './useAgentEvents.js';
+export { useAgentStream, } from './useAgentStream.js';
+export { useEpisodicMemory, } from './useEpisodicMemory.js';
+export { useWorkingMemory, } from './useWorkingMemory.js';

package/dist/client/hooks/useAgentContext.d.ts

@@ -0,0 +1,30 @@
+/**
+ * useAgentContext Hook
+ *
+ * React hook for managing agent context in client components.
+ * Wraps AgentContextManager for client-side usage.
+ */
+export interface UseAgentContextOptions {
+    autoSync?: boolean;
+    syncInterval?: number;
+}
+export interface UseAgentContextReturn {
+    context: Record<string, unknown>;
+    getContext: (key: string) => unknown;
+    setContext: (key: string, value: unknown) => Promise<void>;
+    updateContext: (updates: Partial<Record<string, unknown>>) => Promise<void>;
+    removeContext: (key: string) => Promise<void>;
+    isLoading: boolean;
+    error: Error | null;
+    sync: () => Promise<void>;
+}
+/**
+ * React hook for agent context management.
+ *
+ * @param sessionId - Session identifier
+ * @param agentId - Agent identifier
+ * @param options - Hook options
+ * @returns Agent context state and operations
+ */
+export declare function useAgentContext(sessionId: string, agentId: string, options?: UseAgentContextOptions): UseAgentContextReturn;
+//# sourceMappingURL=useAgentContext.d.ts.map

package/dist/client/hooks/useAgentContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAgentContext.d.ts","sourceRoot":"","sources":["../../../src/client/hooks/useAgentContext.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAChC,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;IACpC,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1D,aAAa,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3E,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7C,SAAS,EAAE,OAAO,CAAA;IAClB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IACnB,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B;AAeD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,sBAA2B,GACnC,qBAAqB,CAkKvB"}

package/dist/client/hooks/useAgentContext.js

@@ -0,0 +1,161 @@
+/**
+ * useAgentContext Hook
+ *
+ * React hook for managing agent context in client components.
+ * Wraps AgentContextManager for client-side usage.
+ */
+import { useCallback, useEffect, useState } from 'react';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const parseContextPayload = (payload) => {
+    if (!isRecord(payload))
+        return {};
+    const { context } = payload;
+    return isRecord(context) ? context : {};
+};
+// =============================================================================
+// Hook
+// =============================================================================
+/**
+ * React hook for agent context management.
+ *
+ * @param sessionId - Session identifier
+ * @param agentId - Agent identifier
+ * @param options - Hook options
+ * @returns Agent context state and operations
+ */
+export function useAgentContext(sessionId, agentId, options = {}) {
+    const { autoSync = false, syncInterval = 5000 } = options;
+    const [context, setContextState] = useState({});
+    const [isLoading, setIsLoading] = useState(true);
+    const [error, setError] = useState(null);
+    // Load initial state
+    useEffect(() => {
+        let mounted = true;
+        async function load() {
+            try {
+                setIsLoading(true);
+                setError(null);
+                const response = await fetch(`/api/memory/context/${sessionId}/${agentId}`);
+                if (!response.ok) {
+                    throw new Error(`Failed to load agent context: ${response.statusText}`);
+                }
+                const payload = (await response.json());
+                if (!mounted)
+                    return;
+                setContextState(parseContextPayload(payload));
+            }
+            catch (err) {
+                if (!mounted)
+                    return;
+                setError(err instanceof Error ? err : new Error('Unknown error'));
+            }
+            finally {
+                if (mounted) {
+                    setIsLoading(false);
+                }
+            }
+        }
+        void load();
+        return () => {
+            mounted = false;
+        };
+    }, [sessionId, agentId]);
+    // Sync function
+    const sync = useCallback(async () => {
+        try {
+            const response = await fetch(`/api/memory/context/${sessionId}/${agentId}`);
+            if (!response.ok) {
+                throw new Error(`Failed to sync agent context: ${response.statusText}`);
+            }
+            const payload = (await response.json());
+            setContextState(parseContextPayload(payload));
+            setError(null);
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error('Unknown error'));
+        }
+    }, [sessionId, agentId]);
+    // Auto-sync
+    useEffect(() => {
+        if (!autoSync)
+            return;
+        const interval = setInterval(() => {
+            void sync();
+        }, syncInterval);
+        return () => clearInterval(interval);
+    }, [autoSync, syncInterval, sync]);
+    // Get context value
+    const getContext = useCallback((key) => {
+        return context[key];
+    }, [context]);
+    // Set context value
+    const setContext = useCallback(async (key, value) => {
+        try {
+            setError(null);
+            const response = await fetch(`/api/memory/context/${sessionId}/${agentId}`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ [key]: value }),
+            });
+            if (!response.ok) {
+                throw new Error(`Failed to update context: ${response.statusText}`);
+            }
+            const payload = (await response.json());
+            setContextState(parseContextPayload(payload));
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error('Unknown error'));
+            throw err;
+        }
+    }, [sessionId, agentId]);
+    // Update context
+    const updateContext = useCallback(async (updates) => {
+        try {
+            setError(null);
+            const response = await fetch(`/api/memory/context/${sessionId}/${agentId}`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(updates),
+            });
+            if (!response.ok) {
+                throw new Error(`Failed to update context: ${response.statusText}`);
+            }
+            const payload = (await response.json());
+            setContextState(parseContextPayload(payload));
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error('Unknown error'));
+            throw err;
+        }
+    }, [sessionId, agentId]);
+    // Remove context key
+    const removeContext = useCallback(async (key) => {
+        try {
+            setError(null);
+            const response = await fetch(`/api/memory/context/${sessionId}/${agentId}`, {
+                method: 'DELETE',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ key }),
+            });
+            if (!response.ok) {
+                throw new Error(`Failed to remove context key: ${response.statusText}`);
+            }
+            const payload = (await response.json());
+            setContextState(parseContextPayload(payload));
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error('Unknown error'));
+            throw err;
+        }
+    }, [sessionId, agentId]);
+    return {
+        context,
+        getContext,
+        setContext,
+        updateContext,
+        removeContext,
+        isLoading,
+        error,
+        sync,
+    };
+}

package/dist/client/hooks/useAgentEvents.d.ts

@@ -0,0 +1,126 @@
+/**
+ * @revealui/ai - React Hooks for Observability
+ *
+ * React hooks for accessing and displaying agent events and metrics.
+ */
+import type { AgentEventLogger } from '../../observability/logger.js';
+import type { AgentMetricsCollector } from '../../observability/metrics.js';
+import { AgentEventQuery } from '../../observability/query.js';
+import type { AgentMetrics, AnyAgentEvent, EventFilter, MetricsSummary } from '../../observability/types.js';
+/**
+ * Hook for accessing agent events with real-time updates
+ */
+export declare function useAgentEvents(logger: AgentEventLogger, filter?: EventFilter, options?: {
+    refreshInterval?: number;
+    autoRefresh?: boolean;
+}): {
+    events: AnyAgentEvent[];
+    loading: boolean;
+    refresh: () => void;
+    count: number;
+};
+/**
+ * Hook for accessing agent metrics with real-time updates
+ */
+export declare function useAgentMetrics(collector: AgentMetricsCollector, agentId: string, options?: {
+    refreshInterval?: number;
+    autoRefresh?: boolean;
+}): {
+    metrics: AgentMetrics | null;
+    loading: boolean;
+    refresh: () => void;
+};
+/**
+ * Hook for accessing metrics summary
+ */
+export declare function useMetricsSummary(collector: AgentMetricsCollector, filter?: EventFilter, options?: {
+    refreshInterval?: number;
+    autoRefresh?: boolean;
+}): {
+    summary: MetricsSummary | null;
+    loading: boolean;
+    refresh: () => void;
+};
+/**
+ * Hook for querying events with advanced filters
+ */
+export declare function useEventQuery(logger: AgentEventLogger): {
+    query: AgentEventQuery;
+    getRecentEvents: (milliseconds: number, count?: number) => AnyAgentEvent[];
+    getEventsForAgent: (agentId: string) => AnyAgentEvent[];
+    getEventsForSession: (sessionId: string) => AnyAgentEvent[];
+    searchEvents: (searchText: string, filter?: EventFilter) => AnyAgentEvent[];
+    paginateEvents: (page: number, pageSize: number, filter?: EventFilter) => {
+        events: AnyAgentEvent[];
+        page: number;
+        pageSize: number;
+        totalPages: number;
+        totalEvents: number;
+    };
+};
+/**
+ * Hook for tool usage statistics
+ */
+export declare function useToolUsageStats(collector: AgentMetricsCollector, options?: {
+    refreshInterval?: number;
+    autoRefresh?: boolean;
+}): {
+    stats: {
+        toolName: string;
+        metrics: {
+            totalCalls: number;
+            successCount: number;
+            failureCount: number;
+            averageDurationMs: number;
+            lastUsed: number;
+        };
+    }[];
+    loading: boolean;
+    refresh: () => void;
+};
+/**
+ * Hook for LLM usage statistics
+ */
+export declare function useLLMUsageStats(collector: AgentMetricsCollector, options?: {
+    refreshInterval?: number;
+    autoRefresh?: boolean;
+}): {
+    stats: {
+        totalCalls: number;
+        totalPromptTokens: number;
+        totalCompletionTokens: number;
+        totalCost: number;
+        averageDurationMs: number;
+        cacheHitRate: number;
+        modelUsage: Record<string, number>;
+    } | null;
+    loading: boolean;
+    refresh: () => void;
+};
+/**
+ * Hook for real-time event stream
+ */
+export declare function useEventStream(logger: AgentEventLogger, options?: {
+    maxEvents?: number;
+    filter?: EventFilter;
+}): {
+    events: AnyAgentEvent[];
+    latestEvent: AnyAgentEvent | undefined;
+};
+/**
+ * Hook for paginated events
+ */
+export declare function usePaginatedEvents(logger: AgentEventLogger, initialPageSize?: number, filter?: EventFilter): {
+    nextPage: () => void;
+    prevPage: () => void;
+    goToPage: (newPage: number) => void;
+    changePageSize: (newSize: number) => void;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+    events: AnyAgentEvent[];
+    page: number;
+    pageSize: number;
+    totalPages: number;
+    totalEvents: number;
+};
+//# sourceMappingURL=useAgentEvents.d.ts.map

package/dist/client/hooks/useAgentEvents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAgentEvents.d.ts","sourceRoot":"","sources":["../../../src/client/hooks/useAgentEvents.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAA;AACrE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAA;AAC3E,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAA;AAC9D,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,WAAW,EACX,cAAc,EACf,MAAM,8BAA8B,CAAA;AAErC;;GAEG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,gBAAgB,EACxB,MAAM,CAAC,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE;IACR,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;;;;;EA+BF;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,qBAAqB,EAChC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IACR,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;;;;EA8BF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,qBAAqB,EAChC,MAAM,CAAC,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE;IACR,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;;;;EA8BF;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,gBAAgB;;oCAInC,MAAM,UAAU,MAAM;iCAO3B,MAAM;qCAOJ,MAAM;+BAOL,MAAM,WAAW,WAAW;2BAOlC,MAAM,YAAY,MAAM,WAAW,WAAW;;;;;;;EAcxD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,qBAAqB,EAChC,OAAO,CAAC,EAAE;IACR,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;;kBAIa,MAAM;iBACP;YACP,UAAU,EAAE,MAAM,CAAA;YAClB,YAAY,EAAE,MAAM,CAAA;YACpB,YAAY,EAAE,MAAM,CAAA;YACpB,iBAAiB,EAAE,MAAM,CAAA;YACzB,QAAQ,EAAE,MAAM,CAAA;SACjB;;;;EA8BN;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,qBAAqB,EAChC,OAAO,CAAC,EAAE;IACR,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;;oBAGa,MAAM;2BACC,MAAM;+BACF,MAAM;mBAClB,MAAM;2BACE,MAAM;sBACX,MAAM;oBACR,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;;;;EA6BrC;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,gBAAgB,EACxB,OAAO,CAAC,EAAE;IACR,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;;;EAkBF;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,gBAAgB,EACxB,eAAe,SAAK,EACpB,MAAM,CAAC,EAAE,WAAW;;;wBAsBmB,MAAM;8BAIA,MAAM;;;;;;;;EAcpD"}