@elqnt/agents 3.6.0 → 4.0.0

package/dist/hooks/index.d.ts

@@ -1,236 +1,357 @@
 import { ApiClientOptions } from '@elqnt/api-client';
-import { A as Agent, aI as AgentSummary, dt as Skill, dW as SubAgent, ei as ToolDefinition, Z as AgentJob, b0 as AgentWidget, dE as SkillUserConfig, dl as ResolveSkillConfigResponse, aB as AgentStatusUpdate, eH as TriggerBackgroundAgentRequest, eI as TriggerBackgroundAgentResponse, bd as BackgroundAgentStatusResponse } from '../agent-models-vL3a7oFB.js';
-export { bb as BackgroundAgentProgressEvent } from '../agent-models-vL3a7oFB.js';
+import { A as Agent, aI as AgentSummary, du as Skill, dX as SubAgent, ej as ToolDefinition, Z as AgentJob, b1 as AgentWidget, dF as SkillUserConfig, dm as ResolveSkillConfigResponse, aB as AgentStatusUpdate, eI as TriggerBackgroundAgentRequest, eJ as TriggerBackgroundAgentResponse, be as BackgroundAgentStatusResponse } from '../agent-models-B-wTMdwF.js';
+export { bc as BackgroundAgentProgressEvent } from '../agent-models-B-wTMdwF.js';
 import { DateFilter, SchedulerTask, SchedulerSchedule } from '../api/index.js';
-import { bb as UserIntegration, ap as IntegrationProviderTS, aA as IntegrationTypeTS, h as CreateSandboxRequest, aX as Sandbox } from '../sandbox-Djb8gA7e.js';
+import { bb as UserIntegration, ap as IntegrationProviderTS, aA as IntegrationTypeTS, aX as Sandbox, h as CreateSandboxRequest } from '../sandbox-Djb8gA7e.js';
 import { a as StructuredOutputRequest, b as StructuredOutputResponse } from '../structured-Bs0IjwLD.js';
-import { ChatMessage, Attachment } from '@elqnt/chat/models';
-export { B as BGAgentTransport, a as BGAgentTransportConfig } from '../types-CuOOCeF8.js';
+import { Attachment, ChatMessage } from '@elqnt/chat/models';
+export { a as BGAgentTransport, c as BGAgentTransportConfig } from '../types-BzNzXaqk.js';
 import '@elqnt/types';
 
 type UseAgentsOptions = ApiClientOptions;
 /**
- * Hook for agent CRUD operations
+ * The exact, stable return surface of `useAgents`.
  *
- * @example
- * ```tsx
- * const { loading, error, listAgents, createAgent } = useAgents({
- *   baseUrl: apiGatewayUrl,
- *   orgId: selectedOrgId,
- * });
+ * This is the agent/consumer **contract**: the only methods that exist on the
+ * agents hook. Every method is imperative and DOES NOT throw — on failure it
+ * resolves to the documented default (`[]`, `null`, `false`) and sets `error`.
  *
- * const agents = await listAgents();
- * ```
+ * `exportAgent` follows the same no-throw contract: it returns the exported
+ * `Agent`, or `null` on failure (with `error` set). As a documented
+ * **side-effect** it also triggers a browser JSON download when an agent is
+ * returned. See `SKILL.md`.
  */
-declare function useAgents(options: UseAgentsOptions): {
+interface UseAgentsReturn {
+    /** OR of all in-flight method loading flags. */
     loading: boolean;
+    /** First non-null method error, else null. */
     error: string | null;
+    /** GET /api/v1/agents — default []. */
     listAgents: () => Promise<Agent[]>;
+    /** GET /api/v1/agents/summary — default []. */
     listAgentSummaries: () => Promise<AgentSummary[]>;
+    /** GET /api/v1/agents/{agentId} — default null. */
     getAgent: (agentId: string) => Promise<Agent | null>;
+    /** POST /api/v1/agents, body Partial<Agent> — created agent, or null on error. */
     createAgent: (agent: Partial<Agent>) => Promise<Agent | null>;
+    /** PUT /api/v1/agents/{agentId}, body Partial<Agent> — updated agent, or null on error. */
     updateAgent: (agentId: string, agent: Partial<Agent>) => Promise<Agent | null>;
+    /** DELETE /api/v1/agents/{agentId} — true on success. */
     deleteAgent: (agentId: string) => Promise<boolean>;
+    /** GET /api/v1/agents/default — default null. */
     getDefaultAgent: () => Promise<Agent | null>;
-    exportAgent: (agentId: string) => Promise<Agent>;
+    /**
+     * GET /api/v1/agents/{agentId}/export — returns the exported Agent, or null
+     * on error (non-throwing). Side-effect: triggers a JSON download when an
+     * agent is returned.
+     */
+    exportAgent: (agentId: string) => Promise<Agent | null>;
+    /** POST /api/v1/agents/import, body Agent — imported agent, or null on error. */
     importAgent: (agent: Agent) => Promise<Agent | null>;
-};
+}
+/**
+ * Hook for agent CRUD operations
+ *
+ * @example
+ * ```tsx
+ * const { loading, error, listAgents, createAgent } = useAgents({
+ *   baseUrl: apiGatewayUrl,
+ *   orgId: selectedOrgId,
+ * });
+ *
+ * const agents = await listAgents();
+ * ```
+ */
+declare function useAgents(options: UseAgentsOptions): UseAgentsReturn;
 
 type UseSkillsOptions = ApiClientOptions;
 /**
- * Hook for skill CRUD operations
+ * The exact, stable return surface of `useSkills` (the standalone catalog
+ * `Skill` CRUD, keyed by name in v2). Imperative, non-throwing — on failure a
+ * method resolves to its default (`[]`, `null`, `false`) and sets `error`.
+ * See `SKILL.md`.
  */
