@realtimex/sdk 1.3.3 → 1.3.5-rc.1

package/README.md

@@ -108,6 +108,67 @@ await sdk.webhook.triggerAgent({
 });
 ```
 
+### Contract Discovery
+
+```typescript
+// Read canonical contract metadata published by Main App
+const contract = await sdk.contract.getLocalAppV1();
+
+console.log(contract.version); // local-app-contract/v1
+console.log(contract.supported_events); // task.trigger, task.claimed, ...
+console.log(contract.callback?.signature_header); // x-rtx-contract-signature
+```
+
+### Worker Callback Lifecycle
+
+Use this when your worker receives `task_uuid`, `attempt_id`, and callback metadata from RealtimeX task context.
+
+```typescript
+sdk.task.configureContract({
+  callbackSecret: process.env.RTX_CONTRACT_CALLBACK_SECRET,
+  signCallbacksByDefault: true,
+});
+
+await sdk.task.claim(taskUuid, {
+  callbackUrl,
+  machineId,
+  attemptId,
+  userEmail,
+});
+
+await sdk.task.start(taskUuid, {
+  callbackUrl,
+  machineId,
+  attemptId,
+});
+
+await sdk.task.progress(taskUuid, { percent: 50, message: 'Halfway done' }, {
+  callbackUrl,
+  machineId,
+  attemptId,
+});
+
+await sdk.task.complete(taskUuid, { summary: 'Done' }, {
+  callbackUrl,
+  machineId,
+  attemptId,
+});
+```
+
+`TaskModule` auto-populates:
+- `event_id` for idempotency
+- canonical `event` names
+- optional HMAC signature header (`x-rtx-contract-signature`) when signing is enabled
+- legacy `action` alongside canonical `event` for compatibility when posting to callback URLs
+
+### Contract Compatibility Check
+
+Run the cross-language harness (Main App endpoint + TypeScript SDK + Python SDK):
+
+```bash
+RTX_API_KEY=sk-... RTX_CONTRACT_VERIFY_BASE_URL=http://127.0.0.1:3001 npm run contract:verify
+```
+
 ### Public APIs
 
 ```typescript

package/dist/index.d.mts

@@ -10,6 +10,10 @@ interface SDKConfig {
     };
     defaultPort?: number;
     permissions?: string[];
