@antipopp/agno-client 0.7.0 → 0.9.0

package/README.md

@@ -68,6 +68,8 @@ new AgnoClient(config: AgnoClientConfig)
 - `dbId` (string, optional) - Database ID
 - `sessionId` (string, optional) - Current session ID
 - `userId` (string, optional) - User ID to link sessions to a specific user
+- `headers` (Record<string, string>, optional) - Global custom headers for all API requests
+- `params` (Record<string, string>, optional) - Global query parameters for all API requests
 
 ### Methods
 
@@ -88,6 +90,17 @@ await client.sendMessage(formData);
 await client.sendMessage('Hello!', {
   headers: { 'X-Custom-Header': 'value' }
 });
+
+// With query parameters
+await client.sendMessage('Hello!', {
+  params: { temperature: '0.7', max_tokens: '500' }
+});
+
+// With both headers and params
+await client.sendMessage('Hello!', {
+  headers: { 'X-Request-ID': '12345' },
+  params: { debug: 'true' }
+});
 ```
 
 #### `getMessages()`
@@ -241,6 +254,94 @@ try {
 }
 ```
 
+### Custom Headers and Query Parameters
+
+The client supports both global and per-request headers and query parameters.
+
+#### Global Configuration
+
+Set headers and params in the client config to apply them to all API requests:
+
+```typescript
+const client = new AgnoClient({
+  endpoint: 'http://localhost:7777',
+  agentId: 'agent-123',
+  headers: {
+    'X-API-Version': 'v2',
+    'X-Client-ID': 'my-app'
+  },
+  params: {
+    locale: 'en-US',
+    environment: 'production'
+  }
+});
+```
+
+#### Per-Request Options
+
+Override or add headers/params for specific requests:
+
+```typescript
+// Per-request overrides global settings
+await client.sendMessage('Hello!', {
+  headers: { 'X-Request-ID': '12345' },
+  params: { temperature: '0.7' }
+});
+
+// All methods support headers and params
+await client.loadSession('session-123', {
+  params: { include_metadata: 'true' }
+});
+
+await client.fetchSessions({
+  params: { limit: '50', status: 'active' }
+});
+
+await client.continueRun(tools, {
+  headers: { 'X-Trace-ID': 'abc123' },
+  params: { debug: 'true' }
+});
+```
+
+#### Merge Behavior
+
+**Headers:**
+1. Global headers from `config.headers` (lowest precedence)
+2. Per-request headers (overrides global)
+3. Authorization header from `authToken` (highest precedence - always overrides)
+
+**Query Parameters:**
+1. Global params from `config.params` (lowest precedence)
+2. Per-request params (highest precedence - overrides global)
+
+```typescript
+const client = new AgnoClient({
+  endpoint: 'http://localhost:7777',
+  agentId: 'agent-123',
+  params: { version: 'v1', locale: 'en-US' }
+});
+
+// This request will have: version=v2 (overridden), locale=en-US (from global), debug=true (added)
+await client.sendMessage('Hello!', {
+  params: { version: 'v2', debug: 'true' }
+});
+```
+
+#### Common Use Cases
+
+**Headers:**
+- Request tracking: `{ 'X-Request-ID': uuid() }`
+- API versioning: `{ 'X-API-Version': 'v2' }`
+- Client identification: `{ 'X-Client-ID': 'mobile-app' }`
+- Custom auth: `{ 'X-Custom-Auth': 'token' }`
+
+**Query Parameters:**
+- Model configuration: `{ temperature: '0.7', max_tokens: '500' }`
+- Feature flags: `{ enable_streaming: 'true' }`
+- Locale/language: `{ locale: 'en-US', timezone: 'America/New_York' }`
+- Debugging: `{ debug: 'true', trace_id: 'xyz' }`
+- Pagination: `{ page: '1', limit: '50' }`
+
 ### Request Cancellation
 
 Use `AbortController` to cancel ongoing requests. This is essential for preventing memory leaks when components unmount or users navigate away during streaming:

package/dist/index.d.mts