-declare function useSkills(options: UseSkillsOptions): {
+interface UseSkillsReturn {
+    /** OR of all in-flight method loading flags. */
     loading: boolean;
+    /** First non-null method error, else null. */
     error: string | null;
+    /** GET /api/v1/skills — default []. */
     listSkills: () => Promise<Skill[]>;
+    /** GET /api/v1/skills/{skillId} — default null. */
     getSkill: (skillId: string) => Promise<Skill | null>;
+    /** POST /api/v1/skills, body Partial<Skill> — created skill, or null on error. */
     createSkill: (skill: Partial<Skill>) => Promise<Skill | null>;
+    /** PUT /api/v1/skills/{skillId}, body Partial<Skill> — updated skill, or null on error. */
     updateSkill: (skillId: string, skill: Partial<Skill>) => Promise<Skill | null>;
+    /** DELETE /api/v1/skills/{skillId} — true on success. */
     deleteSkill: (skillId: string) => Promise<boolean>;
+    /** GET /api/v1/skills/categories — default []. */
     getCategories: () => Promise<string[]>;
-};
+}
+/**
+ * Hook for skill CRUD operations
+ */
+declare function useSkills(options: UseSkillsOptions): UseSkillsReturn;
 
 type UseSubAgentsOptions = ApiClientOptions;
 /**
- * Hook for sub-agent CRUD operations
+ * The exact, stable return surface of `useSubAgents`. Imperative, non-throwing —
+ * on failure a method resolves to its default (`[]`, `null`, `false`) and sets
+ * `error`. See `SKILL.md`.
  */
-declare function useSubAgents(options: UseSubAgentsOptions): {
+interface UseSubAgentsReturn {
+    /** OR of all in-flight method loading flags. */
     loading: boolean;
+    /** First non-null method error, else null. */
     error: string | null;
+    /** GET /api/v1/subagents — default []. */
     listSubAgents: () => Promise<SubAgent[]>;
+    /** GET /api/v1/subagents/{subAgentId} — default null. */
     getSubAgent: (subAgentId: string) => Promise<SubAgent | null>;
+    /** POST /api/v1/subagents, body { subAgent } — created sub-agent, or null on error. */
     createSubAgent: (subAgent: Partial<SubAgent>) => Promise<SubAgent | null>;
+    /** PUT /api/v1/subagents/{subAgentId}, body { subAgent } — updated sub-agent, or null on error. */
     updateSubAgent: (subAgentId: string, subAgent: Partial<SubAgent>) => Promise<SubAgent | null>;
+    /** DELETE /api/v1/subagents/{subAgentId} — true on success. */
     deleteSubAgent: (subAgentId: string) => Promise<boolean>;
-};
+}
+/**
+ * Hook for sub-agent CRUD operations
+ */
+declare function useSubAgents(options: UseSubAgentsOptions): UseSubAgentsReturn;
 
 type UseToolDefinitionsOptions = ApiClientOptions;
 /**
- * Hook for tool definition CRUD operations
- *
- * @example
- * ```tsx
- * const { loading, error, listToolDefinitions, createToolDefinition } = useToolDefinitions({
- *   baseUrl: apiGatewayUrl,
- *   orgId: selectedOrgId,
- * });
- *
- * const toolDefs = await listToolDefinitions();
- * ```
+ * The exact, stable return surface of `useToolDefinitions` (abstract tool
+ * templates agents customize into `AgentTool`s). Imperative, non-throwing —
+ * on failure a method resolves to its default (`[]`, `null`, `false`) and sets
+ * `error`. See `SKILL.md`.
  */
