@realtimex/sdk 1.3.4 → 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.
      */
-    start(taskUuid: string, machineId?: string): Promise<TaskStatusResponse>;
+    claim(taskUuid: string, options?: TaskEventOptions): Promise<TaskStatusResponse>;
     /**
-     * Mark task as completed with result
+     * Alias for claim()
      */
-    complete(taskUuid: string, result?: object, machineId?: string): Promise<TaskStatusResponse>;
+    claimed(taskUuid: string, options?: TaskEventOptions): Promise<TaskStatusResponse>;
     /**
-     * Mark task as failed with error
+     * Mark task as processing.
+     * Backward compatible signature: start(taskUuid, machineId?)
      */
-    fail(taskUuid: string, error: string, machineId?: string): Promise<TaskStatusResponse>;
+    start(taskUuid: string, machineIdOrOptions?: string | TaskEventOptions): Promise<TaskStatusResponse>;
+    /**
+     * Report incremental task progress.
+     */
+    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;
 }
 
@@ -1050,6 +1133,50 @@ declare class MCPModule extends ApiModule {
     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
  *
@@ -1068,6 +1195,7 @@ declare class RealtimeXSDK {
     stt: STTModule;
     agent: AgentModule;
     mcp: MCPModule;
+    contract: ContractModule;
     readonly appId: string;
     readonly appName: string | undefined;
     readonly apiKey: string | undefined;
@@ -1102,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, 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 };
+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.
      */
-    start(taskUuid: string, machineId?: string): Promise<TaskStatusResponse>;
+    claim(taskUuid: string, options?: TaskEventOptions): Promise<TaskStatusResponse>;
     /**
-     * Mark task as completed with result
+     * Alias for claim()
      */
-    complete(taskUuid: string, result?: object, machineId?: string): Promise<TaskStatusResponse>;
+    claimed(taskUuid: string, options?: TaskEventOptions): Promise<TaskStatusResponse>;
     /**
-     * Mark task as failed with error
+     * Mark task as processing.
+     * Backward compatible signature: start(taskUuid, machineId?)
      */
-    fail(taskUuid: string, error: string, machineId?: string): Promise<TaskStatusResponse>;
+    start(taskUuid: string, machineIdOrOptions?: string | TaskEventOptions): Promise<TaskStatusResponse>;
+    /**
+     * Report incremental task progress.
+     */
+    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;
 }
 
@@ -1050,6 +1133,50 @@ declare class MCPModule extends ApiModule {
     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
  *
@@ -1068,6 +1195,7 @@ declare class RealtimeXSDK {
     stt: STTModule;
     agent: AgentModule;
     mcp: MCPModule;
+    contract: ContractModule;
     readonly appId: string;
     readonly appName: string | undefined;
     readonly apiKey: string | undefined;
@@ -1102,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, 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 };
+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 };