@@ -13,6 +13,7 @@ declare class AgnoClient extends EventEmitter {
     private eventProcessor;
     private state;
     private pendingUISpecs;
+    private runCompletedSuccessfully;
     constructor(config: AgnoClientConfig);
     /**
      * Get current messages
@@ -39,6 +40,7 @@ declare class AgnoClient extends EventEmitter {
      */
     sendMessage(message: string | FormData, options?: {
         headers?: Record<string, string>;
+        params?: Record<string, string>;
     }): Promise<void>;
     /**
      * Handle streaming chunk
@@ -48,18 +50,31 @@ declare class AgnoClient extends EventEmitter {
      * Handle error
      */
     private handleError;
+    /**
+     * Refresh messages from the session API after run completion.
+     * Replaces streamed messages with authoritative session data.
+     * Preserves client-side properties like ui_component that aren't stored on the server.
+     * @private
+     */
+    private refreshSessionMessages;
     /**
      * Load a session
      */
-    loadSession(sessionId: string): Promise<ChatMessage[]>;
+    loadSession(sessionId: string, options?: {
+        params?: Record<string, string>;
+    }): Promise<ChatMessage[]>;
     /**
      * Fetch all sessions
      */
-    fetchSessions(): Promise<SessionEntry[]>;
+    fetchSessions(options?: {
+        params?: Record<string, string>;
+    }): Promise<SessionEntry[]>;
     /**
      * Delete a session
      */
-    deleteSession(sessionId: string): Promise<void>;
+    deleteSession(sessionId: string, options?: {
+        params?: Record<string, string>;
+    }): Promise<void>;
     /**
      * Add tool calls to the last message
      * Used by frontend execution to add tool calls that were executed locally
@@ -83,30 +98,39 @@ declare class AgnoClient extends EventEmitter {
      * Teams do not support the continue endpoint.
      *
      * @param tools - Array of tool calls with execution results
-     * @param options - Optional request headers
+     * @param options - Optional request headers and query parameters
      * @throws Error if no paused run exists
      * @throws Error if called with team mode (teams don't support HITL)
      */
     continueRun(tools: ToolCall[], options?: {
         headers?: Record<string, string>;
+        params?: Record<string, string>;
     }): Promise<void>;
     /**
      * Check endpoint status
      */
-    checkStatus(): Promise<boolean>;
+    checkStatus(options?: {
+        params?: Record<string, string>;
+    }): Promise<boolean>;
     /**
      * Fetch agents from endpoint
      */
-    fetchAgents(): Promise<AgentDetails[]>;
+    fetchAgents(options?: {
+        params?: Record<string, string>;
+    }): Promise<AgentDetails[]>;
     /**
      * Fetch teams from endpoint
      */
-    fetchTeams(): Promise<TeamDetails[]>;
+    fetchTeams(options?: {
+        params?: Record<string, string>;
+    }): Promise<TeamDetails[]>;
     /**
      * Initialize client (check status and fetch agents/teams)
      * Automatically selects the first available agent or team if none is configured
      */
-    initialize(): Promise<{
+    initialize(options?: {
+        params?: Record<string, string>;
+    }): Promise<{
         agents: AgentDetails[];
         teams: TeamDetails[];
     }>;

package/dist/index.d.ts

@@ -13,6 +13,7 @@ declare class AgnoClient extends EventEmitter {
     private eventProcessor;
     private state;
     private pendingUISpecs;
+    private runCompletedSuccessfully;
     constructor(config: AgnoClientConfig);
     /**
      * Get current messages
@@ -39,6 +40,7 @@ declare class AgnoClient extends EventEmitter {
      */
     sendMessage(message: string | FormData, options?: {
         headers?: Record<string, string>;
+        params?: Record<string, string>;
     }): Promise<void>;
     /**
      * Handle streaming chunk
@@ -48,18 +50,31 @@ declare class AgnoClient extends EventEmitter {
      * Handle error
      */
     private handleError;
+    /**
+     * Refresh messages from the session API after run completion.
+     * Replaces streamed messages with authoritative session data.
+     * Preserves client-side properties like ui_component that aren't stored on the server.
+     * @private
+     */
+    private refreshSessionMessages;
     /**
      * Load a session
      */
-    loadSession(sessionId: string): Promise<ChatMessage[]>;
+    loadSession(sessionId: string, options?: {
+        params?: Record<string, string>;
+    }): Promise<ChatMessage[]>;
     /**
      * Fetch all sessions
      */
-    fetchSessions(): Promise<SessionEntry[]>;
+    fetchSessions(options?: {
+        params?: Record<string, string>;
+    }): Promise<SessionEntry[]>;
     /**
      * Delete a session
      */
-    deleteSession(sessionId: string): Promise<void>;
+    deleteSession(sessionId: string, options?: {
+        params?: Record<string, string>;
+    }): Promise<void>;
     /**
      * Add tool calls to the last message
      * Used by frontend execution to add tool calls that were executed locally
@@ -83,30 +98,39 @@ declare class AgnoClient extends EventEmitter {
      * Teams do not support the continue endpoint.
      *
      * @param tools - Array of tool calls with execution results
-     * @param options - Optional request headers
+     * @param options - Optional request headers and query parameters
      * @throws Error if no paused run exists
      * @throws Error if called with team mode (teams don't support HITL)
      */
     continueRun(tools: ToolCall[], options?: {
         headers?: Record<string, string>;
+        params?: Record<string, string>;
     }): Promise<void>;
     /**
      * Check endpoint status
      */
-    checkStatus(): Promise<boolean>;
+    checkStatus(options?: {
+        params?: Record<string, string>;
+    }): Promise<boolean>;
     /**
      * Fetch agents from endpoint
      */
-    fetchAgents(): Promise<AgentDetails[]>;
+    fetchAgents(options?: {
+        params?: Record<string, string>;
+    }): Promise<AgentDetails[]>;
     /**
      * Fetch teams from endpoint
      */
-    fetchTeams(): Promise<TeamDetails[]>;
+    fetchTeams(options?: {
+        params?: Record<string, string>;
+    }): Promise<TeamDetails[]>;
     /**
      * Initialize client (check status and fetch agents/teams)
      * Automatically selects the first available agent or team if none is configured
      */
-    initialize(): Promise<{
+    initialize(options?: {
+        params?: Record<string, string>;
+    }): Promise<{
         agents: AgentDetails[];
         teams: TeamDetails[];
     }>;

package/dist/index.js

@@ -250,6 +250,18 @@ var ConfigManager = class {
   setHeaders(headers) {
     this.updateField("headers", headers);
   }
+  /**
+   * Get global query parameters
+   */
+  getParams() {
+    return this.config.params;
+  }
+  /**
+   * Set global query parameters
+   */
+  setParams(params) {
+    this.updateField("params", params);
+  }
   /**
    * Get current entity ID (agent or team based on mode)
    */
@@ -297,6 +309,26 @@ var ConfigManager = class {
     }
     return headers;
   }
+  /**
+   * Build query string by merging global params and per-request params.
+   * Merge order (lowest to highest precedence):
+   * 1. Global params from config
+   * 2. Per-request params (overrides global)
+   *
+   * @param perRequestParams - Optional query parameters for this specific request
+   * @returns URLSearchParams object ready to append to URLs
+   */
+  buildQueryString(perRequestParams) {
+    const params = {};
+    const globalParams = this.getParams();
+    if (globalParams) {
+      Object.assign(params, globalParams);
+    }
+    if (perRequestParams) {
+      Object.assign(params, perRequestParams);
+    }
+    return new URLSearchParams(params);
+  }
 };
 
 // src/managers/session-manager.ts
@@ -304,11 +336,16 @@ var SessionManager = class {
   /**
    * Fetch all sessions for an entity
    */
-  async fetchSessions(endpoint, entityType, entityId, dbId, headers) {
+  async fetchSessions(endpoint, entityType, entityId, dbId, headers, params) {
     const url = new URL(`${endpoint}/sessions`);
     url.searchParams.set("type", entityType);
     url.searchParams.set("component_id", entityId);
     url.searchParams.set("db_id", dbId);
+    if (params) {
+      params.forEach((value, key) => {
+        url.searchParams.set(key, value);
+      });
+    }
     const response = await fetch(url.toString(), { headers });
     if (!response.ok) {
       if (response.status === 404) {
@@ -323,12 +360,20 @@ var SessionManager = class {
    * Fetch a specific session's runs
    * Returns an array of RunSchema directly (not wrapped in { data, meta })
    */
-  async fetchSession(endpoint, entityType, sessionId, dbId, headers) {
+  async fetchSession(endpoint, entityType, sessionId, dbId, headers, userId, params) {
     const url = new URL(`${endpoint}/sessions/${sessionId}/runs`);
     url.searchParams.set("type", entityType);
     if (dbId) {
       url.searchParams.set("db_id", dbId);
     }
+    if (userId) {
+      url.searchParams.set("user_id", userId);
+    }
+    if (params) {
+      params.forEach((value, key) => {
+        url.searchParams.set(key, value);
+      });
+    }
     const response = await fetch(url.toString(), { headers });
     if (!response.ok) {
       throw new Error(`Failed to fetch session: ${response.statusText}`);
@@ -338,11 +383,16 @@ var SessionManager = class {
   /**
    * Delete a session
    */
-  async deleteSession(endpoint, sessionId, dbId, headers) {
+  async deleteSession(endpoint, sessionId, dbId, headers, params) {
     const url = new URL(`${endpoint}/sessions/${sessionId}`);
     if (dbId) {
       url.searchParams.set("db_id", dbId);
     }
+    if (params) {
+      params.forEach((value, key) => {
+        url.searchParams.set(key, value);
+      });
+    }
     const response = await fetch(url.toString(), {
       method: "DELETE",
       headers
@@ -713,6 +763,7 @@ async function streamResponse(options) {
   const {
     apiUrl,
     headers = {},
+    params,
     requestBody,
     onChunk,
     onError,
@@ -720,8 +771,9 @@ async function streamResponse(options) {
     signal
   } = options;
   let buffer = "";
+  const finalUrl = params && params.toString() ? `${apiUrl}?${params.toString()}` : apiUrl;
   try {
-    const response = await fetch(apiUrl, {
+    const response = await fetch(finalUrl, {
       method: "POST",
       headers: {
         ...!(requestBody instanceof FormData) && {
@@ -851,9 +903,10 @@ function toSafeISOString(timestamp) {
   return new Date(ts).toISOString();
 }
 var AgnoClient = class extends import_eventemitter3.default {
-  // toolCallId -> UIComponentSpec
   constructor(config) {
     super();
+    // toolCallId -> UIComponentSpec
+    this.runCompletedSuccessfully = false;
     this.messageStore = new MessageStore();
     this.configManager = new ConfigManager(config);
     this.sessionManager = new SessionManager();
@@ -861,6 +914,7 @@ var AgnoClient = class extends import_eventemitter3.default {
     this.pendingUISpecs = /* @__PURE__ */ new Map();
     this.state = {
       isStreaming: false,
+      isRefreshing: false,
       isEndpointActive: false,
       agents: [],
       teams: [],
@@ -912,6 +966,7 @@ var AgnoClient = class extends import_eventemitter3.default {
     if (this.state.isStreaming) {
       throw new Error("Already streaming a message");
     }
+    this.runCompletedSuccessfully = false;
     const runUrl = this.configManager.getRunUrl();
     if (!runUrl) {
       throw new Error("No agent or team selected");
@@ -954,9 +1009,11 @@ var AgnoClient = class extends import_eventemitter3.default {
         formData.append("user_id", userId);
       }
       const headers = this.configManager.buildRequestHeaders(options?.headers);
+      const params = this.configManager.buildQueryString(options?.params);
       await streamResponse({
         apiUrl: runUrl,
         headers,
+        params,
         requestBody: formData,
         onChunk: (chunk) => {
           this.handleChunk(chunk, newSessionId, formData.get("message"));
@@ -970,11 +1027,15 @@ var AgnoClient = class extends import_eventemitter3.default {
         onError: (error) => {
           this.handleError(error, newSessionId);
         },
-        onComplete: () => {
+        onComplete: async () => {
           this.state.isStreaming = false;
           this.emit("stream:end");
           this.emit("message:complete", this.messageStore.getMessages());
           this.emit("state:change", this.getState());
+          if (this.runCompletedSuccessfully) {
+            this.runCompletedSuccessfully = false;
+            await this.refreshSessionMessages();
+          }
         }
       });
     } catch (error) {
@@ -1038,6 +1099,9 @@ var AgnoClient = class extends import_eventemitter3.default {
       return updated || lastMessage;
     });
     this.applyPendingUISpecs();
+    if (event === import_agno_types2.RunEvent.RunCompleted || event === import_agno_types2.RunEvent.TeamRunCompleted) {
+      this.runCompletedSuccessfully = true;
+    }
     this.emit("message:update", this.messageStore.getMessages());
   }
   /**
@@ -1059,22 +1123,92 @@ var AgnoClient = class extends import_eventemitter3.default {
     this.emit("stream:end");
     this.emit("state:change", this.getState());
   }
+  /**
+   * Refresh messages from the session API after run completion.
+   * Replaces streamed messages with authoritative session data.
+   * Preserves client-side properties like ui_component that aren't stored on the server.
+   * @private
+   */
+  async refreshSessionMessages() {
+    const sessionId = this.configManager.getSessionId();
+    if (!sessionId) {
+      Logger.debug("[AgnoClient] Cannot refresh: no session ID");
+      return;
+    }
+    this.state.isRefreshing = true;
+    this.emit("state:change", this.getState());
+    try {
+      const existingUIComponents = /* @__PURE__ */ new Map();
+      for (const message of this.messageStore.getMessages()) {
+        if (message.tool_calls) {
+          for (const toolCall of message.tool_calls) {
+            if (toolCall.ui_component) {
+              existingUIComponents.set(toolCall.tool_call_id, toolCall.ui_component);
+            }
+          }
+        }
+      }
+      const config = this.configManager.getConfig();
+      const entityType = this.configManager.getMode();
+      const dbId = this.configManager.getDbId() || "";
+      const userId = this.configManager.getUserId();
+      const headers = this.configManager.buildRequestHeaders();
+      const params = this.configManager.buildQueryString();
+      const response = await this.sessionManager.fetchSession(
+        config.endpoint,
+        entityType,
+        sessionId,
+        dbId,
+        headers,
+        userId,
+        params
+      );
+      const messages = this.sessionManager.convertSessionToMessages(response);
+      if (existingUIComponents.size > 0) {
+        for (const message of messages) {
+          if (message.tool_calls) {
+            for (let i = 0; i < message.tool_calls.length; i++) {
+              const toolCall = message.tool_calls[i];
+              const uiComponent = existingUIComponents.get(toolCall.tool_call_id);
+              if (uiComponent) {
+                message.tool_calls[i].ui_component = uiComponent;
+              }
+            }
+          }
+        }
+      }
+      this.messageStore.setMessages(messages);
+      Logger.debug("[AgnoClient] Session refreshed:", `${messages.length} messages`);
+      this.emit("message:refreshed", messages);
+      this.emit("message:update", messages);
+    } catch (error) {
+      Logger.error("[AgnoClient] Failed to refresh session:", error);
+      this.emit("message:error", `Session refresh failed: ${error instanceof Error ? error.message : String(error)}`);
+    } finally {
+      this.state.isRefreshing = false;
+      this.emit("state:change", this.getState());
+    }
+  }
   /**
    * Load a session
    */
-  async loadSession(sessionId) {
+  async loadSession(sessionId, options) {
     Logger.debug("[AgnoClient] loadSession called with sessionId:", sessionId);
     const config = this.configManager.getConfig();
     const entityType = this.configManager.getMode();
     const dbId = this.configManager.getDbId() || "";
-    Logger.debug("[AgnoClient] Loading session with:", { entityType, dbId });
+    const userId = this.configManager.getUserId();
+    Logger.debug("[AgnoClient] Loading session with:", { entityType, dbId, userId });
     const headers = this.configManager.buildRequestHeaders();
+    const params = this.configManager.buildQueryString(options?.params);
     const response = await this.sessionManager.fetchSession(
       config.endpoint,
       entityType,
       sessionId,
       dbId,
-      headers
+      headers,
+      userId,
+      params
     );
     const messages = this.sessionManager.convertSessionToMessages(response);
     Logger.debug("[AgnoClient] Setting messages to store:", `${messages.length} messages`);
@@ -1090,7 +1224,7 @@ var AgnoClient = class extends import_eventemitter3.default {
   /**
    * Fetch all sessions
    */
-  async fetchSessions() {
+  async fetchSessions(options) {
     const config = this.configManager.getConfig();
     const entityType = this.configManager.getMode();
     const entityId = this.configManager.getCurrentEntityId();
@@ -1099,12 +1233,14 @@ var AgnoClient = class extends import_eventemitter3.default {
       throw new Error("Entity ID must be configured");
     }
     const headers = this.configManager.buildRequestHeaders();
+    const params = this.configManager.buildQueryString(options?.params);
     const sessions = await this.sessionManager.fetchSessions(
       config.endpoint,
       entityType,
       entityId,
       dbId,
-      headers
+      headers,
+      params
     );
     this.state.sessions = sessions;
     this.emit("state:change", this.getState());
@@ -1113,15 +1249,17 @@ var AgnoClient = class extends import_eventemitter3.default {
   /**
    * Delete a session
    */
-  async deleteSession(sessionId) {
+  async deleteSession(sessionId, options) {
     const config = this.configManager.getConfig();
     const dbId = this.configManager.getDbId() || "";
     const headers = this.configManager.buildRequestHeaders();
+    const params = this.configManager.buildQueryString(options?.params);
     await this.sessionManager.deleteSession(
       config.endpoint,
       sessionId,
       dbId,
-      headers
+      headers,
+      params
     );
     this.state.sessions = this.state.sessions.filter(
       (s) => s.session_id !== sessionId
@@ -1235,7 +1373,7 @@ var AgnoClient = class extends import_eventemitter3.default {
    * Teams do not support the continue endpoint.
    *
    * @param tools - Array of tool calls with execution results
-   * @param options - Optional request headers
+   * @param options - Optional request headers and query parameters
    * @throws Error if no paused run exists
    * @throws Error if called with team mode (teams don't support HITL)
    */
@@ -1273,10 +1411,12 @@ var AgnoClient = class extends import_eventemitter3.default {
       formData.append("user_id", userId);
     }
     const headers = this.configManager.buildRequestHeaders(options?.headers);
+    const params = this.configManager.buildQueryString(options?.params);
     try {
       await streamResponse({
         apiUrl: continueUrl,
         headers,
+        params,
         requestBody: formData,
         onChunk: (chunk) => {
           this.handleChunk(chunk, currentSessionId, "");
@@ -1284,13 +1424,17 @@ var AgnoClient = class extends import_eventemitter3.default {
         onError: (error) => {
           this.handleError(error, currentSessionId);
         },
-        onComplete: () => {
+        onComplete: async () => {
           this.state.isStreaming = false;
           this.state.pausedRunId = void 0;
           this.state.toolsAwaitingExecution = void 0;
           this.emit("stream:end");
           this.emit("message:complete", this.messageStore.getMessages());
           this.emit("state:change", this.getState());
+          if (this.runCompletedSuccessfully) {
+            this.runCompletedSuccessfully = false;
+            await this.refreshSessionMessages();
+          }
         }
       });
     } catch (error) {
@@ -1303,10 +1447,17 @@ var AgnoClient = class extends import_eventemitter3.default {
   /**
    * Check endpoint status
    */
-  async checkStatus() {
+  async checkStatus(options) {
     try {
       const headers = this.configManager.buildRequestHeaders();
-      const response = await fetch(`${this.configManager.getEndpoint()}/health`, { headers });
+      const params = this.configManager.buildQueryString(options?.params);
+      const url = new URL(`${this.configManager.getEndpoint()}/health`);
+      if (params.toString()) {
+        params.forEach((value, key) => {
+          url.searchParams.set(key, value);
+        });
+      }
+      const response = await fetch(url.toString(), { headers });
       const isActive = response.ok;
       this.state.isEndpointActive = isActive;
       this.emit("state:change", this.getState());
@@ -1320,9 +1471,16 @@ var AgnoClient = class extends import_eventemitter3.default {
   /**
    * Fetch agents from endpoint
    */
-  async fetchAgents() {
+  async fetchAgents(options) {
     const headers = this.configManager.buildRequestHeaders();
-    const response = await fetch(`${this.configManager.getEndpoint()}/agents`, { headers });
+    const params = this.configManager.buildQueryString(options?.params);
+    const url = new URL(`${this.configManager.getEndpoint()}/agents`);
+    if (params.toString()) {
+      params.forEach((value, key) => {
+        url.searchParams.set(key, value);
+      });
+    }
+    const response = await fetch(url.toString(), { headers });
     if (!response.ok) {
       throw new Error("Failed to fetch agents");
     }
@@ -1334,9 +1492,16 @@ var AgnoClient = class extends import_eventemitter3.default {
   /**
    * Fetch teams from endpoint
    */
-  async fetchTeams() {
+  async fetchTeams(options) {
     const headers = this.configManager.buildRequestHeaders();
-    const response = await fetch(`${this.configManager.getEndpoint()}/teams`, { headers });
+    const params = this.configManager.buildQueryString(options?.params);
+    const url = new URL(`${this.configManager.getEndpoint()}/teams`);
+    if (params.toString()) {
+      params.forEach((value, key) => {
+        url.searchParams.set(key, value);
+      });
+    }
+    const response = await fetch(url.toString(), { headers });
     if (!response.ok) {
       throw new Error("Failed to fetch teams");
     }
@@ -1349,14 +1514,14 @@ var AgnoClient = class extends import_eventemitter3.default {
    * Initialize client (check status and fetch agents/teams)
    * Automatically selects the first available agent or team if none is configured
    */
-  async initialize() {
-    const isActive = await this.checkStatus();
+  async initialize(options) {
+    const isActive = await this.checkStatus(options);
     if (!isActive) {
       return { agents: [], teams: [] };
     }
     const [agents, teams] = await Promise.all([
-      this.fetchAgents(),
-      this.fetchTeams()
+      this.fetchAgents(options),
+      this.fetchTeams(options)
     ]);
     const currentConfig = this.configManager.getConfig();
     const hasAgentConfigured = currentConfig.agentId;

package/dist/index.mjs

@@ -212,6 +212,18 @@ var ConfigManager = class {
   setHeaders(headers) {
     this.updateField("headers", headers);
   }
+  /**
+   * Get global query parameters
+   */
+  getParams() {
+    return this.config.params;
+  }
+  /**
+   * Set global query parameters
+   */
+  setParams(params) {
+    this.updateField("params", params);
+  }
   /**
    * Get current entity ID (agent or team based on mode)
    */
@@ -259,6 +271,26 @@ var ConfigManager = class {
     }
     return headers;
   }
+  /**
+   * Build query string by merging global params and per-request params.
+   * Merge order (lowest to highest precedence):
+   * 1. Global params from config
+   * 2. Per-request params (overrides global)
+   *
+   * @param perRequestParams - Optional query parameters for this specific request
+   * @returns URLSearchParams object ready to append to URLs
+   */
+  buildQueryString(perRequestParams) {
+    const params = {};
+    const globalParams = this.getParams();
+    if (globalParams) {
+      Object.assign(params, globalParams);
+    }
+    if (perRequestParams) {
+      Object.assign(params, perRequestParams);
+    }
+    return new URLSearchParams(params);
+  }
 };
 
 // src/managers/session-manager.ts
@@ -266,11 +298,16 @@ var SessionManager = class {
   /**
    * Fetch all sessions for an entity
    */
-  async fetchSessions(endpoint, entityType, entityId, dbId, headers) {
+  async fetchSessions(endpoint, entityType, entityId, dbId, headers, params) {
     const url = new URL(`${endpoint}/sessions`);
     url.searchParams.set("type", entityType);
     url.searchParams.set("component_id", entityId);
     url.searchParams.set("db_id", dbId);
+    if (params) {
+      params.forEach((value, key) => {
+        url.searchParams.set(key, value);
+      });
+    }
     const response = await fetch(url.toString(), { headers });
     if (!response.ok) {
       if (response.status === 404) {
@@ -285,12 +322,20 @@ var SessionManager = class {
    * Fetch a specific session's runs
    * Returns an array of RunSchema directly (not wrapped in { data, meta })
    */
-  async fetchSession(endpoint, entityType, sessionId, dbId, headers) {
+  async fetchSession(endpoint, entityType, sessionId, dbId, headers, userId, params) {
     const url = new URL(`${endpoint}/sessions/${sessionId}/runs`);
     url.searchParams.set("type", entityType);
     if (dbId) {
       url.searchParams.set("db_id", dbId);
     }
+    if (userId) {
+      url.searchParams.set("user_id", userId);
+    }
+    if (params) {
+      params.forEach((value, key) => {
+        url.searchParams.set(key, value);
+      });
+    }
     const response = await fetch(url.toString(), { headers });
     if (!response.ok) {
       throw new Error(`Failed to fetch session: ${response.statusText}`);
@@ -300,11 +345,16 @@ var SessionManager = class {
   /**
    * Delete a session
    */
-  async deleteSession(endpoint, sessionId, dbId, headers) {
+  async deleteSession(endpoint, sessionId, dbId, headers, params) {
     const url = new URL(`${endpoint}/sessions/${sessionId}`);
     if (dbId) {
       url.searchParams.set("db_id", dbId);
     }
+    if (params) {
+      params.forEach((value, key) => {
+        url.searchParams.set(key, value);
+      });
+    }
     const response = await fetch(url.toString(), {
       method: "DELETE",
       headers
@@ -675,6 +725,7 @@ async function streamResponse(options) {
   const {
     apiUrl,
     headers = {},
+    params,
     requestBody,
     onChunk,
     onError,
@@ -682,8 +733,9 @@ async function streamResponse(options) {
     signal
   } = options;
   let buffer = "";
+  const finalUrl = params && params.toString() ? `${apiUrl}?${params.toString()}` : apiUrl;
   try {
-    const response = await fetch(apiUrl, {
+    const response = await fetch(finalUrl, {
       method: "POST",
       headers: {
         ...!(requestBody instanceof FormData) && {
@@ -813,9 +865,10 @@ function toSafeISOString(timestamp) {
   return new Date(ts).toISOString();
 }
 var AgnoClient = class extends EventEmitter {
-  // toolCallId -> UIComponentSpec
   constructor(config) {
     super();
+    // toolCallId -> UIComponentSpec
+    this.runCompletedSuccessfully = false;
     this.messageStore = new MessageStore();
     this.configManager = new ConfigManager(config);
     this.sessionManager = new SessionManager();
@@ -823,6 +876,7 @@ var AgnoClient = class extends EventEmitter {
     this.pendingUISpecs = /* @__PURE__ */ new Map();
     this.state = {
       isStreaming: false,
+      isRefreshing: false,
       isEndpointActive: false,
       agents: [],
       teams: [],
@@ -874,6 +928,7 @@ var AgnoClient = class extends EventEmitter {
     if (this.state.isStreaming) {
       throw new Error("Already streaming a message");
     }
+    this.runCompletedSuccessfully = false;
     const runUrl = this.configManager.getRunUrl();
     if (!runUrl) {
       throw new Error("No agent or team selected");
@@ -916,9 +971,11 @@ var AgnoClient = class extends EventEmitter {
         formData.append("user_id", userId);
       }
       const headers = this.configManager.buildRequestHeaders(options?.headers);
+      const params = this.configManager.buildQueryString(options?.params);
       await streamResponse({
         apiUrl: runUrl,
         headers,
+        params,
         requestBody: formData,
         onChunk: (chunk) => {
           this.handleChunk(chunk, newSessionId, formData.get("message"));
@@ -932,11 +989,15 @@ var AgnoClient = class extends EventEmitter {
         onError: (error) => {
           this.handleError(error, newSessionId);
         },
-        onComplete: () => {
+        onComplete: async () => {
           this.state.isStreaming = false;
           this.emit("stream:end");
           this.emit("message:complete", this.messageStore.getMessages());
           this.emit("state:change", this.getState());
+          if (this.runCompletedSuccessfully) {
+            this.runCompletedSuccessfully = false;
+            await this.refreshSessionMessages();
+          }
         }
       });
     } catch (error) {
@@ -1000,6 +1061,9 @@ var AgnoClient = class extends EventEmitter {
       return updated || lastMessage;
     });
     this.applyPendingUISpecs();
+    if (event === RunEvent.RunCompleted || event === RunEvent.TeamRunCompleted) {
+      this.runCompletedSuccessfully = true;
+    }
     this.emit("message:update", this.messageStore.getMessages());
   }
   /**
@@ -1021,22 +1085,92 @@ var AgnoClient = class extends EventEmitter {
     this.emit("stream:end");
     this.emit("state:change", this.getState());
   }
+  /**
+   * Refresh messages from the session API after run completion.
+   * Replaces streamed messages with authoritative session data.
+   * Preserves client-side properties like ui_component that aren't stored on the server.
+   * @private
+   */
+  async refreshSessionMessages() {
+    const sessionId = this.configManager.getSessionId();
+    if (!sessionId) {
+      Logger.debug("[AgnoClient] Cannot refresh: no session ID");
+      return;
+    }
+    this.state.isRefreshing = true;
+    this.emit("state:change", this.getState());
+    try {
+      const existingUIComponents = /* @__PURE__ */ new Map();
+      for (const message of this.messageStore.getMessages()) {
+        if (message.tool_calls) {
+          for (const toolCall of message.tool_calls) {
+            if (toolCall.ui_component) {
+              existingUIComponents.set(toolCall.tool_call_id, toolCall.ui_component);
+            }
+          }
+        }
+      }
+      const config = this.configManager.getConfig();
+      const entityType = this.configManager.getMode();
+      const dbId = this.configManager.getDbId() || "";
+      const userId = this.configManager.getUserId();
+      const headers = this.configManager.buildRequestHeaders();
+      const params = this.configManager.buildQueryString();
+      const response = await this.sessionManager.fetchSession(
+        config.endpoint,
+        entityType,
+        sessionId,
+        dbId,
+        headers,
+        userId,
+        params
+      );
+      const messages = this.sessionManager.convertSessionToMessages(response);
+      if (existingUIComponents.size > 0) {
+        for (const message of messages) {
+          if (message.tool_calls) {
+            for (let i = 0; i < message.tool_calls.length; i++) {
+              const toolCall = message.tool_calls[i];
+              const uiComponent = existingUIComponents.get(toolCall.tool_call_id);
+              if (uiComponent) {
+                message.tool_calls[i].ui_component = uiComponent;
+              }
+            }
+          }
+        }
+      }
+      this.messageStore.setMessages(messages);
+      Logger.debug("[AgnoClient] Session refreshed:", `${messages.length} messages`);
+      this.emit("message:refreshed", messages);
+      this.emit("message:update", messages);
+    } catch (error) {
+      Logger.error("[AgnoClient] Failed to refresh session:", error);
+      this.emit("message:error", `Session refresh failed: ${error instanceof Error ? error.message : String(error)}`);
+    } finally {
+      this.state.isRefreshing = false;
+      this.emit("state:change", this.getState());
+    }
+  }
   /**
    * Load a session
    */
-  async loadSession(sessionId) {
+  async loadSession(sessionId, options) {
     Logger.debug("[AgnoClient] loadSession called with sessionId:", sessionId);
     const config = this.configManager.getConfig();
     const entityType = this.configManager.getMode();
     const dbId = this.configManager.getDbId() || "";
-    Logger.debug("[AgnoClient] Loading session with:", { entityType, dbId });
+    const userId = this.configManager.getUserId();
+    Logger.debug("[AgnoClient] Loading session with:", { entityType, dbId, userId });
     const headers = this.configManager.buildRequestHeaders();
+    const params = this.configManager.buildQueryString(options?.params);
     const response = await this.sessionManager.fetchSession(
       config.endpoint,
       entityType,
       sessionId,
       dbId,
-      headers
+      headers,
+      userId,
+      params
     );
     const messages = this.sessionManager.convertSessionToMessages(response);
     Logger.debug("[AgnoClient] Setting messages to store:", `${messages.length} messages`);
@@ -1052,7 +1186,7 @@ var AgnoClient = class extends EventEmitter {
   /**
    * Fetch all sessions
    */
-  async fetchSessions() {
+  async fetchSessions(options) {
     const config = this.configManager.getConfig();
     const entityType = this.configManager.getMode();
     const entityId = this.configManager.getCurrentEntityId();
@@ -1061,12 +1195,14 @@ var AgnoClient = class extends EventEmitter {
       throw new Error("Entity ID must be configured");
     }
     const headers = this.configManager.buildRequestHeaders();
+    const params = this.configManager.buildQueryString(options?.params);
     const sessions = await this.sessionManager.fetchSessions(
       config.endpoint,
       entityType,
       entityId,
       dbId,
-      headers
+      headers,
+      params
     );
     this.state.sessions = sessions;
     this.emit("state:change", this.getState());
@@ -1075,15 +1211,17 @@ var AgnoClient = class extends EventEmitter {
   /**
    * Delete a session
    */
-  async deleteSession(sessionId) {
+  async deleteSession(sessionId, options) {
     const config = this.configManager.getConfig();
     const dbId = this.configManager.getDbId() || "";
     const headers = this.configManager.buildRequestHeaders();
+    const params = this.configManager.buildQueryString(options?.params);
     await this.sessionManager.deleteSession(
       config.endpoint,
       sessionId,
       dbId,
-      headers
+      headers,
+      params
     );
     this.state.sessions = this.state.sessions.filter(
       (s) => s.session_id !== sessionId
@@ -1197,7 +1335,7 @@ var AgnoClient = class extends EventEmitter {
    * Teams do not support the continue endpoint.
    *
    * @param tools - Array of tool calls with execution results
-   * @param options - Optional request headers
+   * @param options - Optional request headers and query parameters
    * @throws Error if no paused run exists
    * @throws Error if called with team mode (teams don't support HITL)
    */
@@ -1235,10 +1373,12 @@ var AgnoClient = class extends EventEmitter {
       formData.append("user_id", userId);
     }
     const headers = this.configManager.buildRequestHeaders(options?.headers);
+    const params = this.configManager.buildQueryString(options?.params);
     try {
       await streamResponse({
         apiUrl: continueUrl,
         headers,
+        params,
         requestBody: formData,
         onChunk: (chunk) => {
           this.handleChunk(chunk, currentSessionId, "");
@@ -1246,13 +1386,17 @@ var AgnoClient = class extends EventEmitter {
         onError: (error) => {
           this.handleError(error, currentSessionId);
         },
-        onComplete: () => {
+        onComplete: async () => {
           this.state.isStreaming = false;
           this.state.pausedRunId = void 0;
           this.state.toolsAwaitingExecution = void 0;
           this.emit("stream:end");
           this.emit("message:complete", this.messageStore.getMessages());
           this.emit("state:change", this.getState());
+          if (this.runCompletedSuccessfully) {
+            this.runCompletedSuccessfully = false;
+            await this.refreshSessionMessages();
+          }
         }
       });
     } catch (error) {
@@ -1265,10 +1409,17 @@ var AgnoClient = class extends EventEmitter {
   /**
    * Check endpoint status
    */
-  async checkStatus() {
+  async checkStatus(options) {
     try {
       const headers = this.configManager.buildRequestHeaders();
-      const response = await fetch(`${this.configManager.getEndpoint()}/health`, { headers });
+      const params = this.configManager.buildQueryString(options?.params);
+      const url = new URL(`${this.configManager.getEndpoint()}/health`);
+      if (params.toString()) {
+        params.forEach((value, key) => {
+          url.searchParams.set(key, value);
+        });
+      }
+      const response = await fetch(url.toString(), { headers });
       const isActive = response.ok;
       this.state.isEndpointActive = isActive;
       this.emit("state:change", this.getState());
@@ -1282,9 +1433,16 @@ var AgnoClient = class extends EventEmitter {
   /**
    * Fetch agents from endpoint
    */
-  async fetchAgents() {
+  async fetchAgents(options) {
     const headers = this.configManager.buildRequestHeaders();
-    const response = await fetch(`${this.configManager.getEndpoint()}/agents`, { headers });
+    const params = this.configManager.buildQueryString(options?.params);
+    const url = new URL(`${this.configManager.getEndpoint()}/agents`);
+    if (params.toString()) {
+      params.forEach((value, key) => {
+        url.searchParams.set(key, value);
+      });
+    }
+    const response = await fetch(url.toString(), { headers });
     if (!response.ok) {
       throw new Error("Failed to fetch agents");
     }
@@ -1296,9 +1454,16 @@ var AgnoClient = class extends EventEmitter {
   /**
    * Fetch teams from endpoint
    */
-  async fetchTeams() {
+  async fetchTeams(options) {
     const headers = this.configManager.buildRequestHeaders();
-    const response = await fetch(`${this.configManager.getEndpoint()}/teams`, { headers });
+    const params = this.configManager.buildQueryString(options?.params);
+    const url = new URL(`${this.configManager.getEndpoint()}/teams`);
+    if (params.toString()) {
+      params.forEach((value, key) => {
+        url.searchParams.set(key, value);
+      });
+    }
+    const response = await fetch(url.toString(), { headers });
     if (!response.ok) {
       throw new Error("Failed to fetch teams");
     }
@@ -1311,14 +1476,14 @@ var AgnoClient = class extends EventEmitter {
    * Initialize client (check status and fetch agents/teams)
    * Automatically selects the first available agent or team if none is configured
    */
-  async initialize() {
-    const isActive = await this.checkStatus();
+  async initialize(options) {
+    const isActive = await this.checkStatus(options);
     if (!isActive) {
       return { agents: [], teams: [] };
     }
     const [agents, teams] = await Promise.all([
-      this.fetchAgents(),
-      this.fetchTeams()
+      this.fetchAgents(options),
+      this.fetchTeams(options)
     ]);
     const currentConfig = this.configManager.getConfig();
     const hasAgentConfigured = currentConfig.agentId;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antipopp/agno-client",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Core client library for Agno agents with streaming support and HITL frontend tool execution",
   "author": "antipopp",
   "license": "MIT",
@@ -34,7 +34,7 @@
   ],
   "dependencies": {
     "eventemitter3": "^5.0.1",
-    "@antipopp/agno-types": "0.7.0"
+    "@antipopp/agno-types": "0.9.0"
   },
   "devDependencies": {
     "tsup": "^8.0.1",