+    contract?: {
+        callbackSecret?: string;
+        signCallbacksByDefault?: boolean;
+    };
 }
 interface Activity {
     id: string;
@@ -30,15 +34,46 @@ interface TriggerAgentPayload {
     workspace_slug?: string;
     thread_slug?: string;
     prompt?: string;
+    event_id?: string;
+    attempt_id?: string | number;
 }
 interface TriggerAgentResponse {
     success: boolean;
     task_uuid?: string;
+    task_id?: string;
+    event_id?: string;
+    attempt_id?: string;
+    event_type?: ContractEventType | string;
+    contract_version?: string;
     calendar_event_uuid?: string;
     auto_run?: boolean;
     message?: string;
     error?: string;
 }
+type ContractEventType = 'task.trigger' | 'system.ping' | 'task.claimed' | 'task.started' | 'task.progress' | 'task.completed' | 'task.failed' | 'task.canceled';
+interface ContractCallbackMetadata {
+    event_id_header?: string;
+    signature_header?: string;
+    signature_algorithm?: string;
+    signature_message?: string;
+    attempt_id_format?: string;
+    idempotency?: string;
+}
+interface LocalAppContractDefinition {
+    id: string;
+    version: string;
+    events: Record<string, ContractEventType>;
+    supported_events: ContractEventType[];
+    supported_legacy_events: string[];
+    aliases: Record<string, ContractEventType>;
+    status_map: Record<string, string>;
+    legacy_action_map: Record<ContractEventType, string>;
+    callback?: ContractCallbackMetadata;
+}
+interface LocalAppContractResponse {
+    success: boolean;
+    contract: LocalAppContractDefinition;
+}
 interface Agent {
     slug: string;
     name: string;
@@ -60,6 +95,7 @@ interface Thread {
 }
 interface TaskRun {
     id: number;
+    attempt_id?: string;
     agent_name: string;
     workspace_slug: string;
     thread_slug?: string;
@@ -300,30 +336,77 @@ declare class ApiModule {
  * Task Module - Report task status to RealtimeX
  * Used by external agents/processors to update task status
  */
+
 interface TaskStatusResponse {
     success: boolean;
     task_uuid: string;
     status: string;
+    event_id?: string;
+    attempt_id?: string;
+    event_type?: ContractEventType | string;
+    deduplicated?: boolean;
+    duplicate?: boolean;
     message?: string;
 }
+interface TaskEventOptions {
+    machineId?: string;
+    attemptId?: string | number;
+    eventId?: string;
+    timestamp?: string;
+    callbackUrl?: string;
+    callbackSecret?: string;
+    sign?: boolean;
+    userEmail?: string;
+    activityId?: string;
+    tableName?: string;
+}
 declare class TaskModule {
     private realtimexUrl;
     private appName?;
     private appId?;
     private apiKey?;
+    private callbackSecret?;
+    private signCallbacksByDefault;
     constructor(realtimexUrl: string, appName?: string, appId?: string, apiKey?: string);
     /**
-     * Mark task as processing
+     * Configure callback signing behavior.
+     */
+    configureContract(config: {
+        callbackSecret?: string;
+        signCallbacksByDefault?: boolean;
+    }): void;
+    /**
+     * Claim a task before processing.
+     */
+    claim(taskUuid: string, options?: TaskEventOptions): Promise<TaskStatusResponse>;
+    /**
+     * Alias for claim()
      */
-    start(taskUuid: string, machineId?: string): Promise<TaskStatusResponse>;
+    claimed(taskUuid: string, options?: TaskEventOptions): Promise<TaskStatusResponse>;
     /**
-     * Mark task as completed with result
+     * Mark task as processing.
+     * Backward compatible signature: start(taskUuid, machineId?)
      */
-    complete(taskUuid: string, result?: object, machineId?: string): Promise<TaskStatusResponse>;
+    start(taskUuid: string, machineIdOrOptions?: string | TaskEventOptions): Promise<TaskStatusResponse>;
     /**
-     * Mark task as failed with error
+     * Report incremental task progress.
      */
-    fail(taskUuid: string, error: string, machineId?: string): Promise<TaskStatusResponse>;
+    progress(taskUuid: string, progressData?: Record<string, unknown>, options?: TaskEventOptions): Promise<TaskStatusResponse>;
+    /**
+     * Mark task as completed with result.
+     * Backward compatible signature: complete(taskUuid, result?, machineId?)
+     */
+    complete(taskUuid: string, result?: Record<string, unknown>, machineIdOrOptions?: string | TaskEventOptions): Promise<TaskStatusResponse>;
+    /**
+     * Mark task as failed with error.
+     * Backward compatible signature: fail(taskUuid, error, machineId?)
+     */
+    fail(taskUuid: string, error: string, machineIdOrOptions?: string | TaskEventOptions): Promise<TaskStatusResponse>;
+    /**
+     * Mark task as canceled.
+     */
+    cancel(taskUuid: string, reason?: string, options?: TaskEventOptions): Promise<TaskStatusResponse>;
+    private _normalizeOptions;
     private _sendEvent;
 }
 
@@ -982,6 +1065,118 @@ declare class AgentModule {
     }>;
 }
 
+/**
+ * MCP Module - Interact with MCP servers via RealtimeX SDK
+ */
+
+interface MCPServer {
+    /** Unique server name (slug) */
+    name: string;
+    /** User-friendly display name */
+    display_name: string;
+    /** Server description */
+    description: string | null;
+    /** Server type: 'stdio', 'http', 'sse', or 'remote' */
+    server_type: string;
+    /** Whether the server is enabled */
+    enabled: boolean;
+    /** Provider: 'local' or 'remote' */
+    provider: 'local' | 'remote';
+    /** Tags / categories */
+    tags: string[];
+}
+interface MCPTool {
+    /** Tool name */
+    name: string;
+    /** Tool description */
+    description: string | null;
+    /** JSON Schema describing the tool's input parameters */
+    input_schema: Record<string, any>;
+}
+interface MCPToolResult {
+    /** Whether the execution was successful */
+    success: boolean;
+    /** Server that executed the tool */
+    server: string;
+    /** Tool that was executed */
+    tool: string;
+    /** Provider used */
+    provider: string;
+    /** Execution result data */
+    result: any;
+    /** Error message if failed */
+    error?: string;
+}
+declare class MCPModule extends ApiModule {
+    constructor(realtimexUrl: string, appId: string, appName?: string, apiKey?: string);
+    /**
+     * List configured MCP servers.
+     * @param provider - Filter by provider: 'local', 'remote', or 'all' (default: 'all')
+     * @returns Array of MCP server objects
+     */
+    getServers(provider?: 'local' | 'remote' | 'all'): Promise<MCPServer[]>;
+    /**
+     * List available tools for a specific MCP server.
+     * @param serverName - The server name (slug)
+     * @param provider - Provider: 'local' or 'remote' (default: 'local')
+     * @returns Array of tool objects with name, description, and input schema
+     */
+    getTools(serverName: string, provider?: 'local' | 'remote'): Promise<MCPTool[]>;
+    /**
+     * Execute a tool on an MCP server.
+     * @param serverName - The server name (slug)
+     * @param toolName - The tool name to execute
+     * @param args - Arguments to pass to the tool (matches tool's input_schema)
+     * @param provider - Provider: 'local' or 'remote' (default: 'local')
+     * @returns Tool execution result
+     */
+    executeTool(serverName: string, toolName: string, args?: Record<string, any>, provider?: 'local' | 'remote'): Promise<any>;
+}
+
+declare const LOCAL_APP_CONTRACT_VERSION = "local-app-contract/v1";
+declare const CONTRACT_SIGNATURE_HEADER = "x-rtx-contract-signature";
+declare const CONTRACT_EVENT_ID_HEADER = "x-rtx-event-id";
+declare const CONTRACT_SIGNATURE_ALGORITHM = "sha256";
+declare const CONTRACT_ATTEMPT_PREFIX = "run-";
+interface ContractSignInput {
+    secret: string;
+    eventId?: string;
+    eventType: ContractEventType | string;
+    taskId: string;
+    attemptId?: string | number | null;
+    timestamp?: string | null;
+    payload?: unknown;
+}
+declare function normalizeContractEvent(eventLike?: string | null): ContractEventType | null;
+declare function normalizeAttemptId(attemptLike?: string | number | null): string | undefined;
+declare function parseAttemptRunId(attemptLike?: string | number | null): number | null;
+declare function hashContractPayload(payload: unknown): string;
+declare function createContractEventId(): string;
+declare function buildContractSignatureMessage({ eventId, eventType, taskId, attemptId, timestamp, payload, }: Omit<ContractSignInput, 'secret'>): string;
+declare function signContractEvent(input: ContractSignInput): string;
+declare function canonicalEventToLegacyAction(eventLike: string): string | null;
+declare function buildContractIdempotencyKey({ taskId, eventType, eventId, attemptId, machineId, timestamp, payload, }: {
+    taskId: string;
+    eventType: string;
+    eventId?: string | null;
+    attemptId?: string | number | null;
+    machineId?: string | null;
+    timestamp?: string | null;
+    payload?: unknown;
+}): string;
+declare class ContractModule {
+    private readonly realtimexUrl;
+    private readonly appName?;
+    private readonly appId?;
+    private readonly apiKey?;
+    private cachedContract;
+    constructor(realtimexUrl: string, appName?: string, appId?: string, apiKey?: string);
+    private requestPermission;
+    private request;
+    getLocalAppV1(forceRefresh?: boolean): Promise<LocalAppContractDefinition>;
+    clearCache(): void;
+}
+
 /**
  * RealtimeX Local App SDK
  *
@@ -999,6 +1194,8 @@ declare class RealtimeXSDK {
     tts: TTSModule;
     stt: STTModule;
     agent: AgentModule;
+    mcp: MCPModule;
+    contract: ContractModule;
     readonly appId: string;
     readonly appName: string | undefined;
     readonly apiKey: string | undefined;
@@ -1033,4 +1230,4 @@ declare class RealtimeXSDK {
     getAppDataDir(): Promise<string>;
 }
 
-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 };
+export { ActivitiesModule, type Activity, type Agent, type AgentChatOptions, type AgentChatResponse, AgentModule, type AgentSession, type AgentSessionInfo, type AgentSessionOptions, ApiModule, CONTRACT_ATTEMPT_PREFIX, CONTRACT_EVENT_ID_HEADER, CONTRACT_SIGNATURE_ALGORITHM, CONTRACT_SIGNATURE_HEADER, type ChatContentBlock, type ChatCustomBlock, type ChatFileBlock, type ChatImageUrlBlock, type ChatMessage, type ChatMessageContent, type ChatOptions, type ChatResponse, type ChatTextBlock, type ContractCallbackMetadata, type ContractEventType, ContractModule, type ContractSignInput, type EmbedOptions, type EmbedResponse, LLMModule, LLMPermissionError, LLMProviderError, LOCAL_APP_CONTRACT_VERSION, type LocalAppContractDefinition, type LocalAppContractResponse, MCPModule, type MCPServer, type MCPTool, type MCPToolResult, 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, buildContractIdempotencyKey, buildContractSignatureMessage, canonicalEventToLegacyAction, createContractEventId, hashContractPayload, normalizeAttemptId, normalizeContractEvent, parseAttemptRunId, signContractEvent };

package/dist/index.d.ts

@@ -10,6 +10,10 @@ interface SDKConfig {
     };
     defaultPort?: number;
     permissions?: string[];
+    contract?: {
+        callbackSecret?: string;
+        signCallbacksByDefault?: boolean;
+    };
 }
 interface Activity {
     id: string;
@@ -30,15 +34,46 @@ interface TriggerAgentPayload {
     workspace_slug?: string;
     thread_slug?: string;
     prompt?: string;
+    event_id?: string;
+    attempt_id?: string | number;
 }
 interface TriggerAgentResponse {
     success: boolean;
     task_uuid?: string;
+    task_id?: string;
+    event_id?: string;
+    attempt_id?: string;
+    event_type?: ContractEventType | string;
+    contract_version?: string;
     calendar_event_uuid?: string;
     auto_run?: boolean;
     message?: string;
     error?: string;
 }
+type ContractEventType = 'task.trigger' | 'system.ping' | 'task.claimed' | 'task.started' | 'task.progress' | 'task.completed' | 'task.failed' | 'task.canceled';
+interface ContractCallbackMetadata {
+    event_id_header?: string;
+    signature_header?: string;
+    signature_algorithm?: string;
+    signature_message?: string;
+    attempt_id_format?: string;
+    idempotency?: string;
+}
+interface LocalAppContractDefinition {
+    id: string;
+    version: string;
+    events: Record<string, ContractEventType>;
+    supported_events: ContractEventType[];
+    supported_legacy_events: string[];
+    aliases: Record<string, ContractEventType>;
+    status_map: Record<string, string>;
+    legacy_action_map: Record<ContractEventType, string>;
+    callback?: ContractCallbackMetadata;
+}
+interface LocalAppContractResponse {
+    success: boolean;
+    contract: LocalAppContractDefinition;
+}
 interface Agent {
     slug: string;
     name: string;
@@ -60,6 +95,7 @@ interface Thread {
 }
 interface TaskRun {
     id: number;
+    attempt_id?: string;
     agent_name: string;
     workspace_slug: string;
     thread_slug?: string;
@@ -300,30 +336,77 @@ declare class ApiModule {
  * Task Module - Report task status to RealtimeX
  * Used by external agents/processors to update task status
  */
+
 interface TaskStatusResponse {
     success: boolean;
     task_uuid: string;
     status: string;
+    event_id?: string;
+    attempt_id?: string;
+    event_type?: ContractEventType | string;
+    deduplicated?: boolean;
+    duplicate?: boolean;
     message?: string;
 }
+interface TaskEventOptions {
+    machineId?: string;
+    attemptId?: string | number;
+    eventId?: string;
+    timestamp?: string;
+    callbackUrl?: string;
+    callbackSecret?: string;
+    sign?: boolean;
+    userEmail?: string;
+    activityId?: string;
+    tableName?: string;
+}
 declare class TaskModule {
     private realtimexUrl;
     private appName?;
     private appId?;
     private apiKey?;
+    private callbackSecret?;
+    private signCallbacksByDefault;
     constructor(realtimexUrl: string, appName?: string, appId?: string, apiKey?: string);
     /**
-     * Mark task as processing
+     * Configure callback signing behavior.
+     */
+    configureContract(config: {
+        callbackSecret?: string;
+        signCallbacksByDefault?: boolean;
+    }): void;
+    /**
+     * Claim a task before processing.
+     */
+    claim(taskUuid: string, options?: TaskEventOptions): Promise<TaskStatusResponse>;
+    /**
+     * Alias for claim()
      */
-    start(taskUuid: string, machineId?: string): Promise<TaskStatusResponse>;
+    claimed(taskUuid: string, options?: TaskEventOptions): Promise<TaskStatusResponse>;
     /**
-     * Mark task as completed with result
+     * Mark task as processing.
+     * Backward compatible signature: start(taskUuid, machineId?)
      */
-    complete(taskUuid: string, result?: object, machineId?: string): Promise<TaskStatusResponse>;
+    start(taskUuid: string, machineIdOrOptions?: string | TaskEventOptions): Promise<TaskStatusResponse>;
     /**
-     * Mark task as failed with error
+     * Report incremental task progress.
      */
-    fail(taskUuid: string, error: string, machineId?: string): Promise<TaskStatusResponse>;
+    progress(taskUuid: string, progressData?: Record<string, unknown>, options?: TaskEventOptions): Promise<TaskStatusResponse>;
+    /**
+     * Mark task as completed with result.
+     * Backward compatible signature: complete(taskUuid, result?, machineId?)
+     */
+    complete(taskUuid: string, result?: Record<string, unknown>, machineIdOrOptions?: string | TaskEventOptions): Promise<TaskStatusResponse>;
+    /**
+     * Mark task as failed with error.
+     * Backward compatible signature: fail(taskUuid, error, machineId?)
+     */
+    fail(taskUuid: string, error: string, machineIdOrOptions?: string | TaskEventOptions): Promise<TaskStatusResponse>;
+    /**
+     * Mark task as canceled.
+     */
+    cancel(taskUuid: string, reason?: string, options?: TaskEventOptions): Promise<TaskStatusResponse>;
+    private _normalizeOptions;
     private _sendEvent;
 }
 
@@ -982,6 +1065,118 @@ declare class AgentModule {
     }>;
 }
 
+/**
+ * MCP Module - Interact with MCP servers via RealtimeX SDK
+ */
+
+interface MCPServer {
+    /** Unique server name (slug) */
+    name: string;
+    /** User-friendly display name */
+    display_name: string;
+    /** Server description */
+    description: string | null;
+    /** Server type: 'stdio', 'http', 'sse', or 'remote' */
+    server_type: string;
+    /** Whether the server is enabled */
+    enabled: boolean;
+    /** Provider: 'local' or 'remote' */
+    provider: 'local' | 'remote';
+    /** Tags / categories */
+    tags: string[];
+}
+interface MCPTool {
+    /** Tool name */
+    name: string;
+    /** Tool description */
+    description: string | null;
+    /** JSON Schema describing the tool's input parameters */
+    input_schema: Record<string, any>;
+}
+interface MCPToolResult {
+    /** Whether the execution was successful */
+    success: boolean;
+    /** Server that executed the tool */
+    server: string;
+    /** Tool that was executed */
+    tool: string;
+    /** Provider used */
+    provider: string;
+    /** Execution result data */
+    result: any;
+    /** Error message if failed */
+    error?: string;
+}
+declare class MCPModule extends ApiModule {
+    constructor(realtimexUrl: string, appId: string, appName?: string, apiKey?: string);
+    /**
+     * List configured MCP servers.
+     * @param provider - Filter by provider: 'local', 'remote', or 'all' (default: 'all')
+     * @returns Array of MCP server objects
+     */
+    getServers(provider?: 'local' | 'remote' | 'all'): Promise<MCPServer[]>;
+    /**
+     * List available tools for a specific MCP server.
+     * @param serverName - The server name (slug)
+     * @param provider - Provider: 'local' or 'remote' (default: 'local')
+     * @returns Array of tool objects with name, description, and input schema
+     */
+    getTools(serverName: string, provider?: 'local' | 'remote'): Promise<MCPTool[]>;
+    /**
+     * Execute a tool on an MCP server.
+     * @param serverName - The server name (slug)
+     * @param toolName - The tool name to execute
+     * @param args - Arguments to pass to the tool (matches tool's input_schema)
+     * @param provider - Provider: 'local' or 'remote' (default: 'local')
+     * @returns Tool execution result
+     */
+    executeTool(serverName: string, toolName: string, args?: Record<string, any>, provider?: 'local' | 'remote'): Promise<any>;
+}
+
+declare const LOCAL_APP_CONTRACT_VERSION = "local-app-contract/v1";
+declare const CONTRACT_SIGNATURE_HEADER = "x-rtx-contract-signature";
+declare const CONTRACT_EVENT_ID_HEADER = "x-rtx-event-id";
+declare const CONTRACT_SIGNATURE_ALGORITHM = "sha256";
+declare const CONTRACT_ATTEMPT_PREFIX = "run-";
+interface ContractSignInput {
+    secret: string;
+    eventId?: string;
+    eventType: ContractEventType | string;
+    taskId: string;
+    attemptId?: string | number | null;
+    timestamp?: string | null;
+    payload?: unknown;
+}
+declare function normalizeContractEvent(eventLike?: string | null): ContractEventType | null;
+declare function normalizeAttemptId(attemptLike?: string | number | null): string | undefined;
+declare function parseAttemptRunId(attemptLike?: string | number | null): number | null;
+declare function hashContractPayload(payload: unknown): string;
+declare function createContractEventId(): string;
+declare function buildContractSignatureMessage({ eventId, eventType, taskId, attemptId, timestamp, payload, }: Omit<ContractSignInput, 'secret'>): string;
+declare function signContractEvent(input: ContractSignInput): string;
+declare function canonicalEventToLegacyAction(eventLike: string): string | null;
+declare function buildContractIdempotencyKey({ taskId, eventType, eventId, attemptId, machineId, timestamp, payload, }: {
+    taskId: string;
+    eventType: string;
+    eventId?: string | null;
+    attemptId?: string | number | null;
+    machineId?: string | null;
+    timestamp?: string | null;
+    payload?: unknown;
+}): string;
+declare class ContractModule {
+    private readonly realtimexUrl;
+    private readonly appName?;
+    private readonly appId?;
+    private readonly apiKey?;
+    private cachedContract;
+    constructor(realtimexUrl: string, appName?: string, appId?: string, apiKey?: string);
+    private requestPermission;
+    private request;
+    getLocalAppV1(forceRefresh?: boolean): Promise<LocalAppContractDefinition>;
+    clearCache(): void;
+}
+
 /**
  * RealtimeX Local App SDK
  *
@@ -999,6 +1194,8 @@ declare class RealtimeXSDK {
     tts: TTSModule;
     stt: STTModule;
     agent: AgentModule;
+    mcp: MCPModule;
+    contract: ContractModule;
     readonly appId: string;
     readonly appName: string | undefined;
     readonly apiKey: string | undefined;
@@ -1033,4 +1230,4 @@ declare class RealtimeXSDK {
     getAppDataDir(): Promise<string>;
 }
 
-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 };
+export { ActivitiesModule, type Activity, type Agent, type AgentChatOptions, type AgentChatResponse, AgentModule, type AgentSession, type AgentSessionInfo, type AgentSessionOptions, ApiModule, CONTRACT_ATTEMPT_PREFIX, CONTRACT_EVENT_ID_HEADER, CONTRACT_SIGNATURE_ALGORITHM, CONTRACT_SIGNATURE_HEADER, type ChatContentBlock, type ChatCustomBlock, type ChatFileBlock, type ChatImageUrlBlock, type ChatMessage, type ChatMessageContent, type ChatOptions, type ChatResponse, type ChatTextBlock, type ContractCallbackMetadata, type ContractEventType, ContractModule, type ContractSignInput, type EmbedOptions, type EmbedResponse, LLMModule, LLMPermissionError, LLMProviderError, LOCAL_APP_CONTRACT_VERSION, type LocalAppContractDefinition, type LocalAppContractResponse, MCPModule, type MCPServer, type MCPTool, type MCPToolResult, 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, buildContractIdempotencyKey, buildContractSignatureMessage, canonicalEventToLegacyAction, createContractEventId, hashContractPayload, normalizeAttemptId, normalizeContractEvent, parseAttemptRunId, signContractEvent };