-declare function useToolDefinitions(options: UseToolDefinitionsOptions): {
+interface UseToolDefinitionsReturn {
+    /** OR of all in-flight method loading flags. */
     loading: boolean;
+    /** First non-null method error, else null. */
     error: string | null;
+    /** GET /api/v1/tool-definitions — default []. */
     listToolDefinitions: () => Promise<ToolDefinition[]>;
+    /** GET /api/v1/tool-definitions/{toolDefId} — default null. */
     getToolDefinition: (toolDefId: string) => Promise<ToolDefinition | null>;
+    /** POST /api/v1/tool-definitions/by-ids, body { ids } — default []. */
     getToolDefinitionsByIds: (ids: string[]) => Promise<ToolDefinition[]>;
+    /** POST /api/v1/tool-definitions, body Partial<ToolDefinition> — created def, or null on error. */
     createToolDefinition: (toolDefinition: Partial<ToolDefinition>) => Promise<ToolDefinition | null>;
+    /** PUT /api/v1/tool-definitions/{toolDefId}, body Partial<ToolDefinition> — updated def, or null on error. */
     updateToolDefinition: (toolDefId: string, toolDefinition: Partial<ToolDefinition>) => Promise<ToolDefinition | null>;
+    /** DELETE /api/v1/tool-definitions/{toolDefId} — true on success. */
     deleteToolDefinition: (toolDefId: string) => Promise<boolean>;
-};
-
-type UseAgentJobsOptions = ApiClientOptions;
+}
 /**
- * Hook for agent job CRUD operations
+ * Hook for tool definition CRUD operations
  *
  * @example
  * ```tsx
- * const { loading, error, listAgentJobs, createAgentJob, pauseAgentJob } = useAgentJobs({
+ * const { loading, error, listToolDefinitions, createToolDefinition } = useToolDefinitions({
  *   baseUrl: apiGatewayUrl,
  *   orgId: selectedOrgId,
  * });
  *
- * const jobs = await listAgentJobs();
- * await pauseAgentJob(jobId);
+ * const toolDefs = await listToolDefinitions();
  * ```
  */
