@distri/core 0.3.1 → 0.3.3

package/dist/index.js

@@ -29,6 +29,7 @@ __export(index_exports, {
   DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
   DistriClient: () => DistriClient,
   DistriError: () => DistriError,
+  ExternalToolValidationError: () => ExternalToolValidationError,
   convertA2AMessageToDistri: () => convertA2AMessageToDistri,
   convertA2APartToDistri: () => convertA2APartToDistri,
   convertA2AStatusUpdateToDistri: () => convertA2AStatusUpdateToDistri,
@@ -729,6 +730,17 @@ function convertA2AStatusUpdateToDistri(statusUpdate) {
       };
       return hookRequested;
     }
+    case "browser_session_started": {
+      const browserSessionStarted = {
+        type: "browser_session_started",
+        data: {
+          session_id: metadata.session_id || "",
+          viewer_url: metadata.viewer_url,
+          stream_url: metadata.stream_url
+        }
+      };
+      return browserSessionStarted;
+    }
     default: {
       console.warn(`Unhandled status update metadata type: ${metadata.type}`, metadata);
       const defaultResult = {
@@ -807,6 +819,7 @@ function convertDistriMessageToA2A(distriMessage, context) {
       break;
     case "system":
     case "tool":
+    case "developer":
       role = "user";
       break;
     default:
@@ -903,26 +916,56 @@ var _DistriClient = class _DistriClient {
   constructor(config) {
     this.agentClients = /* @__PURE__ */ new Map();
     const headers = { ...config.headers };
+    if (config.workspaceId) {
+      headers["X-Workspace-Id"] = config.workspaceId;
+    }
     this.accessToken = config.accessToken;
     this.refreshToken = config.refreshToken;
     this.tokenRefreshSkewMs = config.tokenRefreshSkewMs ?? 6e4;
     this.onTokenRefresh = config.onTokenRefresh;
     this.config = {
-      baseUrl: config.baseUrl.replace(/\/$/, ""),
+      baseUrl: config.baseUrl?.replace(/\/$/, "") || DEFAULT_BASE_URL,
       apiVersion: config.apiVersion || "v1",
-      timeout: config.timeout || 3e4,
-      retryAttempts: config.retryAttempts || 3,
-      retryDelay: config.retryDelay || 1e3,
-      debug: config.debug || false,
+      timeout: config.timeout ?? 3e4,
+      retryAttempts: config.retryAttempts ?? 3,
+      retryDelay: config.retryDelay ?? 1e3,
+      debug: config.debug ?? false,
       headers,
-      interceptor: config.interceptor || ((init) => Promise.resolve(init))
+      interceptor: config.interceptor ?? (async (init) => Promise.resolve(init)),
+      onTokenRefresh: config.onTokenRefresh,
+      clientId: config.clientId,
+      workspaceId: config.workspaceId
     };
-    this.debug("DistriClient initialized with config:", {
-      baseUrl: this.config.baseUrl,
-      hasAccessToken: !!this.accessToken,
-      hasRefreshToken: !!this.refreshToken,
-      timeout: this.config.timeout
-    });
+  }
+  /**
+   * Get the configured client ID.
+   */
+  get clientId() {
+    return this.config.clientId;
+  }
+  /**
+   * Set the client ID for embed token issuance.
+   */
+  set clientId(value) {
+    this.config.clientId = value;
+  }
+  /**
+   * Get the configured workspace ID.
+   */
+  get workspaceId() {
+    return this.config.workspaceId;
+  }
+  /**
+   * Set the workspace ID for multi-tenant support.
+   * Updates the X-Workspace-Id header for all subsequent requests.
+   */
+  set workspaceId(value) {
+    this.config.workspaceId = value;
+    if (value) {
+      this.config.headers["X-Workspace-Id"] = value;
+    } else {
+      delete this.config.headers["X-Workspace-Id"];
+    }
   }
   /**
    * Create a client with default cloud configuration.
@@ -955,7 +998,7 @@ var _DistriClient = class _DistriClient {
     if (expiry) {
       body.expiry = typeof expiry === "string" ? expiry : expiry.toISOString();
     }
-    const resp = await this.fetch(`/session/${encodeURIComponent(sessionId)}/values`, {
+    const resp = await this.fetch(`/sessions/${encodeURIComponent(sessionId)}/values`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
@@ -972,7 +1015,7 @@ var _DistriClient = class _DistriClient {
    * Session store: get a single value
    */
   async getSessionValue(sessionId, key) {
-    const resp = await this.fetch(`/session/${encodeURIComponent(sessionId)}/values/${encodeURIComponent(key)}`, {
+    const resp = await this.fetch(`/sessions/${encodeURIComponent(sessionId)}/values/${encodeURIComponent(key)}`, {
       method: "GET",
       headers: {
         ...this.config.headers
@@ -989,7 +1032,7 @@ var _DistriClient = class _DistriClient {
    * Session store: get all values in a session
    */
   async getSessionValues(sessionId) {
-    const resp = await this.fetch(`/session/${encodeURIComponent(sessionId)}/values`, {
+    const resp = await this.fetch(`/sessions/${encodeURIComponent(sessionId)}/values`, {
       method: "GET",
       headers: {
         ...this.config.headers
@@ -1006,7 +1049,7 @@ var _DistriClient = class _DistriClient {
    * Session store: delete a single key
    */
   async deleteSessionValue(sessionId, key) {
-    const resp = await this.fetch(`/session/${encodeURIComponent(sessionId)}/values/${encodeURIComponent(key)}`, {
+    const resp = await this.fetch(`/sessions/${encodeURIComponent(sessionId)}/values/${encodeURIComponent(key)}`, {
       method: "DELETE",
       headers: {
         ...this.config.headers
@@ -1021,7 +1064,7 @@ var _DistriClient = class _DistriClient {
    * Session store: clear all keys in a session
    */
   async clearSession(sessionId) {
-    const resp = await this.fetch(`/session/${encodeURIComponent(sessionId)}`, {
+    const resp = await this.fetch(`/sessions/${encodeURIComponent(sessionId)}`, {
       method: "DELETE",
       headers: {
         ...this.config.headers
@@ -1032,30 +1075,6 @@ var _DistriClient = class _DistriClient {
       throw new ApiError(errorData.error || "Failed to clear session", resp.status);
     }
   }
-  /**
-   * Set additional user message parts for the next agent iteration.
-   * These parts will be appended to the user message in the prompt.
-   * @param sessionId - The thread/session ID
-   * @param parts - Array of DistriPart objects to append to user message
-   */
-  async setAdditionalUserParts(sessionId, parts) {
-    await this.setSessionValue(sessionId, _DistriClient.ADDITIONAL_PARTS_KEY, parts);
-  }
-  /**
-   * Get the current additional user message parts.
-   * @param sessionId - The thread/session ID
-   * @returns Array of DistriPart objects or null if not set
-   */
-  async getAdditionalUserParts(sessionId) {
-    return this.getSessionValue(sessionId, _DistriClient.ADDITIONAL_PARTS_KEY);
-  }
-  /**
-   * Clear/delete the additional user message parts.
-   * @param sessionId - The thread/session ID
-   */
-  async clearAdditionalUserParts(sessionId) {
-    await this.deleteSessionValue(sessionId, _DistriClient.ADDITIONAL_PARTS_KEY);
-  }
   /**
    * Issue an access token + refresh token for temporary authentication.
    * Requires an existing authenticated session (bearer token).
@@ -1085,7 +1104,7 @@ var _DistriClient = class _DistriClient {
     if (!tokens?.access_token || !tokens?.refresh_token || typeof tokens?.expires_at !== "number") {
       throw new ApiError("Invalid token response", response.status);
     }
-    this.applyTokens(tokens.access_token, tokens.refresh_token, false);
+    this.applyTokens(tokens.access_token, tokens.refresh_token);
     return tokens;
   }
   /**
@@ -1098,13 +1117,18 @@ var _DistriClient = class _DistriClient {
    * Update the access/refresh tokens in memory.
    */
   setTokens(tokens) {
-    if (tokens.accessToken !== void 0) {
-      this.accessToken = tokens.accessToken;
-    }
-    if (tokens.refreshToken !== void 0) {
+    this.accessToken = tokens.accessToken;
+    if (tokens.refreshToken) {
       this.refreshToken = tokens.refreshToken;
     }
   }
+  /**
+   * Reset all authentication tokens.
+   */
+  resetTokens() {
+    this.accessToken = void 0;
+    this.refreshToken = void 0;
+  }
   /**
    * Start streaming speech-to-text transcription via WebSocket
    */
@@ -1322,6 +1346,31 @@ var _DistriClient = class _DistriClient {
       throw new DistriError(`Failed to fetch agent ${agentId}`, "FETCH_ERROR", error);
     }
   }
+  /**
+   * Update an agent's definition (markdown only)
+   */
+  async updateAgent(agentId, update) {
+    try {
+      const response = await this.fetch(`/agents/${agentId}`, {
+        method: "PUT",
+        headers: {
+          "Content-Type": "application/json",
+          ...this.config.headers
+        },
+        body: JSON.stringify(update)
+      });
+      if (!response.ok) {
+        if (response.status === 404) {
+          throw new ApiError(`Agent not found: ${agentId}`, 404);
+        }
+        throw new ApiError(`Failed to update agent: ${response.statusText}`, response.status);
+      }
+      return await response.json();
+    } catch (error) {
+      if (error instanceof ApiError) throw error;
+      throw new DistriError(`Failed to update agent ${agentId}`, "UPDATE_ERROR", error);
+    }
+  }
   /**
    * Get or create A2AClient for an agent
    */
@@ -1370,8 +1419,46 @@ var _DistriClient = class _DistriClient {
       yield* await client.sendMessageStream(params);
     } catch (error) {
       console.error(error);
-      throw new DistriError(`Failed to stream message to agent ${agentId}`, "STREAM_MESSAGE_ERROR", error);
+      const errorMessage = this.extractErrorMessage(error);
+      throw new DistriError(errorMessage, "STREAM_MESSAGE_ERROR", error);
+    }
+  }
+  /**
+   * Extract a user-friendly error message from potentially nested errors
+   */
+  extractErrorMessage(error) {
+    if (!error) return "Unknown error occurred";
+    if (typeof error === "object" && error !== null) {
+      const err = error;
+      if (err.error && typeof err.error === "object") {
+        const jsonRpcError = err.error;
+        if (typeof jsonRpcError.message === "string") {
+          return jsonRpcError.message;
+        }
+      }
+      if (err.message && typeof err.message === "string") {
+        return err.message;
+      }
+      if (err.details && typeof err.details === "object") {
+        const details = err.details;
+        if (details.message && typeof details.message === "string") {
+          return details.message;
+        }
+        if (details.error && typeof details.error === "object") {
+          const nestedError = details.error;
+          if (typeof nestedError.message === "string") {
+            return nestedError.message;
+          }
+        }
+      }
+      if (err.cause && typeof err.cause === "object") {
+        return this.extractErrorMessage(err.cause);
+      }
+    }
+    if (error instanceof Error) {
+      return error.message;
     }
+    return String(error);
   }
   /**
    * Get task details
@@ -1407,11 +1494,22 @@ var _DistriClient = class _DistriClient {
     }
   }
   /**
-   * Get threads from Distri server
+   * Get threads from Distri server with filtering and pagination
    */
-  async getThreads() {
+  async getThreads(params = {}) {
     try {
-      const response = await this.fetch(`/threads`);
+      const searchParams = new URLSearchParams();
+      if (params.agent_id) searchParams.set("agent_id", params.agent_id);
+      if (params.external_id) searchParams.set("external_id", params.external_id);
+      if (params.search) searchParams.set("search", params.search);
+      if (params.from_date) searchParams.set("from_date", params.from_date);
+      if (params.to_date) searchParams.set("to_date", params.to_date);
+      if (params.tags?.length) searchParams.set("tags", params.tags.join(","));
+      if (params.limit !== void 0) searchParams.set("limit", params.limit.toString());
+      if (params.offset !== void 0) searchParams.set("offset", params.offset.toString());
+      const queryString = searchParams.toString();
+      const url = queryString ? `/threads?${queryString}` : "/threads";
+      const response = await this.fetch(url);
       if (!response.ok) {
         throw new ApiError(`Failed to fetch threads: ${response.statusText}`, response.status);
       }
@@ -1421,6 +1519,39 @@ var _DistriClient = class _DistriClient {
       throw new DistriError("Failed to fetch threads", "FETCH_ERROR", error);
     }
   }
+  /**
+   * Get agents sorted by thread count (most active first)
+   */
+  async getAgentsByUsage() {
+    try {
+      const response = await this.fetch("/threads/agents");
+      if (!response.ok) {
+        throw new ApiError(`Failed to fetch agents by usage: ${response.statusText}`, response.status);
+      }
+      return await response.json();
+    } catch (error) {
+      if (error instanceof ApiError) throw error;
+      throw new DistriError("Failed to fetch agents by usage", "FETCH_ERROR", error);
+    }
+  }
+  /**
+   * Create a new browser session
+   * Returns session info including viewer_url and stream_url from browsr
+   */
+  async createBrowserSession() {
+    try {
+      const response = await this.fetch("/browser/session", {
+        method: "POST"
+      });
+      if (!response.ok) {
+        throw new ApiError(`Failed to create browser session: ${response.statusText}`, response.status);
+      }
+      return await response.json();
+    } catch (error) {
+      if (error instanceof ApiError) throw error;
+      throw new DistriError("Failed to create browser session", "FETCH_ERROR", error);
+    }
+  }
   async getThread(threadId) {
     try {
       const response = await this.fetch(`/threads/${threadId}`);
@@ -1520,15 +1651,17 @@ var _DistriClient = class _DistriClient {
   get baseUrl() {
     return this.config.baseUrl;
   }
-  applyTokens(accessToken, refreshToken, notify) {
+  applyTokens(accessToken, refreshToken) {
     this.accessToken = accessToken;
-    this.refreshToken = refreshToken;
-    if (notify && this.onTokenRefresh) {
-      this.onTokenRefresh({ accessToken, refreshToken });
+    if (refreshToken) {
+      this.refreshToken = refreshToken;
     }
   }
+  /**
+   * Ensure access token is valid, refreshing if necessary
+   */
   async ensureAccessToken() {
-    if (!this.refreshToken) {
+    if (!this.refreshToken && !this.onTokenRefresh) {
       return;
     }
     if (!this.accessToken || this.isTokenExpiring(this.accessToken)) {
@@ -1540,7 +1673,7 @@ var _DistriClient = class _DistriClient {
     }
   }
   async refreshTokens() {
-    if (!this.refreshToken) {
+    if (!this.refreshToken && !this.onTokenRefresh) {
       return;
     }
     if (!this.refreshPromise) {
@@ -1551,6 +1684,17 @@ var _DistriClient = class _DistriClient {
     return this.refreshPromise;
   }
   async performTokenRefresh() {
+    if (this.onTokenRefresh) {
+      this.accessToken = void 0;
+      const newToken = await this.onTokenRefresh();
+      if (newToken) {
+        this.applyTokens(newToken);
+        return;
+      }
+    }
+    if (!this.refreshToken) {
+      return;
+    }
     const response = await this.fetchAbsolute(
       `${this.config.baseUrl}/token`,
       {
@@ -1574,7 +1718,7 @@ var _DistriClient = class _DistriClient {
     if (!tokens?.access_token || !tokens?.refresh_token) {
       throw new ApiError("Invalid token response", response.status);
     }
-    this.applyTokens(tokens.access_token, tokens.refresh_token, true);
+    this.applyTokens(tokens.access_token, tokens.refresh_token);
   }
   isTokenExpiring(token) {
     const expiresAt = this.getTokenExpiry(token);
@@ -1669,7 +1813,7 @@ var _DistriClient = class _DistriClient {
           headers
         });
         clearTimeout(timeoutId);
-        if (!skipAuth && retryOnAuth && response.status === 401 && this.refreshToken) {
+        if (!skipAuth && retryOnAuth && response.status === 401 && (this.refreshToken || this.onTokenRefresh)) {
           const refreshed = await this.refreshTokens().then(() => true).catch(() => false);
           if (refreshed) {
             return this.fetchAbsolute(url, initialInit, { skipAuth, retryOnAuth: false });
@@ -1687,7 +1831,8 @@ var _DistriClient = class _DistriClient {
     throw lastError;
   }
   /**
-   * Enhanced fetch with retry logic
+   * Enhanced fetch with retry logic and auth headers.
+   * Exposed publicly for extensions like DistriHomeClient.
    */
   async fetch(input, initialInit) {
     const url = `${this.config.baseUrl}${input}`;
@@ -1760,13 +1905,6 @@ var _DistriClient = class _DistriClient {
   }
 };
 // ============================================================
-// Additional User Message Parts API
-// ============================================================
-// These methods allow external tools to append parts (text, images)
-// to the user message in the next agent iteration.
-// The parts are stored under the key "__additional_user_parts".
-_DistriClient.ADDITIONAL_PARTS_KEY = "__additional_user_parts";
-// ============================================================
 // Token API
 // ============================================================
 // Issue access + refresh tokens for temporary authentication (e.g., frontend use)
@@ -1792,6 +1930,25 @@ function uuidv4() {
 }
 
 // src/agent.ts
+var ExternalToolValidationError = class extends DistriError {
+  constructor(agentName, result) {
+    super(
+      result.message || "Missing required external tools for agent invocation.",
+      "EXTERNAL_TOOL_VALIDATION_ERROR",
+      {
+        agentName,
+        missingTools: result.missingTools,
+        requiredTools: result.requiredTools,
+        providedTools: result.providedTools
+      }
+    );
+    this.name = "ExternalToolValidationError";
+    this.agentName = agentName;
+    this.missingTools = result.missingTools;
+    this.requiredTools = result.requiredTools;
+    this.providedTools = result.providedTools;
+  }
+};
 var Agent = class _Agent {
   constructor(agentDefinition, client) {
     this.hookHandlers = /* @__PURE__ */ new Map();
@@ -1812,7 +1969,7 @@ var Agent = class _Agent {
     return this.agentDefinition.description;
   }
   get agentType() {
-    return this.agentDefinition.agent_type ?? this.agentDefinition.agentType;
+    return this.agentDefinition.agent_type;
   }
   get iconUrl() {
     return this.agentDefinition.icon_url;
@@ -1849,7 +2006,7 @@ var Agent = class _Agent {
     const enhancedParams = this.enhanceParamsWithTools(params, tools);
     const a2aStream = this.client.sendMessageStream(this.agentDefinition.id, enhancedParams);
     const self = this;
-    return (async function* () {
+    return async function* () {
       for await (const event of a2aStream) {
         const converted = decodeA2AStreamEvent(event);
         if (converted && converted.type === "inline_hook_requested") {
@@ -1870,12 +2027,38 @@ var Agent = class _Agent {
           yield converted;
         }
       }
-    })();
+    }();
+  }
+  /**
+   * Validate that required external tools are registered before invoking.
+   */
+  validateExternalTools(tools = []) {
+    const requiredTools = this.getRequiredExternalTools();
+    const providedTools = tools.map((tool) => tool.name);
+    if (requiredTools.length === 0) {
+      return {
+        isValid: true,
+        requiredTools: [],
+        providedTools,
+        missingTools: []
+      };
+    }
+    const providedSet = new Set(providedTools);
+    const missingTools = requiredTools.filter((tool) => !providedSet.has(tool));
+    const isValid = missingTools.length === 0;
+    return {
+      isValid,
+      requiredTools,
+      providedTools,
+      missingTools,
+      message: isValid ? void 0 : this.formatExternalToolValidationMessage(requiredTools, missingTools)
+    };
   }
   /**
    * Enhance message params with tool definitions
    */
   enhanceParamsWithTools(params, tools) {
+    this.assertExternalTools(tools);
     const metadata = {
       ...params.metadata,
       external_tools: tools?.map((tool) => ({
@@ -1890,6 +2073,39 @@ var Agent = class _Agent {
       metadata
     };
   }
+  assertExternalTools(tools) {
+    const result = this.validateExternalTools(tools ?? []);
+    if (!result.isValid) {
+      throw new ExternalToolValidationError(this.agentDefinition.name || this.agentDefinition.id, result);
+    }
+  }
+  getRequiredExternalTools() {
+    const toolConfig = this.resolveToolConfig();
+    if (!toolConfig?.external || !Array.isArray(toolConfig.external)) {
+      return [];
+    }
+    if (toolConfig.external.includes("*")) {
+      return [];
+    }
+    return toolConfig.external.filter((tool) => typeof tool === "string" && tool.trim().length > 0);
+  }
+  resolveToolConfig() {
+    const root = this.agentDefinition;
+    return this.extractToolConfig(root) || this.extractToolConfig(root?.agent) || this.extractToolConfig(root?.definition);
+  }
+  extractToolConfig(candidate) {
+    if (!candidate) return null;
+    const tools = candidate.tools;
+    if (!tools || Array.isArray(tools) || typeof tools !== "object") {
+      return null;
+    }
+    return tools;
+  }
+  formatExternalToolValidationMessage(requiredTools, missingTools) {
+    const requiredList = requiredTools.join(", ");
+    const missingList = missingTools.join(", ");
+    return `Agent has external tools that are not registered: ${missingList}. This is an embedded agent that can run within the parent application. Register DistriWidget for embedding the parent component. Required tools: ${requiredList}.`;
+  }
   /**
    * Register multiple hooks at once.
    */
@@ -1906,12 +2122,13 @@ var Agent = class _Agent {
    */
   static async create(agentIdOrDef, client) {
     const agentDefinition = typeof agentIdOrDef === "string" ? await client.getAgent(agentIdOrDef) : agentIdOrDef;
+    const tools = agentDefinition?.resolved_tools || [];
     console.log("\u{1F916} Agent definition loaded:", {
       id: agentDefinition.id,
       name: agentDefinition.name,
-      tools: agentDefinition.tools?.map((t) => ({
+      tools: tools.map((t) => ({
         name: t.name,
-        type: t.type || "function"
+        type: "function"
       })) || [],
       toolCount: agentDefinition.tools?.length || 0
     });
@@ -1940,6 +2157,7 @@ var Agent = class _Agent {
   DEFAULT_BASE_URL,
   DistriClient,
   DistriError,
+  ExternalToolValidationError,
   convertA2AMessageToDistri,
   convertA2APartToDistri,
   convertA2AStatusUpdateToDistri,