@exulu/backend 1.69.3 → 2.0.0

package/dist/index.d.cts

@@ -157,7 +157,7 @@ interface ExuluAgent {
         config: {
             name: string;
             variable: string;
-            type: "boolean" | "string" | "number" | "variable";
+            type: "boolean" | "string" | "number" | "variable" | "json";
         }[];
         name: string;
         description: string;
@@ -222,16 +222,25 @@ interface Item {
 /**
  * OAuth 2.0 configuration for an {@link ExuluTool}. When a tool is constructed
  * with an `oauth` property, Exulu wraps its `execute` so it only runs when a
- * valid access token exists for the calling (toolId, userId) pair. When no
- * valid token exists the tool short-circuits and returns an authorization URL
- * the agent can show the user; the generic /oauth/callback route completes the
- * flow and persists the tokens.
+ * valid access token exists for the calling (providerKey, userId) pair — where
+ * providerKey defaults to the tool's id but can be shared across tools by
+ * setting the "provider" field below. When no valid token exists the tool
+ * short-circuits and returns an authorization URL the agent can show the user;
+ * the generic /oauth/callback route completes the flow and persists the tokens.
  *
  * Only the standard authorization-code grant is supported. All values are
  * declared in code (source them from env vars or however you like) — none of
  * them are exposed as admin-configurable tool config.
  */
 type ExuluOauthConfig = {
+    /**
+     * Identifier for the OAuth provider (e.g., "google", "jira", "github").
+     * Tools sharing the same provider share tokens under (provider, userId) —
+     * one consent screen per provider per user instead of per tool. When
+     * omitted, defaults to the tool's `id`, preserving per-tool behavior for
+     * tools that don't opt in.
+     */
+    provider?: string;
     /** The provider's authorization endpoint, e.g. https://app.hubspot.com/oauth/authorize */
     authorizationUrl: string;
     /** The provider's token endpoint, e.g. https://api.hubapi.com/oauth/v1/token */
@@ -275,8 +284,8 @@ declare class ExuluTool {
     config: {
         name: string;
         description: string;
-        type: "boolean" | "string" | "number" | "variable";
-        default?: string | boolean | number;
+        type: "boolean" | "string" | "number" | "variable" | "json";
+        default?: string | boolean | number | object;
     }[];
     constructor({ id, name, description, category, inputSchema, type, execute, config, needsApproval, oauth, }: {
         id: string;
@@ -288,8 +297,8 @@ declare class ExuluTool {
         config: {
             name: string;
             description: string;
-            type: "boolean" | "string" | "number" | "variable";
-            default?: string | boolean | number;
+            type: "boolean" | "string" | "number" | "variable" | "json";
+            default?: string | boolean | number | object;
         }[];
         needsApproval?: boolean;
         oauth?: ExuluOauthConfig;
@@ -903,10 +912,10 @@ type ExuluAgentToolConfig = {
     type: string;
     config: {
         name: string;
-        variable: string | boolean | number;
-        type: "boolean" | "string" | "number" | "variable";
+        variable: string | boolean | number | object;
+        type: "boolean" | "string" | "number" | "variable" | "json";
         value?: any;
-        default?: string | boolean | number;
+        default?: string | boolean | number | object;
     }[];
 };
 
@@ -1227,10 +1236,6 @@ declare class ExuluQueues {
 }
 declare const queues: ExuluQueues;
 
-declare const trajectoryRegistry: {
-    lastFile: string | undefined;
-};
-
 /**
  * Represents the data structure for a chunk object.
  *
@@ -1855,6 +1860,26 @@ declare function postgresClient(): Promise<{
     db: Knex;
 }>;
 
+/**
+ * Switch this process into LiteLLM *client* mode: it connects to an
+ * externally-managed proxy (spawned by the Exulu HTTP server process, or a
+ * standalone proxy) rather than spawning and supervising its own.
+ *
+ * This is the correct mode for worker processes. The supervisor's `internal`
+ * state is per-process; a worker runs as a separate Node process from the
+ * server and never goes through express.init() (where the supervisor is
+ * started), so without this it would try to spawn its own proxy — colliding
+ * with the server's on LITELLM_PORT — or, lacking a package root, fail with
+ * "package root not set" even though a healthy proxy is already running.
+ *
+ * No-op if this process has already started its own supervisor (e.g. a
+ * combined server+worker process): that process owns a proxy and keeps using
+ * it. Idempotent. Readiness is resolved lazily by waitForLiteLLMReady() via a
+ * health probe, so this never blocks boot and tolerates the proxy coming up
+ * after the worker.
+ */
+declare const enableLiteLLMClientMode: () => void;
+
 /**
  * Represents the essential data for a sentence within a text.
  *
@@ -2447,23 +2472,15 @@ declare function rerank<T extends RerankableChunk>(input: ExuluRerankInput<T>):
     rerank_score: number;
 })[]>;
 
-/**
- * Creates the v3 ExuluTool for agentic context retrieval.
- *
- * Compared to v2:
- * - Single LLM call per step (vs two in v2)
- * - Query classification upfront → strategy-based step budget (1–3 vs hardcoded 2)
- * - Context example records sampled at init and cached
- * - Strategy-specific instructions and tool sets
- */
-declare function createAgenticRetrievalToolV3({ contexts, instructions: adminInstructions, user, role, model, preselected, memoryItems }: {
+declare function createAgenticRetrievalTool(opts: {
     contexts: ExuluContext[];
+    memoryContext?: ExuluContext;
     user?: User;
     role?: string;
     model?: LanguageModel;
     instructions?: string;
     preselected?: string[];
-    memoryItems?: Item[];
+    memoryItems?: VectorSearchChunkResult[];
 }): ExuluTool | undefined;
 
 type JOB_STATUS = "completed" | "failed" | "delayed" | "active" | "waiting" | "paused" | "stuck";
@@ -2484,7 +2501,7 @@ declare const ExuluDefaultTools: {
     agentic: {
         retrieval: {
             create: {
-                v3: typeof createAgenticRetrievalToolV3;
+                pipeline: typeof createAgenticRetrievalTool;
             };
         };
     };
@@ -2580,4 +2597,4 @@ declare const ExuluPython: {
     instructions: typeof getPythonSetupInstructions;
 };
 
-export { type ChunkerOperation, type ChunkerResponse, type JOB_STATUS as EXULU_JOB_STATUS, JOB_STATUS_ENUM as EXULU_JOB_STATUS_ENUM, type STATISTICS_TYPE as EXULU_STATISTICS_TYPE, STATISTICS_TYPE_ENUM as EXULU_STATISTICS_TYPE_ENUM, type ExuluAgent, ExuluApp, ExuluAuthentication, ExuluChunkers, ExuluContext, type ExuluContextEmbedder, ExuluDatabase, ExuluDefaultProviders, ExuluDefaultTools, ExuluDocumentProcessor, ExuluEval, type Item as ExuluItem, ExuluJobs, type ExuluOauthConfig, type ExuluOauthToolContext, ExuluOtel, ExuluProvider, ExuluPython, queues as ExuluQueues, ExuluReadApi, ExuluReranker, ExuluTool, trajectoryRegistry as ExuluTrajectoryRegistry, ExuluVariables, type VectorSearchChunkResult, defaultChunker, postgresClient };
+export { type ChunkerOperation, type ChunkerResponse, type JOB_STATUS as EXULU_JOB_STATUS, JOB_STATUS_ENUM as EXULU_JOB_STATUS_ENUM, type STATISTICS_TYPE as EXULU_STATISTICS_TYPE, STATISTICS_TYPE_ENUM as EXULU_STATISTICS_TYPE_ENUM, type ExuluAgent, ExuluApp, ExuluAuthentication, ExuluChunkers, ExuluContext, type ExuluContextEmbedder, ExuluDatabase, ExuluDefaultProviders, ExuluDefaultTools, ExuluDocumentProcessor, ExuluEval, type Item as ExuluItem, ExuluJobs, type ExuluOauthConfig, type ExuluOauthToolContext, ExuluOtel, ExuluProvider, ExuluPython, queues as ExuluQueues, ExuluReadApi, ExuluReranker, ExuluTool, ExuluVariables, type VectorSearchChunkResult, defaultChunker, enableLiteLLMClientMode, postgresClient };

package/dist/index.d.ts

@@ -157,7 +157,7 @@ interface ExuluAgent {
         config: {
             name: string;
             variable: string;
-            type: "boolean" | "string" | "number" | "variable";
+            type: "boolean" | "string" | "number" | "variable" | "json";
         }[];
         name: string;
         description: string;
@@ -222,16 +222,25 @@ interface Item {
 /**
  * OAuth 2.0 configuration for an {@link ExuluTool}. When a tool is constructed
  * with an `oauth` property, Exulu wraps its `execute` so it only runs when a
- * valid access token exists for the calling (toolId, userId) pair. When no
- * valid token exists the tool short-circuits and returns an authorization URL
- * the agent can show the user; the generic /oauth/callback route completes the
- * flow and persists the tokens.
+ * valid access token exists for the calling (providerKey, userId) pair — where
+ * providerKey defaults to the tool's id but can be shared across tools by
+ * setting the "provider" field below. When no valid token exists the tool
+ * short-circuits and returns an authorization URL the agent can show the user;
+ * the generic /oauth/callback route completes the flow and persists the tokens.
  *
  * Only the standard authorization-code grant is supported. All values are
  * declared in code (source them from env vars or however you like) — none of
  * them are exposed as admin-configurable tool config.
  */
 type ExuluOauthConfig = {
+    /**
+     * Identifier for the OAuth provider (e.g., "google", "jira", "github").
+     * Tools sharing the same provider share tokens under (provider, userId) —
+     * one consent screen per provider per user instead of per tool. When
+     * omitted, defaults to the tool's `id`, preserving per-tool behavior for
+     * tools that don't opt in.
+     */
+    provider?: string;
     /** The provider's authorization endpoint, e.g. https://app.hubspot.com/oauth/authorize */
     authorizationUrl: string;
     /** The provider's token endpoint, e.g. https://api.hubapi.com/oauth/v1/token */
@@ -275,8 +284,8 @@ declare class ExuluTool {
     config: {
         name: string;
         description: string;
-        type: "boolean" | "string" | "number" | "variable";
-        default?: string | boolean | number;
+        type: "boolean" | "string" | "number" | "variable" | "json";
+        default?: string | boolean | number | object;
     }[];
     constructor({ id, name, description, category, inputSchema, type, execute, config, needsApproval, oauth, }: {
         id: string;
@@ -288,8 +297,8 @@ declare class ExuluTool {
         config: {
             name: string;
             description: string;
-            type: "boolean" | "string" | "number" | "variable";
-            default?: string | boolean | number;
+            type: "boolean" | "string" | "number" | "variable" | "json";
+            default?: string | boolean | number | object;
         }[];
         needsApproval?: boolean;
         oauth?: ExuluOauthConfig;
@@ -903,10 +912,10 @@ type ExuluAgentToolConfig = {
     type: string;
     config: {
         name: string;
-        variable: string | boolean | number;
-        type: "boolean" | "string" | "number" | "variable";
+        variable: string | boolean | number | object;
+        type: "boolean" | "string" | "number" | "variable" | "json";
         value?: any;
-        default?: string | boolean | number;
+        default?: string | boolean | number | object;
     }[];
 };
 
@@ -1227,10 +1236,6 @@ declare class ExuluQueues {
 }
 declare const queues: ExuluQueues;
 
-declare const trajectoryRegistry: {
-    lastFile: string | undefined;
-};
-
 /**
  * Represents the data structure for a chunk object.
  *
@@ -1855,6 +1860,26 @@ declare function postgresClient(): Promise<{
     db: Knex;
 }>;
 
+/**
+ * Switch this process into LiteLLM *client* mode: it connects to an
+ * externally-managed proxy (spawned by the Exulu HTTP server process, or a
+ * standalone proxy) rather than spawning and supervising its own.
+ *
+ * This is the correct mode for worker processes. The supervisor's `internal`
+ * state is per-process; a worker runs as a separate Node process from the
+ * server and never goes through express.init() (where the supervisor is
+ * started), so without this it would try to spawn its own proxy — colliding
+ * with the server's on LITELLM_PORT — or, lacking a package root, fail with
+ * "package root not set" even though a healthy proxy is already running.
+ *
+ * No-op if this process has already started its own supervisor (e.g. a
+ * combined server+worker process): that process owns a proxy and keeps using
+ * it. Idempotent. Readiness is resolved lazily by waitForLiteLLMReady() via a
+ * health probe, so this never blocks boot and tolerates the proxy coming up
+ * after the worker.
+ */
+declare const enableLiteLLMClientMode: () => void;
+
 /**
  * Represents the essential data for a sentence within a text.
  *
@@ -2447,23 +2472,15 @@ declare function rerank<T extends RerankableChunk>(input: ExuluRerankInput<T>):
     rerank_score: number;
 })[]>;
 
-/**
- * Creates the v3 ExuluTool for agentic context retrieval.
- *
- * Compared to v2:
- * - Single LLM call per step (vs two in v2)
- * - Query classification upfront → strategy-based step budget (1–3 vs hardcoded 2)
- * - Context example records sampled at init and cached
- * - Strategy-specific instructions and tool sets
- */
-declare function createAgenticRetrievalToolV3({ contexts, instructions: adminInstructions, user, role, model, preselected, memoryItems }: {
+declare function createAgenticRetrievalTool(opts: {
     contexts: ExuluContext[];
+    memoryContext?: ExuluContext;
     user?: User;
     role?: string;
     model?: LanguageModel;
     instructions?: string;
     preselected?: string[];
-    memoryItems?: Item[];
+    memoryItems?: VectorSearchChunkResult[];
 }): ExuluTool | undefined;
 
 type JOB_STATUS = "completed" | "failed" | "delayed" | "active" | "waiting" | "paused" | "stuck";
@@ -2484,7 +2501,7 @@ declare const ExuluDefaultTools: {
     agentic: {
         retrieval: {
             create: {
-                v3: typeof createAgenticRetrievalToolV3;
+                pipeline: typeof createAgenticRetrievalTool;
             };
         };
     };
@@ -2580,4 +2597,4 @@ declare const ExuluPython: {
     instructions: typeof getPythonSetupInstructions;
 };
 
-export { type ChunkerOperation, type ChunkerResponse, type JOB_STATUS as EXULU_JOB_STATUS, JOB_STATUS_ENUM as EXULU_JOB_STATUS_ENUM, type STATISTICS_TYPE as EXULU_STATISTICS_TYPE, STATISTICS_TYPE_ENUM as EXULU_STATISTICS_TYPE_ENUM, type ExuluAgent, ExuluApp, ExuluAuthentication, ExuluChunkers, ExuluContext, type ExuluContextEmbedder, ExuluDatabase, ExuluDefaultProviders, ExuluDefaultTools, ExuluDocumentProcessor, ExuluEval, type Item as ExuluItem, ExuluJobs, type ExuluOauthConfig, type ExuluOauthToolContext, ExuluOtel, ExuluProvider, ExuluPython, queues as ExuluQueues, ExuluReadApi, ExuluReranker, ExuluTool, trajectoryRegistry as ExuluTrajectoryRegistry, ExuluVariables, type VectorSearchChunkResult, defaultChunker, postgresClient };
+export { type ChunkerOperation, type ChunkerResponse, type JOB_STATUS as EXULU_JOB_STATUS, JOB_STATUS_ENUM as EXULU_JOB_STATUS_ENUM, type STATISTICS_TYPE as EXULU_STATISTICS_TYPE, STATISTICS_TYPE_ENUM as EXULU_STATISTICS_TYPE_ENUM, type ExuluAgent, ExuluApp, ExuluAuthentication, ExuluChunkers, ExuluContext, type ExuluContextEmbedder, ExuluDatabase, ExuluDefaultProviders, ExuluDefaultTools, ExuluDocumentProcessor, ExuluEval, type Item as ExuluItem, ExuluJobs, type ExuluOauthConfig, type ExuluOauthToolContext, ExuluOtel, ExuluProvider, ExuluPython, queues as ExuluQueues, ExuluReadApi, ExuluReranker, ExuluTool, ExuluVariables, type VectorSearchChunkResult, defaultChunker, enableLiteLLMClientMode, postgresClient };