-declare function useAgentJobs(options: UseAgentJobsOptions): {
+declare function useToolDefinitions(options: UseToolDefinitionsOptions): UseToolDefinitionsReturn;
+
+type UseAgentJobsOptions = ApiClientOptions;
+/**
+ * The exact, stable return surface of `useAgentJobs`. Imperative, non-throwing —
+ * on failure each method resolves to the documented default and sets `error`.
+ */
+interface UseAgentJobsReturn {
+    /** OR of all in-flight method loading flags. */
     loading: boolean;
+    /** First non-null method error, else null. */
     error: string | null;
+    /** GET /api/v1/agent-jobs — default []. */
     listAgentJobs: () => Promise<AgentJob[]>;
+    /** GET /api/v1/agent-jobs/{jobId} — default null. */
     getAgentJob: (jobId: string) => Promise<AgentJob | null>;
+    /** POST /api/v1/agent-jobs — created job, or null on error. */
     createAgentJob: (job: Partial<AgentJob>) => Promise<AgentJob | null>;
+    /** PUT /api/v1/agent-jobs/{jobId} — updated job, or null on error. */
     updateAgentJob: (jobId: string, job: Partial<AgentJob>) => Promise<AgentJob | null>;
+    /** DELETE /api/v1/agent-jobs/{jobId} — true on success. */
     deleteAgentJob: (jobId: string) => Promise<boolean>;
+    /** POST /api/v1/agent-jobs/{jobId}/pause — paused job, or null on error. */
     pauseAgentJob: (jobId: string) => Promise<AgentJob | null>;
+    /** POST /api/v1/agent-jobs/{jobId}/resume — resumed job, or null on error. */
     resumeAgentJob: (jobId: string) => Promise<AgentJob | null>;
-};
-
-interface UseWidgetsOptions extends ApiClientOptions {
-    agentId: string;
 }
 /**
- * Hook for widget CRUD operations
+ * Hook for agent job CRUD operations
  *
  * @example
  * ```tsx
- * const { loading, error, listWidgets, createWidget } = useWidgets({
+ * const { loading, error, listAgentJobs, createAgentJob, pauseAgentJob } = useAgentJobs({
  *   baseUrl: apiGatewayUrl,
  *   orgId: selectedOrgId,
- *   agentId: selectedAgentId,
  * });
  *
- * const widgets = await listWidgets();
+ * const jobs = await listAgentJobs();
+ * await pauseAgentJob(jobId);
  * ```
  */
-declare function useWidgets(options: UseWidgetsOptions): {
+declare function useAgentJobs(options: UseAgentJobsOptions): UseAgentJobsReturn;
+
+interface UseWidgetsOptions extends ApiClientOptions {
+    agentId: string;
+}
+/**
+ * The exact, stable return surface of `useWidgets` (chat-widget CRUD for one
+ * agent; the agent is fixed by `options.agentId`). Imperative, non-throwing —
+ * on failure a method resolves to its default (`[]`, `null`, `false`) and sets
+ * `error`. See `SKILL.md`.
+ */
+interface UseWidgetsReturn {
+    /** OR of all in-flight method loading flags. */
     loading: boolean;
+    /** First non-null method error, else null. */
     error: string | null;
+    /** GET /api/v1/agents/{agentId}/widgets — default []. */
     listWidgets: () => Promise<AgentWidget[]>;
+    /** GET /api/v1/widgets/{widgetId} — default null. */
     getWidget: (widgetId: string) => Promise<AgentWidget | null>;
+    /** GET /api/v1/agents/{agentId}/widgets/default — default null. */
     getDefaultWidget: () => Promise<AgentWidget | null>;
+    /** POST /api/v1/agents/{agentId}/widgets, body { widget } — created widget, or null on error. */
     createWidget: (widget: Partial<AgentWidget>) => Promise<AgentWidget | null>;
+    /** PUT /api/v1/widgets/{widgetId}, body { widget } — updated widget, or null on error. */
     updateWidget: (widgetId: string, widget: Partial<AgentWidget>) => Promise<AgentWidget | null>;
+    /** DELETE /api/v1/widgets/{widgetId} — true on success. */
     deleteWidget: (widgetId: string) => Promise<boolean>;
+    /** POST /api/v1/widgets/{widgetId}/default, body { agentId } — true on success. */
     setDefaultWidget: (widgetId: string) => Promise<boolean>;
-};
-
-type UseSkillUserConfigOptions = ApiClientOptions;
+}
 /**
- * Hook for skill user configuration operations
+ * Hook for widget CRUD operations
  *
  * @example
  * ```tsx
- * const { loading, error, getSkillUserConfig, updateSkillUserConfig } = useSkillUserConfig({
+ * const { loading, error, listWidgets, createWidget } = useWidgets({
  *   baseUrl: apiGatewayUrl,
  *   orgId: selectedOrgId,
+ *   agentId: selectedAgentId,
  * });
  *
- * const config = await getSkillUserConfig(skillId);
- * await updateSkillUserConfig(skillId, { enabled: true });
+ * const widgets = await listWidgets();
  * ```
  */
-declare function useSkillUserConfig(options: UseSkillUserConfigOptions): {
+declare function useWidgets(options: UseWidgetsOptions): UseWidgetsReturn;
+
+type UseSkillUserConfigOptions = ApiClientOptions;
+/**
+ * The exact, stable return surface of `useSkillUserConfig`. Imperative,
+ * non-throwing — on failure each method resolves to the documented default
+ * (`null` / `false` / `[]`) and sets `error`.
+ */
+interface UseSkillUserConfigReturn {
+    /** OR of all in-flight method loading flags. */
     loading: boolean;
+    /** First non-null method error, else null. */
     error: string | null;
-    getSkillUserConfig: (skillId: string, agentId?: string | undefined) => Promise<SkillUserConfig | null>;
+    /** GET .../skills/{skillId}/user-config — default null. */
+    getSkillUserConfig: (skillId: string, agentId?: string) => Promise<SkillUserConfig | null>;
+    /** PUT .../skills/{skillId}/user-config — config or null on error. */
     updateSkillUserConfig: (skillId: string, data: {
         enabled?: boolean;
         displayOrder?: number;
         config?: Record<string, unknown>;
         agentId?: string;
     }) => Promise<SkillUserConfig | null>;
-    deleteSkillUserConfig: (skillId: string, agentId?: string | undefined) => Promise<boolean>;
+    /** DELETE .../skills/{skillId}/user-config — true on success. */
+    deleteSkillUserConfig: (skillId: string, agentId?: string) => Promise<boolean>;
+    /** GET .../skills/user-configs — default []. */
     listSkillUserConfigs: (params?: {
         agentId?: string;
         limit?: number;
         offset?: number;
-    } | undefined) => Promise<SkillUserConfig[]>;
+    }) => Promise<SkillUserConfig[]>;
+    /** GET .../skills/{skillId}/resolve — default null. */
     resolveSkillConfig: (skillId: string, agentId: string) => Promise<ResolveSkillConfigResponse | null>;
-};
-
-type UseAnalyticsOptions = ApiClientOptions;
+}
 /**
- * Hook for agent analytics operations
+ * Hook for skill user configuration operations
  *
  * @example
  * ```tsx
- * const { loading, error, getAgentChatsAnalytics, getAgentCSATAnalytics } = useAnalytics({
+ * const { loading, error, getSkillUserConfig, updateSkillUserConfig } = useSkillUserConfig({
  *   baseUrl: apiGatewayUrl,
  *   orgId: selectedOrgId,
  * });
  *
- * const chatsData = await getAgentChatsAnalytics({ from: '2024-01-01', to: '2024-12-31' });
+ * const config = await getSkillUserConfig(skillId);
+ * await updateSkillUserConfig(skillId, { enabled: true });
  * ```
  */
