@elqnt/agents 3.2.0 → 3.3.0

package/dist/hooks/index.d.mts

@@ -1,63 +1,13 @@
-import { ApiResponse, ApiClientOptions } from '@elqnt/api-client';
-import { Z as AgentJob, A as Agent, aF as AgentSummary, dw as SkillUserConfig, dd as ResolveSkillConfigResponse, dk as Skill, dO as SubAgent, e9 as ToolDefinition, aY as AgentWidget } from '../agent-models-C36pvpUb.mjs';
-import { ba as UserIntegration, ap as IntegrationProviderTS, aA as IntegrationTypeTS, h as CreateSandboxRequest, aW as Sandbox } from '../sandbox-BHeWPjLU.mjs';
-import { DateFilter, SchedulerSchedule, SchedulerTask } from '../api/index.mjs';
+import { ApiClientOptions } from '@elqnt/api-client';
+import { A as Agent, aI as AgentSummary, ds as Skill, dV as SubAgent, eh as ToolDefinition, Z as AgentJob, a$ as AgentWidget, dD as SkillUserConfig, dk as ResolveSkillConfigResponse, aB as AgentStatusUpdate, eG as TriggerBackgroundAgentRequest, eH as TriggerBackgroundAgentResponse, bc as BackgroundAgentStatusResponse } from '../agent-models-DLQlC7N6.mjs';
+export { ba as BackgroundAgentProgressEvent } from '../agent-models-DLQlC7N6.mjs';
+import { DateFilter, SchedulerTask, SchedulerSchedule } from '../api/index.mjs';
+import { ba as UserIntegration, ap as IntegrationProviderTS, aA as IntegrationTypeTS, h as CreateSandboxRequest, aW as Sandbox } from '../sandbox-DOxoM2Ge.mjs';
+import { a as StructuredOutputRequest, b as StructuredOutputResponse } from '../structured-Bs0IjwLD.mjs';
+import { ChatMessage, Attachment } from '@elqnt/chat/models';
+export { B as BGAgentTransport, a as BGAgentTransportConfig } from '../types-C2qd5f-E.mjs';
 import '@elqnt/types';
 
-interface UseAsyncOptions {
-    onError?: (error: string) => void;
-}
-interface UseAsyncReturn<TResult, TArgs extends unknown[] = []> {
-    execute: (...args: TArgs) => Promise<TResult>;
-    loading: boolean;
-    error: string | null;
-    clearError: () => void;
-}
-/**
- * Generic async hook for any promise-returning function.
- * Uses a request counter to properly track concurrent requests.
- */
-declare function useAsync<TResult, TArgs extends unknown[] = []>(asyncFn: (...args: TArgs) => Promise<TResult>, options?: UseAsyncOptions): UseAsyncReturn<TResult, TArgs>;
-/**
- * Specialized async hook for API operations that return ApiResponse.
- * Automatically extracts data and handles API errors.
- *
- * @param asyncFn - Function that returns ApiResponse<TResponse>
- * @param extractor - Function to extract the desired result from response data
- * @param defaultValue - Default value to return on error
- * @param options - Optional configuration
- *
- * @example
- * ```tsx
- * const { execute: listAgents, loading, error } = useApiAsync(
- *   () => listAgentsApi(optionsRef.current),
- *   (data) => data.agents,
- *   []
- * );
- * ```
- */
-declare function useApiAsync<TResponse, TResult, TArgs extends unknown[] = []>(asyncFn: (...args: TArgs) => Promise<ApiResponse<TResponse>>, extractor: (data: TResponse) => TResult, defaultValue: TResult, options?: UseAsyncOptions): UseAsyncReturn<TResult, TArgs>;
-
-/**
- * Creates a ref that stays synchronized with the provided options.
- * Useful for accessing current options values in callbacks without
- * causing re-renders or stale closure issues.
- *
- * @param options - The options object to track
- * @returns A ref that always contains the latest options
- *
- * @example
- * ```tsx
- * const optionsRef = useOptionsRef(options);
- *
- * const fetchData = useCallback(async () => {
- *   // Always has the latest options, no stale closure
- *   const result = await api.fetch(optionsRef.current);
- * }, []); // No need to include options in deps
- * ```
- */
-declare function useOptionsRef<T>(options: T): React.MutableRefObject<T>;
-
 type UseAgentsOptions = ApiClientOptions;
 /**
  * Hook for agent CRUD operations
@@ -82,11 +32,15 @@ declare function useAgents(options: UseAgentsOptions): {
     updateAgent: (agentId: string, agent: Partial<Agent>) => Promise<Agent | null>;
     deleteAgent: (agentId: string) => Promise<boolean>;
     getDefaultAgent: () => Promise<Agent | null>;
+    exportAgent: (agentId: string) => Promise<Agent>;
+    importAgent: (agent: Agent) => Promise<Agent | null>;
 };
+
+type UseSkillsOptions = ApiClientOptions;
 /**
  * Hook for skill CRUD operations
  */
