@realtimex/sdk 1.3.1 → 1.3.3

package/README.md

@@ -167,6 +167,19 @@ const response = await sdk.llm.chat(
 );
 console.log(response.response?.content);
 
+// Multimodal Chat (text + file/image blocks)
+const multimodal = await sdk.llm.chat([
+  {
+    role: 'user',
+    content: [
+      { type: 'text', text: 'Summarize the attached document' },
+      { type: 'input_file', file_url: 'https://example.com/report.pdf' },
+      { type: 'input_image', image_url: 'https://example.com/chart.png' }
+    ]
+  }
+]);
+console.log(multimodal.response?.content);
+
 // Streaming Chat
 for await (const chunk of sdk.llm.chatStream(messages, options)) {
   process.stdout.write(chunk.textResponse || '');

package/dist/index.d.mts

@@ -380,9 +380,36 @@ declare class PortModule {
  * - Vector storage (upsert, query, delete)
  */
 
+interface ChatTextBlock {
+    type: 'text' | 'input_text';
+    text: string;
+    [key: string]: unknown;
+}
+interface ChatImageUrlBlock {
+    type: 'image_url' | 'input_image';
+    image_url: string | {
+        url: string;
+        detail?: 'auto' | 'low' | 'high';
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+interface ChatFileBlock {
+    type: 'input_file' | 'file';
+    file_url?: string;
+    file_id?: string;
+    filename?: string;
+    [key: string]: unknown;
+}
+interface ChatCustomBlock {
+    type: string;
+    [key: string]: unknown;
+}
+type ChatContentBlock = ChatTextBlock | ChatImageUrlBlock | ChatFileBlock | ChatCustomBlock;
+type ChatMessageContent = string | ChatContentBlock[];
 interface ChatMessage {
     role: 'system' | 'user' | 'assistant';
-    content: string;
+    content: ChatMessageContent;
 }
 interface ChatOptions {
     model?: string;
@@ -812,6 +839,149 @@ declare class STTModule extends ApiModule {
     listen(options: STTListenOptions): Promise<STTResponse>;
 }
 
+/**
+ * HTTP Client Module - Smart Client with Auth Handling
+ */
+declare class HttpClient {
+    private baseUrl;
+    private appId;
+    private apiKey?;
+    private accessToken?;
+    constructor(baseUrl: string, appId: string, apiKey?: string);
+    private getAppHeaders;
+    private getAccessToken;
+    fetch(endpoint: string, options?: RequestInit): Promise<Response>;
+}
+
+/**
+ * Agent Module - Simple session-based agent chat
+ *
+ * This module provides the simplest way to chat with AI agents:
+ * 1. Create a session (optional - can just chat directly)
+ * 2. Send messages (context is automatically maintained)
+ * 3. Close session when done (optional - auto-expires)
+ */
+
+interface AgentSessionOptions {
+    workspace_slug?: string;
+    thread_slug?: string;
+    agent_name?: string;
+}
+interface AgentSession {
+    session_id: string;
+    workspace: {
+        slug: string;
+        name: string;
+    };
+    thread?: {
+        slug: string;
+        name: string;
+    } | null;
+    agent: {
+        name: string;
+        provider: string;
+        model: string | null;
+    };
+    created_at: string;
+}
+interface AgentChatOptions {
+    message: string;
+}
+interface AgentChatResponse {
+    id: string;
+    session_id: string;
+    text: string;
+    thoughts: string[];
+    message_count: number;
+}
+interface AgentSessionInfo extends AgentSession {
+    message_count: number;
+    last_message_at: string | null;
+}
+interface StreamChunkEvent {
+    type: 'agentThought' | 'textResponse' | 'close' | 'error';
+    data: any;
+}
+declare class AgentModule {
+    private httpClient;
+    constructor(httpClient: HttpClient);
+    /**
+     * Create a new agent session
+     *
+     * @example
+     * ```typescript
+     * const session = await sdk.agent.createSession({
+     *   workspace_slug: 'my-workspace',
+     *   agent_name: '@agent'
+     * });
+     * ```
+     */
+    createSession(options?: AgentSessionOptions): Promise<AgentSession>;
+    /**
+     * Chat within a session (synchronous)
+     *
+     * @example
+     * ```typescript
+     * const response = await sdk.agent.chat(sessionId, 'Hello agent!');
+     * console.log(response.text);
+     * ```
+     */
+    chat(sessionId: string, message: string): Promise<AgentChatResponse>;
+    /**
+     * Stream chat within a session
+     * Returns an async iterator for SSE events
+     *
+     * @example
+     * ```typescript
+     * for await (const event of sdk.agent.streamChat(sessionId, 'Tell me a story')) {
+     *   if (event.type === 'agentThought') {
+     *     console.log('Thinking:', event.data.thought);
+     *   } else if (event.type === 'textResponse') {
+     *     console.log('Response:', event.data.textResponse);
+     *   }
+     * }
+     * ```
+     */
+    streamChat(sessionId: string, message: string): AsyncIterableIterator<StreamChunkEvent>;
+    /**
+     * Get session information
+     *
+     * @example
+     * ```typescript
+     * const info = await sdk.agent.getSession(sessionId);
+     * console.log(`Messages sent: ${info.message_count}`);
+     * ```
+     */
+    getSession(sessionId: string): Promise<AgentSessionInfo>;
+    /**
+     * Close and delete a session
+     * Sessions auto-expire after 1 hour, but you can close them manually
+     *
+     * @example
+     * ```typescript
+     * await sdk.agent.closeSession(sessionId);
+     * ```
+     */
+    closeSession(sessionId: string): Promise<void>;
+    /**
+     * Helper: Create session and send first message in one call
+     * This is the simplest way to start chatting with an agent
+     *
+     * @example
+     * ```typescript
+     * const { session, response } = await sdk.agent.startChat('Hello agent!');
+     * console.log(response.text);
+     *
+     * // Continue chatting in the same session
+     * const reply = await sdk.agent.chat(session.session_id, 'Tell me more');
+     * ```
+     */
+    startChat(message: string, options?: AgentSessionOptions): Promise<{
+        session: AgentSession;
+        response: AgentChatResponse;
+    }>;
+}
+
 /**
  * RealtimeX Local App SDK
  *
@@ -828,11 +998,13 @@ declare class RealtimeXSDK {
     llm: LLMModule;
     tts: TTSModule;
     stt: STTModule;
+    agent: AgentModule;
     readonly appId: string;
     readonly appName: string | undefined;
     readonly apiKey: string | undefined;
     private readonly realtimexUrl;
     private readonly permissions;
+    private httpClient;
     private static DEFAULT_REALTIMEX_URL;
     constructor(config?: SDKConfig);
     /**
@@ -861,4 +1033,4 @@ declare class RealtimeXSDK {
     getAppDataDir(): Promise<string>;
 }
 
-export { ActivitiesModule, type Activity, type Agent, ApiModule, type ChatMessage, type ChatOptions, type ChatResponse, type EmbedOptions, type EmbedResponse, LLMModule, LLMPermissionError, LLMProviderError, PermissionDeniedError, PermissionRequiredError, PortModule, type Provider, type ProvidersResponse, RealtimeXSDK, type SDKConfig, type STTListenOptions, type STTModel, type STTModelsResponse, STTModule, type STTProvider, type STTProvidersResponse, type STTResponse, type StreamChunk, type TTSChunk, type TTSChunkEvent, TTSModule, type TTSOptions, type TTSProvider, type TTSProviderConfig, type TTSProvidersResponse, type Task, TaskModule, type TaskRun, type Thread, type TriggerAgentPayload, type TriggerAgentResponse, type VectorDeleteOptions, type VectorDeleteResponse, type VectorQueryOptions, type VectorQueryResponse, type VectorQueryResult, type VectorRecord, VectorStore, type VectorUpsertOptions, type VectorUpsertResponse, WebhookModule, type Workspace };
+export { ActivitiesModule, type Activity, type Agent, type AgentChatOptions, type AgentChatResponse, AgentModule, type AgentSession, type AgentSessionInfo, type AgentSessionOptions, ApiModule, type ChatContentBlock, type ChatCustomBlock, type ChatFileBlock, type ChatImageUrlBlock, type ChatMessage, type ChatMessageContent, type ChatOptions, type ChatResponse, type ChatTextBlock, type EmbedOptions, type EmbedResponse, LLMModule, LLMPermissionError, LLMProviderError, PermissionDeniedError, PermissionRequiredError, PortModule, type Provider, type ProvidersResponse, RealtimeXSDK, type SDKConfig, type STTListenOptions, type STTModel, type STTModelsResponse, STTModule, type STTProvider, type STTProvidersResponse, type STTResponse, type StreamChunk, type StreamChunkEvent, type TTSChunk, type TTSChunkEvent, TTSModule, type TTSOptions, type TTSProvider, type TTSProviderConfig, type TTSProvidersResponse, type Task, TaskModule, type TaskRun, type Thread, type TriggerAgentPayload, type TriggerAgentResponse, type VectorDeleteOptions, type VectorDeleteResponse, type VectorQueryOptions, type VectorQueryResponse, type VectorQueryResult, type VectorRecord, VectorStore, type VectorUpsertOptions, type VectorUpsertResponse, WebhookModule, type Workspace };

package/dist/index.d.ts

@@ -380,9 +380,36 @@ declare class PortModule {
  * - Vector storage (upsert, query, delete)
  */
 
+interface ChatTextBlock {
+    type: 'text' | 'input_text';
+    text: string;
+    [key: string]: unknown;
+}
+interface ChatImageUrlBlock {
+    type: 'image_url' | 'input_image';
+    image_url: string | {
+        url: string;
+        detail?: 'auto' | 'low' | 'high';
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+interface ChatFileBlock {
+    type: 'input_file' | 'file';
+    file_url?: string;
+    file_id?: string;
+    filename?: string;
+    [key: string]: unknown;
+}
+interface ChatCustomBlock {
+    type: string;
+    [key: string]: unknown;
+}
+type ChatContentBlock = ChatTextBlock | ChatImageUrlBlock | ChatFileBlock | ChatCustomBlock;
+type ChatMessageContent = string | ChatContentBlock[];
 interface ChatMessage {
     role: 'system' | 'user' | 'assistant';
-    content: string;
+    content: ChatMessageContent;
 }
 interface ChatOptions {
     model?: string;
@@ -812,6 +839,149 @@ declare class STTModule extends ApiModule {
     listen(options: STTListenOptions): Promise<STTResponse>;
 }
 
+/**
+ * HTTP Client Module - Smart Client with Auth Handling
+ */
+declare class HttpClient {
+    private baseUrl;
+    private appId;
+    private apiKey?;
+    private accessToken?;
+    constructor(baseUrl: string, appId: string, apiKey?: string);
+    private getAppHeaders;
+    private getAccessToken;
+    fetch(endpoint: string, options?: RequestInit): Promise<Response>;
+}
+
+/**
+ * Agent Module - Simple session-based agent chat
+ *
+ * This module provides the simplest way to chat with AI agents:
+ * 1. Create a session (optional - can just chat directly)
+ * 2. Send messages (context is automatically maintained)
+ * 3. Close session when done (optional - auto-expires)
+ */
+
+interface AgentSessionOptions {
+    workspace_slug?: string;
+    thread_slug?: string;
+    agent_name?: string;
+}
+interface AgentSession {
+    session_id: string;
+    workspace: {
+        slug: string;
+        name: string;
+    };
+    thread?: {
+        slug: string;
+        name: string;
+    } | null;
+    agent: {
+        name: string;
+        provider: string;
+        model: string | null;
+    };
+    created_at: string;
+}
+interface AgentChatOptions {
+    message: string;
+}
+interface AgentChatResponse {
+    id: string;
+    session_id: string;
+    text: string;
+    thoughts: string[];
+    message_count: number;
+}
+interface AgentSessionInfo extends AgentSession {
+    message_count: number;
+    last_message_at: string | null;
+}
+interface StreamChunkEvent {
+    type: 'agentThought' | 'textResponse' | 'close' | 'error';
+    data: any;
+}
+declare class AgentModule {
+    private httpClient;
+    constructor(httpClient: HttpClient);
+    /**
+     * Create a new agent session
+     *
+     * @example
+     * ```typescript
+     * const session = await sdk.agent.createSession({
+     *   workspace_slug: 'my-workspace',
+     *   agent_name: '@agent'
+     * });
+     * ```
+     */
+    createSession(options?: AgentSessionOptions): Promise<AgentSession>;
+    /**
+     * Chat within a session (synchronous)
+     *
+     * @example
+     * ```typescript
+     * const response = await sdk.agent.chat(sessionId, 'Hello agent!');
+     * console.log(response.text);
+     * ```
+     */
+    chat(sessionId: string, message: string): Promise<AgentChatResponse>;
+    /**
+     * Stream chat within a session
+     * Returns an async iterator for SSE events
+     *
+     * @example
+     * ```typescript
+     * for await (const event of sdk.agent.streamChat(sessionId, 'Tell me a story')) {
+     *   if (event.type === 'agentThought') {
+     *     console.log('Thinking:', event.data.thought);
+     *   } else if (event.type === 'textResponse') {
+     *     console.log('Response:', event.data.textResponse);
+     *   }
+     * }
+     * ```
+     */
+    streamChat(sessionId: string, message: string): AsyncIterableIterator<StreamChunkEvent>;
+    /**
+     * Get session information
+     *
+     * @example
+     * ```typescript
+     * const info = await sdk.agent.getSession(sessionId);
+     * console.log(`Messages sent: ${info.message_count}`);
+     * ```
+     */
+    getSession(sessionId: string): Promise<AgentSessionInfo>;
+    /**
+     * Close and delete a session
+     * Sessions auto-expire after 1 hour, but you can close them manually
+     *
+     * @example
+     * ```typescript
+     * await sdk.agent.closeSession(sessionId);
+     * ```
+     */
+    closeSession(sessionId: string): Promise<void>;
+    /**
+     * Helper: Create session and send first message in one call
+     * This is the simplest way to start chatting with an agent
+     *
+     * @example
+     * ```typescript
+     * const { session, response } = await sdk.agent.startChat('Hello agent!');
+     * console.log(response.text);
+     *
+     * // Continue chatting in the same session
+     * const reply = await sdk.agent.chat(session.session_id, 'Tell me more');
+     * ```
+     */
+    startChat(message: string, options?: AgentSessionOptions): Promise<{
+        session: AgentSession;
+        response: AgentChatResponse;
+    }>;
+}
+
 /**
  * RealtimeX Local App SDK
  *
@@ -828,11 +998,13 @@ declare class RealtimeXSDK {
     llm: LLMModule;
     tts: TTSModule;
     stt: STTModule;
+    agent: AgentModule;
     readonly appId: string;
     readonly appName: string | undefined;
     readonly apiKey: string | undefined;
     private readonly realtimexUrl;
     private readonly permissions;
+    private httpClient;
     private static DEFAULT_REALTIMEX_URL;
     constructor(config?: SDKConfig);
     /**
@@ -861,4 +1033,4 @@ declare class RealtimeXSDK {
     getAppDataDir(): Promise<string>;
 }
 
-export { ActivitiesModule, type Activity, type Agent, ApiModule, type ChatMessage, type ChatOptions, type ChatResponse, type EmbedOptions, type EmbedResponse, LLMModule, LLMPermissionError, LLMProviderError, PermissionDeniedError, PermissionRequiredError, PortModule, type Provider, type ProvidersResponse, RealtimeXSDK, type SDKConfig, type STTListenOptions, type STTModel, type STTModelsResponse, STTModule, type STTProvider, type STTProvidersResponse, type STTResponse, type StreamChunk, type TTSChunk, type TTSChunkEvent, TTSModule, type TTSOptions, type TTSProvider, type TTSProviderConfig, type TTSProvidersResponse, type Task, TaskModule, type TaskRun, type Thread, type TriggerAgentPayload, type TriggerAgentResponse, type VectorDeleteOptions, type VectorDeleteResponse, type VectorQueryOptions, type VectorQueryResponse, type VectorQueryResult, type VectorRecord, VectorStore, type VectorUpsertOptions, type VectorUpsertResponse, WebhookModule, type Workspace };
+export { ActivitiesModule, type Activity, type Agent, type AgentChatOptions, type AgentChatResponse, AgentModule, type AgentSession, type AgentSessionInfo, type AgentSessionOptions, ApiModule, type ChatContentBlock, type ChatCustomBlock, type ChatFileBlock, type ChatImageUrlBlock, type ChatMessage, type ChatMessageContent, type ChatOptions, type ChatResponse, type ChatTextBlock, type EmbedOptions, type EmbedResponse, LLMModule, LLMPermissionError, LLMProviderError, PermissionDeniedError, PermissionRequiredError, PortModule, type Provider, type ProvidersResponse, RealtimeXSDK, type SDKConfig, type STTListenOptions, type STTModel, type STTModelsResponse, STTModule, type STTProvider, type STTProvidersResponse, type STTResponse, type StreamChunk, type StreamChunkEvent, type TTSChunk, type TTSChunkEvent, TTSModule, type TTSOptions, type TTSProvider, type TTSProviderConfig, type TTSProvidersResponse, type Task, TaskModule, type TaskRun, type Thread, type TriggerAgentPayload, type TriggerAgentResponse, type VectorDeleteOptions, type VectorDeleteResponse, type VectorQueryOptions, type VectorQueryResponse, type VectorQueryResult, type VectorRecord, VectorStore, type VectorUpsertOptions, type VectorUpsertResponse, WebhookModule, type Workspace };

package/dist/index.js

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   ActivitiesModule: () => ActivitiesModule,
+  AgentModule: () => AgentModule,
   ApiModule: () => ApiModule,
   LLMModule: () => LLMModule,
   LLMPermissionError: () => LLMPermissionError,
@@ -1202,6 +1203,218 @@ var STTModule = class extends ApiModule {
   }
 };
 
+// src/modules/agent.ts
+var AgentModule = class {
+  constructor(httpClient) {
+    this.httpClient = httpClient;
+  }
+  /**
+   * Create a new agent session
+   *
+   * @example
+   * ```typescript
+   * const session = await sdk.agent.createSession({
+   *   workspace_slug: 'my-workspace',
+   *   agent_name: '@agent'
+   * });
+   * ```
+   */
+  async createSession(options) {
+    const response = await this.httpClient.fetch("/sdk/agent/session", {
+      method: "POST",
+      body: JSON.stringify(options || {})
+    });
+    const data = await response.json();
+    if (!response.ok) {
+      throw new Error(data.error || "Failed to create session");
+    }
+    return data.session;
+  }
+  /**
+   * Chat within a session (synchronous)
+   *
+   * @example
+   * ```typescript
+   * const response = await sdk.agent.chat(sessionId, 'Hello agent!');
+   * console.log(response.text);
+   * ```
+   */
+  async chat(sessionId, message) {
+    const response = await this.httpClient.fetch(`/sdk/agent/session/${sessionId}/chat`, {
+      method: "POST",
+      body: JSON.stringify({ message })
+    });
+    const data = await response.json();
+    if (!response.ok) {
+      throw new Error(data.error || "Chat request failed");
+    }
+    return data.response;
+  }
+  /**
+   * Stream chat within a session
+   * Returns an async iterator for SSE events
+   *
+   * @example
+   * ```typescript
+   * for await (const event of sdk.agent.streamChat(sessionId, 'Tell me a story')) {
+   *   if (event.type === 'agentThought') {
+   *     console.log('Thinking:', event.data.thought);
+   *   } else if (event.type === 'textResponse') {
+   *     console.log('Response:', event.data.textResponse);
+   *   }
+   * }
+   * ```
+   */
+  async *streamChat(sessionId, message) {
+    const response = await this.httpClient.fetch(`/sdk/agent/session/${sessionId}/chat/stream`, {
+      method: "POST",
+      body: JSON.stringify({ message })
+    });
+    if (!response.ok) {
+      const data = await response.json();
+      throw new Error(data.error || "Stream request failed");
+    }
+    if (!response.body) {
+      throw new Error("Response body is null");
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() || "";
+        for (const line of lines) {
+          if (line.startsWith("data: ")) {
+            const data = JSON.parse(line.slice(6));
+            yield {
+              type: data.type,
+              data
+            };
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+  /**
+   * Get session information
+   *
+   * @example
+   * ```typescript
+   * const info = await sdk.agent.getSession(sessionId);
+   * console.log(`Messages sent: ${info.message_count}`);
+   * ```
+   */
+  async getSession(sessionId) {
+    const response = await this.httpClient.fetch(`/sdk/agent/session/${sessionId}`, {
+      method: "GET"
+    });
+    const data = await response.json();
+    if (!response.ok) {
+      throw new Error(data.error || "Failed to get session info");
+    }
+    return data.session;
+  }
+  /**
+   * Close and delete a session
+   * Sessions auto-expire after 1 hour, but you can close them manually
+   *
+   * @example
+   * ```typescript
+   * await sdk.agent.closeSession(sessionId);
+   * ```
+   */
+  async closeSession(sessionId) {
+    const response = await this.httpClient.fetch(`/sdk/agent/session/${sessionId}`, {
+      method: "DELETE"
+    });
+    const data = await response.json();
+    if (!response.ok) {
+      throw new Error(data.error || "Failed to close session");
+    }
+  }
+  /**
+   * Helper: Create session and send first message in one call
+   * This is the simplest way to start chatting with an agent
+   *
+   * @example
+   * ```typescript
+   * const { session, response } = await sdk.agent.startChat('Hello agent!');
+   * console.log(response.text);
+   *
+   * // Continue chatting in the same session
+   * const reply = await sdk.agent.chat(session.session_id, 'Tell me more');
+   * ```
+   */
+  async startChat(message, options) {
+    const session = await this.createSession(options);
+    const response = await this.chat(session.session_id, message);
+    return { session, response };
+  }
+};
+
+// src/modules/http.ts
+var HttpClient = class {
+  constructor(baseUrl, appId, apiKey) {
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.appId = appId;
+    this.apiKey = apiKey;
+  }
+  getAppHeaders() {
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.appId) headers["x-app-id"] = this.appId;
+    if (this.apiKey) headers["x-api-key"] = this.apiKey;
+    return headers;
+  }
+  async getAccessToken() {
+    if (this.accessToken) return this.accessToken;
+    try {
+      const res = await fetch(`${this.baseUrl}/sdk/auth/token`, {
+        headers: this.getAppHeaders()
+      });
+      const data = await res.json();
+      if (res.ok && data.token) {
+        this.accessToken = data.token;
+        return data.token;
+      }
+    } catch (e) {
+    }
+    return "";
+  }
+  async fetch(endpoint, options = {}) {
+    const url = `${this.baseUrl}${endpoint}`;
+    let token = await this.getAccessToken();
+    const makeRequest = (authToken) => {
+      const headers = {
+        ...this.getAppHeaders(),
+        ...options.headers || {}
+      };
+      if (authToken) {
+        headers["Authorization"] = `Bearer ${authToken}`;
+      }
+      return fetch(url, { ...options, headers });
+    };
+    let response = await makeRequest(token);
+    if (response.status === 401) {
+      console.log("[RealtimeX SDK] 401 Unauthorized, refreshing access token...");
+      this.accessToken = void 0;
+      const newToken = await this.getAccessToken();
+      if (newToken && newToken !== token) {
+        console.log("[RealtimeX SDK] Retrying request with new token");
+        response = await makeRequest(newToken);
+      }
+    }
+    return response;
+  }
+};
+
 // src/index.ts
 var _RealtimeXSDK = class _RealtimeXSDK {
   constructor(config = {}) {
@@ -1213,6 +1426,7 @@ var _RealtimeXSDK = class _RealtimeXSDK {
     this.apiKey = config.realtimex?.apiKey || envApiKey;
     this.permissions = config.permissions || [];
     this.realtimexUrl = config.realtimex?.url || _RealtimeXSDK.DEFAULT_REALTIMEX_URL;
+    this.httpClient = new HttpClient(this.realtimexUrl, this.appId, this.apiKey);
     this.activities = new ActivitiesModule(this.realtimexUrl, this.appId, this.appName, this.apiKey);
     this.webhook = new WebhookModule(this.realtimexUrl, this.appName, this.appId, this.apiKey);
     this.api = new ApiModule(this.realtimexUrl, this.appId, this.appName, this.apiKey);
@@ -1221,6 +1435,7 @@ var _RealtimeXSDK = class _RealtimeXSDK {
     this.llm = new LLMModule(this.realtimexUrl, this.appId, this.appName, this.apiKey);
     this.tts = new TTSModule(this.realtimexUrl, this.appId, this.appName, this.apiKey);
     this.stt = new STTModule(this.realtimexUrl, this.appId, this.appName, this.apiKey);
+    this.agent = new AgentModule(this.httpClient);
     if (this.permissions.length > 0 && this.appId && !this.apiKey) {
       this.register().catch((err) => {
         console.error("[RealtimeX SDK] Auto-registration failed:", err.message);
@@ -1323,6 +1538,7 @@ var RealtimeXSDK = _RealtimeXSDK;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ActivitiesModule,
+  AgentModule,
   ApiModule,
   LLMModule,
   LLMPermissionError,

package/dist/index.mjs

@@ -1153,6 +1153,218 @@ var STTModule = class extends ApiModule {
   }
 };
 
+// src/modules/agent.ts
+var AgentModule = class {
+  constructor(httpClient) {
+    this.httpClient = httpClient;
+  }
+  /**
+   * Create a new agent session
+   *
+   * @example
+   * ```typescript
+   * const session = await sdk.agent.createSession({
+   *   workspace_slug: 'my-workspace',
+   *   agent_name: '@agent'
+   * });
+   * ```
+   */
+  async createSession(options) {
+    const response = await this.httpClient.fetch("/sdk/agent/session", {
+      method: "POST",
+      body: JSON.stringify(options || {})
+    });
+    const data = await response.json();
+    if (!response.ok) {
+      throw new Error(data.error || "Failed to create session");
+    }
+    return data.session;
+  }
+  /**
+   * Chat within a session (synchronous)
+   *
+   * @example
+   * ```typescript
+   * const response = await sdk.agent.chat(sessionId, 'Hello agent!');
+   * console.log(response.text);
+   * ```
+   */
+  async chat(sessionId, message) {
+    const response = await this.httpClient.fetch(`/sdk/agent/session/${sessionId}/chat`, {
+      method: "POST",
+      body: JSON.stringify({ message })
+    });
+    const data = await response.json();
+    if (!response.ok) {
+      throw new Error(data.error || "Chat request failed");
+    }
+    return data.response;
+  }
+  /**
+   * Stream chat within a session
+   * Returns an async iterator for SSE events
+   *
+   * @example
+   * ```typescript
+   * for await (const event of sdk.agent.streamChat(sessionId, 'Tell me a story')) {
+   *   if (event.type === 'agentThought') {
+   *     console.log('Thinking:', event.data.thought);
+   *   } else if (event.type === 'textResponse') {
+   *     console.log('Response:', event.data.textResponse);
+   *   }
+   * }
+   * ```
+   */
+  async *streamChat(sessionId, message) {
+    const response = await this.httpClient.fetch(`/sdk/agent/session/${sessionId}/chat/stream`, {
+      method: "POST",
+      body: JSON.stringify({ message })
+    });
+    if (!response.ok) {
+      const data = await response.json();
+      throw new Error(data.error || "Stream request failed");
+    }
+    if (!response.body) {
+      throw new Error("Response body is null");
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() || "";
+        for (const line of lines) {
+          if (line.startsWith("data: ")) {
+            const data = JSON.parse(line.slice(6));
+            yield {
+              type: data.type,
+              data
+            };
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+  /**
+   * Get session information
+   *
+   * @example
+   * ```typescript
+   * const info = await sdk.agent.getSession(sessionId);
+   * console.log(`Messages sent: ${info.message_count}`);
+   * ```
+   */
+  async getSession(sessionId) {
+    const response = await this.httpClient.fetch(`/sdk/agent/session/${sessionId}`, {
+      method: "GET"
+    });
+    const data = await response.json();
+    if (!response.ok) {
+      throw new Error(data.error || "Failed to get session info");
+    }
+    return data.session;
+  }
+  /**
+   * Close and delete a session
+   * Sessions auto-expire after 1 hour, but you can close them manually
+   *
+   * @example
+   * ```typescript
+   * await sdk.agent.closeSession(sessionId);
+   * ```
+   */
+  async closeSession(sessionId) {
+    const response = await this.httpClient.fetch(`/sdk/agent/session/${sessionId}`, {
+      method: "DELETE"
+    });
+    const data = await response.json();
+    if (!response.ok) {
+      throw new Error(data.error || "Failed to close session");
+    }
+  }
+  /**
+   * Helper: Create session and send first message in one call
+   * This is the simplest way to start chatting with an agent
+   *
+   * @example
+   * ```typescript
+   * const { session, response } = await sdk.agent.startChat('Hello agent!');
+   * console.log(response.text);
+   *
+   * // Continue chatting in the same session
+   * const reply = await sdk.agent.chat(session.session_id, 'Tell me more');
+   * ```
+   */
+  async startChat(message, options) {
+    const session = await this.createSession(options);
+    const response = await this.chat(session.session_id, message);
+    return { session, response };
+  }
+};
+
+// src/modules/http.ts
+var HttpClient = class {
+  constructor(baseUrl, appId, apiKey) {
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.appId = appId;
+    this.apiKey = apiKey;
+  }
+  getAppHeaders() {
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.appId) headers["x-app-id"] = this.appId;
+    if (this.apiKey) headers["x-api-key"] = this.apiKey;
+    return headers;
+  }
+  async getAccessToken() {
+    if (this.accessToken) return this.accessToken;
+    try {
+      const res = await fetch(`${this.baseUrl}/sdk/auth/token`, {
+        headers: this.getAppHeaders()
+      });
+      const data = await res.json();
+      if (res.ok && data.token) {
+        this.accessToken = data.token;
+        return data.token;
+      }
+    } catch (e) {
+    }
+    return "";
+  }
+  async fetch(endpoint, options = {}) {
+    const url = `${this.baseUrl}${endpoint}`;
+    let token = await this.getAccessToken();
+    const makeRequest = (authToken) => {
+      const headers = {
+        ...this.getAppHeaders(),
+        ...options.headers || {}
+      };
+      if (authToken) {
+        headers["Authorization"] = `Bearer ${authToken}`;
+      }
+      return fetch(url, { ...options, headers });
+    };
+    let response = await makeRequest(token);
+    if (response.status === 401) {
+      console.log("[RealtimeX SDK] 401 Unauthorized, refreshing access token...");
+      this.accessToken = void 0;
+      const newToken = await this.getAccessToken();
+      if (newToken && newToken !== token) {
+        console.log("[RealtimeX SDK] Retrying request with new token");
+        response = await makeRequest(newToken);
+      }
+    }
+    return response;
+  }
+};
+
 // src/index.ts
 var _RealtimeXSDK = class _RealtimeXSDK {
   constructor(config = {}) {
@@ -1164,6 +1376,7 @@ var _RealtimeXSDK = class _RealtimeXSDK {
     this.apiKey = config.realtimex?.apiKey || envApiKey;
     this.permissions = config.permissions || [];
     this.realtimexUrl = config.realtimex?.url || _RealtimeXSDK.DEFAULT_REALTIMEX_URL;
+    this.httpClient = new HttpClient(this.realtimexUrl, this.appId, this.apiKey);
     this.activities = new ActivitiesModule(this.realtimexUrl, this.appId, this.appName, this.apiKey);
     this.webhook = new WebhookModule(this.realtimexUrl, this.appName, this.appId, this.apiKey);
     this.api = new ApiModule(this.realtimexUrl, this.appId, this.appName, this.apiKey);
@@ -1172,6 +1385,7 @@ var _RealtimeXSDK = class _RealtimeXSDK {
     this.llm = new LLMModule(this.realtimexUrl, this.appId, this.appName, this.apiKey);
     this.tts = new TTSModule(this.realtimexUrl, this.appId, this.appName, this.apiKey);
     this.stt = new STTModule(this.realtimexUrl, this.appId, this.appName, this.apiKey);
+    this.agent = new AgentModule(this.httpClient);
     if (this.permissions.length > 0 && this.appId && !this.apiKey) {
       this.register().catch((err) => {
         console.error("[RealtimeX SDK] Auto-registration failed:", err.message);
@@ -1273,6 +1487,7 @@ _RealtimeXSDK.DEFAULT_REALTIMEX_URL = "http://localhost:3001";
 var RealtimeXSDK = _RealtimeXSDK;
 export {
   ActivitiesModule,
+  AgentModule,
   ApiModule,
   LLMModule,
   LLMPermissionError,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@realtimex/sdk",
-    "version": "1.3.1",
+    "version": "1.3.3",
     "description": "SDK for building Local Apps that integrate with RealtimeX",
     "main": "dist/index.js",
     "module": "dist/index.mjs",