-declare function useAnalytics(options: UseAnalyticsOptions): {
+declare function useSkillUserConfig(options: UseSkillUserConfigOptions): UseSkillUserConfigReturn;
+
+type UseAnalyticsOptions = ApiClientOptions;
+/**
+ * The exact, stable return surface of `useAnalytics`. Imperative, non-throwing —
+ * on failure each method resolves to `[]` and sets `error`.
+ */
+interface UseAnalyticsReturn {
+    /** OR of all in-flight method loading flags. */
     loading: boolean;
+    /** First non-null method error, else null. */
     error: string | null;
+    /** POST /api/v1/agents/analytics/chats — default []. */
     getAgentChatsAnalytics: (params: {
         date_filter: DateFilter;
         agent_id?: string;
     }) => Promise<unknown[]>;
+    /** POST /api/v1/agents/analytics/csat — default []. */
     getAgentCSATAnalytics: (params: {
         date_filter: DateFilter;
         agent_id?: string;
     }) => Promise<unknown[]>;
+    /** GET /api/v1/agents/analytics/list — default []. */
     getAgentListAnalytics: () => Promise<unknown[]>;
+    /** POST /api/v1/agents/analytics/task-outcomes — default []. */
     getTaskOutcomes: (params: {
         date_filter: DateFilter;
     }) => Promise<unknown[]>;
-};
-
-type UseIntegrationsOptions = ApiClientOptions;
+}
 /**
- * Hook for user integration operations (OAuth connections)
+ * Hook for agent analytics operations
  *
  * @example
  * ```tsx
- * const { loading, error, listIntegrations, connectIntegration, disconnectIntegration } = useIntegrations({
+ * const { loading, error, getAgentChatsAnalytics, getAgentCSATAnalytics } = useAnalytics({
  *   baseUrl: apiGatewayUrl,
  *   orgId: selectedOrgId,
  * });
  *
- * const integrations = await listIntegrations();
- * const { auth_url } = await connectIntegration({ provider: 'google', integrationType: 'email', redirectUri: '/callback' });
+ * const chatsData = await getAgentChatsAnalytics({ from: '2024-01-01', to: '2024-12-31' });
  * ```
  */