-declare function useSkills(options: UseAgentsOptions): {
+declare function useSkills(options: UseSkillsOptions): {
     loading: boolean;
     error: string | null;
     listSkills: () => Promise<Skill[]>;
@@ -96,10 +50,12 @@ declare function useSkills(options: UseAgentsOptions): {
     deleteSkill: (skillId: string) => Promise<boolean>;
     getCategories: () => Promise<string[]>;
 };
+
+type UseSubAgentsOptions = ApiClientOptions;
 /**
  * Hook for sub-agent CRUD operations
  */
-declare function useSubAgents(options: UseAgentsOptions): {
+declare function useSubAgents(options: UseSubAgentsOptions): {
     loading: boolean;
     error: string | null;
     listSubAgents: () => Promise<SubAgent[]>;
@@ -108,6 +64,8 @@ declare function useSubAgents(options: UseAgentsOptions): {
     updateSubAgent: (subAgentId: string, subAgent: Partial<SubAgent>) => Promise<SubAgent | null>;
     deleteSubAgent: (subAgentId: string) => Promise<boolean>;
 };
+
+type UseToolDefinitionsOptions = ApiClientOptions;
 /**
  * Hook for tool definition CRUD operations
  *
@@ -121,7 +79,7 @@ declare function useSubAgents(options: UseAgentsOptions): {
  * const toolDefs = await listToolDefinitions();
  * ```
  */
-declare function useToolDefinitions(options: UseAgentsOptions): {
+declare function useToolDefinitions(options: UseToolDefinitionsOptions): {
     loading: boolean;
     error: string | null;
     listToolDefinitions: () => Promise<ToolDefinition[]>;
@@ -131,6 +89,8 @@ declare function useToolDefinitions(options: UseAgentsOptions): {
     updateToolDefinition: (toolDefId: string, toolDefinition: Partial<ToolDefinition>) => Promise<ToolDefinition | null>;
     deleteToolDefinition: (toolDefId: string) => Promise<boolean>;
 };
+
+type UseAgentJobsOptions = ApiClientOptions;
 /**
  * Hook for agent job CRUD operations
  *
@@ -145,7 +105,7 @@ declare function useToolDefinitions(options: UseAgentsOptions): {
  * await pauseAgentJob(jobId);
  * ```
  */
-declare function useAgentJobs(options: UseAgentsOptions): {
+declare function useAgentJobs(options: UseAgentJobsOptions): {
     loading: boolean;
     error: string | null;
     listAgentJobs: () => Promise<AgentJob[]>;
@@ -156,7 +116,8 @@ declare function useAgentJobs(options: UseAgentsOptions): {
     pauseAgentJob: (jobId: string) => Promise<AgentJob | null>;
     resumeAgentJob: (jobId: string) => Promise<AgentJob | null>;
 };
-interface UseWidgetsOptions extends UseAgentsOptions {
+
+interface UseWidgetsOptions extends ApiClientOptions {
     agentId: string;
 }
 /**
@@ -184,6 +145,8 @@ declare function useWidgets(options: UseWidgetsOptions): {
     deleteWidget: (widgetId: string) => Promise<boolean>;
     setDefaultWidget: (widgetId: string) => Promise<boolean>;
 };
+
+type UseSkillUserConfigOptions = ApiClientOptions;
 /**
  * Hook for skill user configuration operations
  *
@@ -198,7 +161,7 @@ declare function useWidgets(options: UseWidgetsOptions): {
  * await updateSkillUserConfig(skillId, { enabled: true });
  * ```
  */
-declare function useSkillUserConfig(options: UseAgentsOptions): {
+declare function useSkillUserConfig(options: UseSkillUserConfigOptions): {
     loading: boolean;
     error: string | null;
     getSkillUserConfig: (skillId: string, agentId?: string | undefined) => Promise<SkillUserConfig | null>;
@@ -216,6 +179,8 @@ declare function useSkillUserConfig(options: UseAgentsOptions): {
     } | undefined) => Promise<SkillUserConfig[]>;
     resolveSkillConfig: (skillId: string, agentId: string) => Promise<ResolveSkillConfigResponse | null>;
 };
+
+type UseAnalyticsOptions = ApiClientOptions;
 /**
  * Hook for agent analytics operations
  *
@@ -229,7 +194,7 @@ declare function useSkillUserConfig(options: UseAgentsOptions): {
  * const chatsData = await getAgentChatsAnalytics({ from: '2024-01-01', to: '2024-12-31' });
  * ```
  */
-declare function useAnalytics(options: UseAgentsOptions): {
+declare function useAnalytics(options: UseAnalyticsOptions): {
     loading: boolean;
     error: string | null;
     getAgentChatsAnalytics: (params: {
@@ -245,6 +210,8 @@ declare function useAnalytics(options: UseAgentsOptions): {
         date_filter: DateFilter;
     }) => Promise<unknown[]>;
 };
+
+type UseIntegrationsOptions = ApiClientOptions;
 /**
  * Hook for user integration operations (OAuth connections)
  *
@@ -259,7 +226,7 @@ declare function useAnalytics(options: UseAgentsOptions): {
  * const { auth_url } = await connectIntegration({ provider: 'google', integrationType: 'email', redirectUri: '/callback' });
  * ```
  */
-declare function useIntegrations(options: UseAgentsOptions): {
+declare function useIntegrations(options: UseIntegrationsOptions): {
     loading: boolean;
     error: string | null;
     listIntegrations: () => Promise<UserIntegration[]>;
@@ -291,6 +258,8 @@ declare function useIntegrations(options: UseAgentsOptions): {
         instancesCreated: number;
     } | null>;
 };
+
+type UseSandboxOptions = ApiClientOptions;
 /**
  * Hook for sandbox operations (AI-generated HTML sandboxes)
  *
@@ -305,7 +274,7 @@ declare function useIntegrations(options: UseAgentsOptions): {
  * console.log(result.url); // sandbox URL
  * ```
  */
-declare function useSandbox(options: UseAgentsOptions): {
+declare function useSandbox(options: UseSandboxOptions): {
     loading: boolean;
     error: string | null;
     createSandbox: (request: Omit<CreateSandboxRequest, "orgId">) => Promise<{
@@ -328,6 +297,36 @@ declare function useSandbox(options: UseAgentsOptions): {
     }>;
     deleteSandbox: (sandboxId: string) => Promise<boolean>;
 };
+
+type UseStructuredOutputOptions = ApiClientOptions;
+/**
+ * Hook for the one-shot structured-output LLM primitive.
+ *
+ * @example
+ * ```tsx
+ * const { run, loading, error, data } = useStructuredOutput<{ title: string }>({
+ *   baseUrl: apiGatewayUrl,
+ *   orgId: selectedOrgId,
+ * });
+ *
+ * await run({
+ *   provider: "anthropic",
+ *   model: "claude-sonnet-4-6",
+ *   userPrompt: "Give me a title for a slide about onboarding.",
+ *   schema: { type: "object", properties: { title: { type: "string" } }, required: ["title"] },
+ *   schemaName: "slide_title",
+ *   maxTokens: 256,
+ * });
+ * ```
+ */
+declare function useStructuredOutput<T = unknown>(options: UseStructuredOutputOptions): {
+    run: (request: StructuredOutputRequest) => Promise<StructuredOutputResponse<T> | null>;
+    loading: boolean;
+    error: string | null;
+    clearError: () => void;
+};
+
+type UseSchedulerTasksOptions = ApiClientOptions;
 /**
  * Hook for scheduler task operations
  *
@@ -342,7 +341,7 @@ declare function useSandbox(options: UseAgentsOptions): {
  * await snoozeTask(taskId, { amount: 30, unit: "minutes" });
  * ```
  */
-declare function useSchedulerTasks(options: UseAgentsOptions): {
+declare function useSchedulerTasks(options: UseSchedulerTasksOptions): {
     loading: boolean;
     error: string | null;
     listTasks: (params?: {
@@ -361,6 +360,8 @@ declare function useSchedulerTasks(options: UseAgentsOptions): {
     completeTask: (taskId: string) => Promise<SchedulerTask | null>;
     startTask: (taskId: string) => Promise<SchedulerTask | null>;
 };
+
+type UseSchedulerSchedulesOptions = ApiClientOptions;
 /**
  * Hook for scheduler schedule operations (recurring jobs)
  *
@@ -375,7 +376,7 @@ declare function useSchedulerTasks(options: UseAgentsOptions): {
  * await pauseSchedule(scheduleId);
  * ```
  */
-declare function useSchedulerSchedules(options: UseAgentsOptions): {
+declare function useSchedulerSchedules(options: UseSchedulerSchedulesOptions): {
     loading: boolean;
     error: string | null;
     listSchedules: (params?: {
@@ -392,4 +393,91 @@ declare function useSchedulerSchedules(options: UseAgentsOptions): {
     runSchedule: (scheduleId: string) => Promise<SchedulerSchedule | null>;
 };
 
-export { type UseAgentsOptions, type UseAsyncOptions, type UseAsyncReturn, type UseWidgetsOptions, useAgentJobs, useAgents, useAnalytics, useApiAsync, useAsync, useIntegrations, useOptionsRef, useSandbox, useSchedulerSchedules, useSchedulerTasks, useSkillUserConfig, useSkills, useSubAgents, useToolDefinitions, useWidgets };
+/** Live state accumulated from SSE events for a single background agent */
+interface BGAgentLiveState {
+    status: "running" | "completed" | "failed";
+    progressLog: string[];
+    latestMessage: string;
+    result?: string;
+    error?: string;
+}
+/** Options for useBackgroundAgents hook */
+interface UseBackgroundAgentsOptions extends ApiClientOptions {
+    /** Chat service URL for SSE streaming (e.g., wss://chat.example.com or https://chat.example.com) */
+    chatServiceUrl?: string;
+    /** User ID (typically email) for chat operations */
+    userId?: string;
+}
+/** Background status reported by the agent via report_status tool */
+type BackgroundStatus = "processing" | "completed" | "failed";
+/** Watched chat state with messages */
+interface WatchedChatState {
+    chatKey: string;
+    messages: ChatMessage[];
+    status: "loading" | "active" | "completed" | "error";
+    /** Background agent status (from report_status tool) */
+    backgroundStatus?: BackgroundStatus;
+    /** Background agent status message (from report_status tool) */
+    backgroundStatusMessage?: string;
+    /** History of all status updates for inline display */
+    statusHistory: AgentStatusUpdate[];
+    title?: string;
+    metadata?: Record<string, unknown>;
+    error?: string;
+}
+/**
+ * Hook for triggering background agents, streaming progress via SSE, and checking status.
+ *
+ * @example
+ * ```tsx
+ * const { startChat, sendMessage } = useChatContext();
+ * const { liveStates, createTask, streamJob, checkStatus } = useBackgroundAgents({
+ *   baseUrl: apiGatewayUrl,
+ *   orgId: selectedOrgId,
+ *   startChat,
+ *   sendMessage,
+ * });
+ *
+ * // Create a background task (simplified flow using chat)
+ * const chatKey = await createTask("Analyze the quarterly report");
+ *
+ * // Or trigger via jobs API (PostgreSQL-backed)
+ * const result = await triggerAgent({ name: "Analysis", prompt: "...", agentName: "Research Agent" });
+ * if (result?.jobId) streamJob(result.jobId);
+ * ```
+ */
+declare function useBackgroundAgents(options: UseBackgroundAgentsOptions): {
+    liveStates: Record<string, BGAgentLiveState>;
+    streamJob: (jobId: string) => void;
+    createTask: (prompt: string, attachments?: Attachment[]) => Promise<string | null>;
+    watchChat: (chatKey: string) => Promise<void>;
+    unwatchChat: (chatKey: string) => void;
+    watchedChats: Record<string, WatchedChatState>;
+    triggerAgent: (request: Pick<TriggerBackgroundAgentRequest, "name" | "prompt" | "agentName" | "context" | "enableSSE" | "description">) => Promise<TriggerBackgroundAgentResponse | null>;
+    checkStatus: (jobId: string) => Promise<BackgroundAgentStatusResponse | null>;
+    listAgentSummaries: () => Promise<AgentSummary[]>;
+    loading: boolean;
+    error: string | null;
+};
+
+/**
+ * Creates a ref that stays synchronized with the provided options.
+ * Useful for accessing current options values in callbacks without
+ * causing re-renders or stale closure issues.
+ *
+ * @param options - The options object to track
+ * @returns A ref that always contains the latest options
+ *
+ * @example
+ * ```tsx
+ * const optionsRef = useOptionsRef(options);
+ *
+ * const fetchData = useCallback(async () => {
+ *   // Always has the latest options, no stale closure
+ *   const result = await api.fetch(optionsRef.current);
+ * }, []); // No need to include options in deps
+ * ```
+ */
+declare function useOptionsRef<T>(options: T): React.MutableRefObject<T>;
+
+export { type BGAgentLiveState, type BackgroundStatus, type UseAgentJobsOptions, type UseAgentsOptions, type UseAnalyticsOptions, type UseBackgroundAgentsOptions, type UseIntegrationsOptions, type UseSandboxOptions, type UseSchedulerSchedulesOptions, type UseSchedulerTasksOptions, type UseSkillUserConfigOptions, type UseSkillsOptions, type UseStructuredOutputOptions, type UseSubAgentsOptions, type UseToolDefinitionsOptions, type UseWidgetsOptions, type WatchedChatState, useAgentJobs, useAgents, useAnalytics, useBackgroundAgents, useIntegrations, useOptionsRef, useSandbox, useSchedulerSchedules, useSchedulerTasks, useSkillUserConfig, useSkills, useStructuredOutput, useSubAgents, useToolDefinitions, useWidgets };