-declare function useIntegrations(options: UseIntegrationsOptions): {
+declare function useAnalytics(options: UseAnalyticsOptions): UseAnalyticsReturn;
+
+type UseIntegrationsOptions = ApiClientOptions;
+/**
+ * The exact, stable return surface of `useIntegrations`. Imperative,
+ * non-throwing — on failure each method resolves to the documented default
+ * (`[]` / `null` / `false`) and sets `error`.
+ */
+interface UseIntegrationsReturn {
+    /** OR of all in-flight method loading flags. */
     loading: boolean;
+    /** First non-null method error, else null. */
     error: string | null;
+    /** GET /api/v1/integrations — default []. */
     listIntegrations: () => Promise<UserIntegration[]>;
+    /** GET /api/v1/integrations/{provider}/{type} — default null. */
     getIntegration: (provider: IntegrationProviderTS, integrationType: IntegrationTypeTS) => Promise<UserIntegration | null>;
+    /** POST /api/v1/integrations/connect — { authUrl, state } or null on error. */
     connectIntegration: (params: {
         provider: IntegrationProviderTS;
         integrationType: IntegrationTypeTS;
@@ -239,66 +360,110 @@ declare function useIntegrations(options: UseIntegrationsOptions): {
         authUrl: string;
         state: string;
     } | null>;
+    /** POST /api/v1/integrations/disconnect — true on success. */
     disconnectIntegration: (params: {
         provider: IntegrationProviderTS;
         integrationType: IntegrationTypeTS;
     }) => Promise<boolean>;
+    /** POST /api/v1/integrations/refresh — integration or null on error. */
     refreshIntegration: (params: {
         provider: IntegrationProviderTS;
         integrationType: IntegrationTypeTS;
     }) => Promise<UserIntegration | null>;
+    /** POST /api/v1/integrations/triage — integration or null on error. */
     updateTriage: (params: {
         provider: IntegrationProviderTS;
         integrationType: IntegrationTypeTS;
         triageEnabled: boolean;
     }) => Promise<UserIntegration | null>;
+    /** POST /api/v1/integrations/triage/run — { success, emailsFound, instancesCreated } or null on error. */
     runEmailTriage: () => Promise<{
         success: boolean;
         emailsFound: number;
         instancesCreated: number;
     } | null>;
-};
-
-type UseSandboxOptions = ApiClientOptions;
+}
 /**
- * Hook for sandbox operations (AI-generated HTML sandboxes)
+ * Hook for user integration operations (OAuth connections)
  *
  * @example
  * ```tsx
- * const { createSandbox, getSandbox, listSandboxes, loading, error } = useSandbox({
+ * const { loading, error, listIntegrations, connectIntegration, disconnectIntegration } = useIntegrations({
  *   baseUrl: apiGatewayUrl,
  *   orgId: selectedOrgId,
  * });
  *
- * const result = await createSandbox({ prompt: "Create a bar chart showing sales data" });
- * console.log(result.url); // sandbox URL
+ * const integrations = await listIntegrations();
+ * const { auth_url } = await connectIntegration({ provider: 'google', integrationType: 'email', redirectUri: '/callback' });
  * ```
  */
-declare function useSandbox(options: UseSandboxOptions): {
+declare function useIntegrations(options: UseIntegrationsOptions): UseIntegrationsReturn;
+
+type UseSandboxOptions = ApiClientOptions;
+/** Result of a create/update sandbox call (id + url + optional record). */
+interface SandboxMutationResult {
+    id: string;
+    url: string;
+    sandbox?: Sandbox;
+}
+/**
+ * The exact, stable return surface of `useSandbox`. Imperative, non-throwing —
+ * on failure each method resolves to the documented default and sets `error`.
+ */
+interface UseSandboxReturn {
+    /** OR of all in-flight method loading flags. */
     loading: boolean;
+    /** First non-null method error, else null. */
     error: string | null;
-    createSandbox: (request: Omit<CreateSandboxRequest, "orgId">) => Promise<{
-        id: string;
-        url: string;
-        sandbox?: Sandbox;
-    } | null>;
+    /** POST /api/v1/sandboxes — { id, url, sandbox? } or null on error. */
+    createSandbox: (request: Omit<CreateSandboxRequest, "orgId">) => Promise<SandboxMutationResult | null>;
+    /** GET /api/v1/sandboxes/{sandboxId} — default null. */
     getSandbox: (sandboxId: string) => Promise<Sandbox | null>;
+    /** PUT /api/v1/sandboxes/{sandboxId} — { id, url, sandbox? } or null on error. */
     updateSandbox: (sandboxId: string, request: {
         prompt: string;
         title?: string;
-    }) => Promise<{
-        id: string;
-        url: string;
-        sandbox?: Sandbox;
-    } | null>;
-    listSandboxes: (limit?: number | undefined) => Promise<{
+    }) => Promise<SandboxMutationResult | null>;
+    /** GET /api/v1/sandboxes — { sandboxes, total }; default { sandboxes: [], total: 0 }. */
+    listSandboxes: (limit?: number) => Promise<{
         sandboxes: Sandbox[];
         total: number;
     }>;
+    /** DELETE /api/v1/sandboxes/{sandboxId} — true on success. */
     deleteSandbox: (sandboxId: string) => Promise<boolean>;
-};
+}
+/**
+ * Hook for sandbox operations (AI-generated HTML sandboxes)
+ *
+ * @example
+ * ```tsx
+ * const { createSandbox, getSandbox, listSandboxes, loading, error } = useSandbox({
+ *   baseUrl: apiGatewayUrl,
+ *   orgId: selectedOrgId,
+ * });
+ *
+ * const result = await createSandbox({ prompt: "Create a bar chart showing sales data" });
+ * console.log(result.url); // sandbox URL
+ * ```
+ */
+declare function useSandbox(options: UseSandboxOptions): UseSandboxReturn;
 
 type UseStructuredOutputOptions = ApiClientOptions;
+/**
+ * The exact, stable return surface of `useStructuredOutput`. One-shot,
+ * non-throwing — `run` resolves to the structured response, or `null` on
+ * failure (with `error` set).
+ */
+interface UseStructuredOutputReturn<T = unknown> {
+    /** POST /api/v1/structured-output — typed response, or null on error. */
+    run: (request: StructuredOutputRequest) => Promise<StructuredOutputResponse<T> | null>;
+    /** True while a request is in flight. */
+    loading: boolean;
+    /** Last error message, else null. */
+    error: string | null;
+    /** Clears the current error. */
+    clearError: () => void;
+}
 /**
  * Hook for the one-shot structured-output LLM primitive.
  *
@@ -319,79 +484,106 @@ type UseStructuredOutputOptions = ApiClientOptions;
  * });
  * ```
  */
-declare function useStructuredOutput<T = unknown>(options: UseStructuredOutputOptions): {
-    run: (request: StructuredOutputRequest) => Promise<StructuredOutputResponse<T> | null>;
-    loading: boolean;
-    error: string | null;
-    clearError: () => void;
-};
+declare function useStructuredOutput<T = unknown>(options: UseStructuredOutputOptions): UseStructuredOutputReturn<T>;
 
 type UseSchedulerTasksOptions = ApiClientOptions;
 /**
- * Hook for scheduler task operations
- *
- * @example
- * ```tsx
- * const { listTasks, createTask, snoozeTask, loading, error } = useSchedulerTasks({
- *   baseUrl: apiGatewayUrl,
- *   orgId: selectedOrgId,
- * });
- *
- * const tasks = await listTasks();
- * await snoozeTask(taskId, { amount: 30, unit: "minutes" });
- * ```
+ * The exact, stable return surface of `useSchedulerTasks`. Imperative,
+ * non-throwing — on failure each method resolves to the documented default
+ * (`[]` / `null` / `false`) and sets `error`.
  */
-declare function useSchedulerTasks(options: UseSchedulerTasksOptions): {
+interface UseSchedulerTasksReturn {
+    /** OR of all in-flight method loading flags. */
     loading: boolean;
+    /** First non-null method error, else null. */
     error: string | null;
+    /** GET /api/v1/scheduler/tasks — default []. */
     listTasks: (params?: {
         status?: string;
         limit?: number;
         offset?: number;
-    } | undefined) => Promise<SchedulerTask[]>;
+    }) => Promise<SchedulerTask[]>;
+    /** POST /api/v1/scheduler/tasks — created task, or null on error. */
     createTask: (task: Partial<SchedulerTask>) => Promise<SchedulerTask | null>;
+    /** GET /api/v1/scheduler/tasks/{taskId} — default null. */
     getTask: (taskId: string) => Promise<SchedulerTask | null>;
+    /** PUT /api/v1/scheduler/tasks/{taskId} — updated task, or null on error. */
     updateTask: (taskId: string, task: Partial<SchedulerTask>) => Promise<SchedulerTask | null>;
+    /** DELETE /api/v1/scheduler/tasks/{taskId} — true on success. */
     deleteTask: (taskId: string) => Promise<boolean>;
+    /** POST /api/v1/scheduler/tasks/{taskId}/snooze — task or null on error. */
     snoozeTask: (taskId: string, delay: {
         amount: number;
         unit: string;
     }) => Promise<SchedulerTask | null>;
+    /** POST /api/v1/scheduler/tasks/{taskId}/complete — task or null on error. */
     completeTask: (taskId: string) => Promise<SchedulerTask | null>;
+    /** POST /api/v1/scheduler/tasks/{taskId}/start — task or null on error. */
     startTask: (taskId: string) => Promise<SchedulerTask | null>;
-};
-
-type UseSchedulerSchedulesOptions = ApiClientOptions;
+}
 /**
- * Hook for scheduler schedule operations (recurring jobs)
+ * Hook for scheduler task operations
  *
  * @example
  * ```tsx
- * const { listSchedules, createSchedule, pauseSchedule, loading, error } = useSchedulerSchedules({
+ * const { listTasks, createTask, snoozeTask, loading, error } = useSchedulerTasks({
  *   baseUrl: apiGatewayUrl,
  *   orgId: selectedOrgId,
  * });
  *
- * const schedules = await listSchedules();
- * await pauseSchedule(scheduleId);
+ * const tasks = await listTasks();
+ * await snoozeTask(taskId, { amount: 30, unit: "minutes" });
  * ```
  */
-declare function useSchedulerSchedules(options: UseSchedulerSchedulesOptions): {
+declare function useSchedulerTasks(options: UseSchedulerTasksOptions): UseSchedulerTasksReturn;
+
+type UseSchedulerSchedulesOptions = ApiClientOptions;
+/**
+ * The exact, stable return surface of `useSchedulerSchedules`. Imperative,
+ * non-throwing — on failure each method resolves to the documented default
+ * (`[]` / `null` / `false`) and sets `error`.
+ */
+interface UseSchedulerSchedulesReturn {
+    /** OR of all in-flight method loading flags. */
     loading: boolean;
+    /** First non-null method error, else null. */
     error: string | null;
+    /** GET /api/v1/scheduler/schedules — default []. */
     listSchedules: (params?: {
         status?: string;
         limit?: number;
         offset?: number;
-    } | undefined) => Promise<SchedulerSchedule[]>;
+    }) => Promise<SchedulerSchedule[]>;
+    /** POST /api/v1/scheduler/schedules — created schedule, or null on error. */
     createSchedule: (schedule: Partial<SchedulerSchedule>) => Promise<SchedulerSchedule | null>;
+    /** GET /api/v1/scheduler/schedules/{scheduleId} — default null. */
     getSchedule: (scheduleId: string) => Promise<SchedulerSchedule | null>;
+    /** PUT /api/v1/scheduler/schedules/{scheduleId} — updated schedule, or null on error. */
     updateSchedule: (scheduleId: string, schedule: Partial<SchedulerSchedule>) => Promise<SchedulerSchedule | null>;
+    /** DELETE /api/v1/scheduler/schedules/{scheduleId} — true on success. */
     deleteSchedule: (scheduleId: string) => Promise<boolean>;
+    /** POST /api/v1/scheduler/schedules/{scheduleId}/pause — schedule or null on error. */
     pauseSchedule: (scheduleId: string) => Promise<SchedulerSchedule | null>;
+    /** POST /api/v1/scheduler/schedules/{scheduleId}/resume — schedule or null on error. */
     resumeSchedule: (scheduleId: string) => Promise<SchedulerSchedule | null>;
+    /** POST /api/v1/scheduler/schedules/{scheduleId}/run — schedule or null on error. */
     runSchedule: (scheduleId: string) => Promise<SchedulerSchedule | null>;
-};
+}
+/**
+ * Hook for scheduler schedule operations (recurring jobs)
+ *
+ * @example
+ * ```tsx
+ * const { listSchedules, createSchedule, pauseSchedule, loading, error } = useSchedulerSchedules({
+ *   baseUrl: apiGatewayUrl,
+ *   orgId: selectedOrgId,
+ * });
+ *
+ * const schedules = await listSchedules();
+ * await pauseSchedule(scheduleId);
+ * ```
+ */
+declare function useSchedulerSchedules(options: UseSchedulerSchedulesOptions): UseSchedulerSchedulesReturn;
 
 /** Live state accumulated from SSE events for a single background agent */
 interface BGAgentLiveState {
@@ -425,6 +617,38 @@ interface WatchedChatState {
     metadata?: Record<string, unknown>;
     error?: string;
 }
+/**
+ * The exact, stable return surface of `useBackgroundAgents`.
+ *
+ * This is a **realtime** hook (the allowed shape deviation): it holds SSE
+ * connection/stream state (`liveStates`, `watchedChats`) alongside the standard
+ * `{ loading, error, ...actions }`. The imperative methods are non-throwing — on
+ * failure they resolve to the documented default and set `error` (or log).
+ */
+interface UseBackgroundAgentsReturn {
+    /** Live SSE-accumulated state per streamed jobId. */
+    liveStates: Record<string, BGAgentLiveState>;
+    /** Open an SSE stream for a job's progress (job runs via the jobs API). */
+    streamJob: (jobId: string) => void;
+    /** Create a background task via the chat system — returns chatKey, or null on error. */
+    createTask: (prompt: string, attachments?: Attachment[]) => Promise<string | null>;
+    /** Watch a chat for realtime updates via SSE. */
+    watchChat: (chatKey: string) => Promise<void>;
+    /** Stop watching a chat and tear down its SSE connection. */
+    unwatchChat: (chatKey: string) => void;
+    /** Live state per watched chatKey. */
+    watchedChats: Record<string, WatchedChatState>;
+    /** POST /api/v1/agents/background/trigger — response, or null on error. */
+    triggerAgent: (request: Pick<TriggerBackgroundAgentRequest, "name" | "prompt" | "agentName" | "context" | "enableSSE" | "description">) => Promise<TriggerBackgroundAgentResponse | null>;
+    /** GET /api/v1/agents/background/{jobId}/status — response, or null on error. */
+    checkStatus: (jobId: string) => Promise<BackgroundAgentStatusResponse | null>;
+    /** GET /api/v1/agents/summary — default []. */
+    listAgentSummaries: () => Promise<AgentSummary[]>;
+    /** OR of the imperative methods' in-flight loading flags. */
+    loading: boolean;
+    /** First non-null imperative-method error, else null. */
+    error: string | null;
+}
 /**
  * Hook for triggering background agents, streaming progress via SSE, and checking status.
  *
@@ -446,19 +670,7 @@ interface WatchedChatState {
  * 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" | "description" | "prompt" | "agentName" | "context" | "enableSSE">) => Promise<TriggerBackgroundAgentResponse | null>;
-    checkStatus: (jobId: string) => Promise<BackgroundAgentStatusResponse | null>;
-    listAgentSummaries: () => Promise<AgentSummary[]>;
-    loading: boolean;
-    error: string | null;
-};
+declare function useBackgroundAgents(options: UseBackgroundAgentsOptions): UseBackgroundAgentsReturn;
 
 /**
  * Creates a ref that stays synchronized with the provided options.
@@ -480,4 +692,4 @@ declare function useBackgroundAgents(options: UseBackgroundAgentsOptions): {
  */
 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 };
+export { type BGAgentLiveState, type BackgroundStatus, type SandboxMutationResult, type UseAgentJobsOptions, type UseAgentJobsReturn, type UseAgentsOptions, type UseAgentsReturn, type UseAnalyticsOptions, type UseAnalyticsReturn, type UseBackgroundAgentsOptions, type UseBackgroundAgentsReturn, type UseIntegrationsOptions, type UseIntegrationsReturn, type UseSandboxOptions, type UseSandboxReturn, type UseSchedulerSchedulesOptions, type UseSchedulerSchedulesReturn, type UseSchedulerTasksOptions, type UseSchedulerTasksReturn, type UseSkillUserConfigOptions, type UseSkillUserConfigReturn, type UseSkillsOptions, type UseSkillsReturn, type UseStructuredOutputOptions, type UseStructuredOutputReturn, type UseSubAgentsOptions, type UseSubAgentsReturn, type UseToolDefinitionsOptions, type UseToolDefinitionsReturn, type UseWidgetsOptions, type UseWidgetsReturn, type WatchedChatState, useAgentJobs, useAgents, useAnalytics, useBackgroundAgents, useIntegrations, useOptionsRef, useSandbox, useSchedulerSchedules, useSchedulerTasks, useSkillUserConfig, useSkills, useStructuredOutput, useSubAgents, useToolDefinitions, useWidgets };