@realtimex/sdk 1.3.4 → 1.3.5-rc.2

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()
+     */
+    claimed(taskUuid: string, options?: TaskEventOptions): Promise<TaskStatusResponse>;
+    /**
+     * Mark task as processing.
+     * Backward compatible signature: start(taskUuid, machineId?)
+     */
+    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?)
      */
-    start(taskUuid: string, machineId?: string): Promise<TaskStatusResponse>;
+    complete(taskUuid: string, result?: Record<string, unknown>, machineIdOrOptions?: string | TaskEventOptions): Promise<TaskStatusResponse>;
     /**
-     * Mark task as completed with result
+     * Mark task as failed with error.
+     * Backward compatible signature: fail(taskUuid, error, machineId?)
      */
-    complete(taskUuid: string, result?: object, machineId?: string): Promise<TaskStatusResponse>;
+    fail(taskUuid: string, error: string, machineIdOrOptions?: string | TaskEventOptions): Promise<TaskStatusResponse>;
     /**
-     * Mark task as failed with error
+     * Mark task as canceled.
      */
-    fail(taskUuid: string, error: string, machineId?: string): Promise<TaskStatusResponse>;
+    cancel(taskUuid: string, reason?: string, options?: TaskEventOptions): Promise<TaskStatusResponse>;
+    private _normalizeOptions;
     private _sendEvent;
 }
 
@@ -1050,6 +1133,560 @@ 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;
+}
+
+type ProviderKind = 'gemini' | 'claude' | 'codex';
+type ContractStrictness = 'compatible' | 'strict';
+interface ContractCallbackRules {
+    event_id_header?: string;
+    signature_header?: string;
+    signature_algorithm?: string;
+    signature_message?: string;
+    attempt_id_format?: string;
+    idempotency?: string;
+}
+interface ContractCapabilityTrigger {
+    event: 'task.trigger';
+    route?: string;
+    payload_template?: Record<string, unknown>;
+}
+interface ContractCapability {
+    capability_id: string;
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+    output_schema?: Record<string, unknown>;
+    permission: string;
+    trigger: ContractCapabilityTrigger;
+}
+interface LocalAppContractV1 {
+    contract_version: 'local-app-contract/v1';
+    strictness: ContractStrictness;
+    supported_contract_events: string[];
+    supported_legacy_events?: string[];
+    aliases?: Record<string, string>;
+    status_map?: Record<string, string>;
+    legacy_action_map?: Record<string, string>;
+    callback?: ContractCallbackRules;
+    capabilities?: ContractCapability[];
+}
+interface LegacyLocalAppContractShape {
+    id?: string;
+    version?: string;
+    strictness?: ContractStrictness;
+    supported_events?: string[];
+    supported_contract_events?: string[];
+    supported_legacy_events?: string[];
+    aliases?: Record<string, string>;
+    status_map?: Record<string, string>;
+    legacy_action_map?: Record<string, string>;
+    callback?: ContractCallbackRules;
+    capabilities?: ContractCapability[];
+}
+interface ContractDiscoveryResponse {
+    success: boolean;
+    contract: LocalAppContractV1 | LegacyLocalAppContractShape;
+}
+
+interface ProjectToolsInput {
+    contract: LocalAppContractV1;
+    provider: ProviderKind;
+    appId: string;
+    namespace?: string;
+}
+interface CanonicalToolDefinition {
+    tool_name: string;
+    title: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+    output_schema?: Record<string, unknown>;
+    permission: string;
+    capability_id: string;
+    trigger: ContractCapability['trigger'];
+}
+interface HostToolAdapter<TProviderTool, TProviderToolCall, TProviderResult> {
+    toProviderTools(tools: CanonicalToolDefinition[]): TProviderTool[];
+    fromProviderToolCall(call: TProviderToolCall): {
+        tool_call_id: string;
+        tool_name: string;
+        args: Record<string, unknown>;
+    };
+    toProviderResult(result: {
+        status: 'completed' | 'failed' | 'queued';
+        tool_call_id?: string;
+        task_id?: string;
+        attempt_id?: string;
+        output?: Record<string, unknown>;
+        error?: {
+            code: string;
+            message: string;
+            retryable: boolean;
+        };
+    }): TProviderResult;
+}
+
+interface ToolCall {
+    tool_call_id: string;
+    tool_name: string;
+    args: Record<string, unknown>;
+}
+interface ExecutionContext {
+    appId: string;
+    userId: string;
+    workspaceId?: string;
+    requestId?: string;
+    idempotencyKey?: string;
+    provider?: ProviderKind;
+    namespace?: string;
+    metadata?: Record<string, unknown>;
+}
+interface ExecutionResult {
+    status: 'completed' | 'failed' | 'queued';
+    tool_call_id?: string;
+    task_id?: string;
+    attempt_id?: string;
+    output?: Record<string, unknown>;
+    error?: {
+        code: string;
+        message: string;
+        retryable: boolean;
+    };
+}
+type LifecycleEventType = 'task.claimed' | 'task.started' | 'task.progress' | 'task.completed' | 'task.failed' | 'task.canceled';
+interface RuntimeExecutionEvent {
+    tool_call_id: string;
+    task_id: string;
+    attempt_id?: string;
+    event_type: LifecycleEventType;
+    event_id: string;
+    timestamp: string;
+    payload?: Record<string, unknown>;
+}
+interface GetToolsInput {
+    appId: string;
+    provider: ProviderKind;
+    namespace?: string;
+}
+interface IngestExecutionEventInput {
+    event?: string;
+    event_type?: string;
+    event_id?: string;
+    task_id?: string;
+    task_uuid?: string;
+    attempt_id?: string | number | null;
+    tool_call_id?: string;
+    timestamp?: string;
+    payload?: Record<string, unknown>;
+    data?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface ContractRuntimeInterface {
+    getContract(appId: string): Promise<LocalAppContractV1>;
+    getTools(input: GetToolsInput): Promise<CanonicalToolDefinition[]>;
+    executeToolCall(call: ToolCall, context: ExecutionContext): Promise<ExecutionResult>;
+    onExecutionEvent(handler: (event: RuntimeExecutionEvent) => void): () => void;
+}
+
+interface RetryPolicyOptions {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+}
+declare class RetryPolicy {
+    private readonly maxAttempts;
+    private readonly baseDelayMs;
+    private readonly maxDelayMs;
+    private readonly shouldRetry;
+    constructor(options?: RetryPolicyOptions);
+    execute<T>(operation: (attempt: number) => Promise<T>): Promise<T>;
+}
+
+interface ContractRuntimeOptions {
+    baseUrl: string;
+    appId?: string;
+    appName?: string;
+    apiKey?: string;
+    permissions?: string[];
+    namespace?: string;
+    fetchImpl?: typeof fetch;
+    cacheTtlMs?: number;
+    retry?: RetryPolicyOptions;
+}
+declare class ContractRuntime implements ContractRuntimeInterface {
+    private readonly appId?;
+    private readonly appName?;
+    private readonly defaultNamespace?;
+    private readonly contractClient;
+    private readonly toolProjector;
+    private readonly executionStore;
+    private readonly lifecycleReporter;
+    private readonly scopeGuard;
+    private readonly retryPolicy;
+    private readonly httpClient;
+    constructor(options: ContractRuntimeOptions);
+    getContract(appId: string): Promise<LocalAppContractV1>;
+    getTools(input: GetToolsInput): Promise<CanonicalToolDefinition[]>;
+    executeToolCall(call: ToolCall, context: ExecutionContext): Promise<ExecutionResult>;
+    onExecutionEvent(handler: (event: RuntimeExecutionEvent) => void): () => void;
+    ingestExecutionEvent(input: IngestExecutionEventInput): RuntimeExecutionEvent | null;
+    clearCache(): void;
+    private assertAppContext;
+    private buildRegistryKey;
+    private resolveTaskId;
+    private buildTriggerRequestBody;
+    private validateToolArgs;
+    private matchesType;
+    private tryEmitLifecycleEvent;
+    private toFailedResult;
+}
+
+interface ContractHttpClientConfig {
+    baseUrl: string;
+    appId?: string;
+    appName?: string;
+    apiKey?: string;
+    fetchImpl?: typeof fetch;
+}
+declare class ContractHttpClient {
+    private readonly baseUrl;
+    private readonly appId?;
+    private readonly appName?;
+    private readonly apiKey?;
+    private readonly fetchImpl;
+    constructor(config: ContractHttpClientConfig);
+    get<T>(path: string, headers?: HeadersInit): Promise<T>;
+    post<T>(path: string, body: unknown, headers?: HeadersInit): Promise<T>;
+    request<T>(path: string, options?: RequestInit): Promise<T>;
+    private buildHeaders;
+    private parseResponse;
+}
+
+declare class ContractCache {
+    private readonly ttlMs;
+    private readonly entries;
+    constructor(ttlMs?: number);
+    get(key: string): LocalAppContractV1 | null;
+    set(key: string, value: LocalAppContractV1): void;
+    clear(key?: string): void;
+}
+
+interface ContractClientOptions {
+    cache?: ContractCache;
+    cacheKey?: string;
+}
+declare class ContractClient {
+    private readonly httpClient;
+    private readonly cache;
+    private readonly cacheKey;
+    constructor(httpClient: ContractHttpClient, options?: ContractClientOptions);
+    getLocalAppV1(forceRefresh?: boolean): Promise<LocalAppContractV1>;
+    clearCache(): void;
+}
+
+declare function normalizeLocalAppContractV1(payload: unknown): LocalAppContractV1;
+
+declare class ToolProjector {
+    project(input: ProjectToolsInput): CanonicalToolDefinition[];
+    private ensureUniqueToolName;
+}
+
+declare function normalizeSchema(schema?: Record<string, unknown>): Record<string, unknown>;
+
+declare function toStableToolName(capabilityId: string, namespace?: string): string;
+
+declare class ScopeGuard {
+    private readonly scopes;
+    constructor(scopes?: string[]);
+    can(permission?: string): boolean;
+    assert(permission?: string): void;
+}
+
+interface AuthProvider {
+    buildHeaders(baseHeaders?: Record<string, string>): Record<string, string>;
+}
+interface StaticAuthProviderOptions {
+    appId?: string;
+    appName?: string;
+    apiKey?: string;
+}
+declare class StaticAuthProvider implements AuthProvider {
+    private readonly appId?;
+    private readonly appName?;
+    private readonly apiKey?;
+    constructor(options?: StaticAuthProviderOptions);
+    buildHeaders(baseHeaders?: Record<string, string>): Record<string, string>;
+}
+
+declare class ContractError extends Error {
+    readonly code: string;
+    readonly details?: unknown;
+    constructor(code: string, message: string, details?: unknown);
+}
+declare class ContractValidationError extends ContractError {
+    constructor(message: string, details?: unknown);
+}
+declare class ToolValidationError extends ContractError {
+    constructor(message: string, details?: unknown);
+}
+declare class ToolNotFoundError extends ContractError {
+    constructor(toolName: string, details?: unknown);
+}
+declare class ScopeDeniedError extends ContractError {
+    constructor(permission: string, details?: unknown);
+}
+declare class RuntimeTransportError extends ContractError {
+    readonly statusCode?: number;
+    constructor(message: string, statusCode?: number, details?: unknown);
+}
+
+interface GeminiFunctionDeclaration {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+}
+interface GeminiToolCall {
+    id: string;
+    name: string;
+    args?: Record<string, unknown> | string;
+}
+interface GeminiToolResult {
+    tool_call_id: string;
+    status: ExecutionResult['status'];
+    payload: Record<string, unknown>;
+}
+declare class GeminiToolAdapter implements HostToolAdapter<GeminiFunctionDeclaration, GeminiToolCall, GeminiToolResult> {
+    toProviderTools(tools: CanonicalToolDefinition[]): GeminiFunctionDeclaration[];
+    fromProviderToolCall(call: GeminiToolCall): ToolCall;
+    toProviderResult(result: ExecutionResult): GeminiToolResult;
+}
+
+interface ClaudeToolDefinition {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+}
+interface ClaudeToolCall {
+    id: string;
+    name: string;
+    input?: Record<string, unknown>;
+}
+interface ClaudeToolResult {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string;
+    is_error?: boolean;
+}
+declare class ClaudeToolAdapter implements HostToolAdapter<ClaudeToolDefinition, ClaudeToolCall, ClaudeToolResult> {
+    toProviderTools(tools: CanonicalToolDefinition[]): ClaudeToolDefinition[];
+    fromProviderToolCall(call: ClaudeToolCall): ToolCall;
+    toProviderResult(result: ExecutionResult): ClaudeToolResult;
+}
+
+interface CodexToolDefinition {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+interface CodexToolCall {
+    id: string;
+    function: {
+        name: string;
+        arguments?: string | Record<string, unknown>;
+    };
+}
+interface CodexToolResult {
+    tool_call_id: string;
+    output: string;
+    is_error?: boolean;
+}
+declare class CodexToolAdapter implements HostToolAdapter<CodexToolDefinition, CodexToolCall, CodexToolResult> {
+    toProviderTools(tools: CanonicalToolDefinition[]): CodexToolDefinition[];
+    fromProviderToolCall(call: CodexToolCall): ToolCall;
+    toProviderResult(result: ExecutionResult): CodexToolResult;
+}
+
+type ACPToolKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'think' | 'fetch' | 'other';
+type ACPToolStatus = 'pending' | 'in_progress' | 'completed' | 'failed';
+interface ACPTextContent {
+    type: 'text';
+    text: string;
+}
+interface ACPSessionToolUpdate {
+    type: 'tool_call' | 'tool_call_update';
+    toolCallId: string;
+    title?: string;
+    kind?: ACPToolKind;
+    status: ACPToolStatus;
+    content?: ACPTextContent[];
+    rawInput?: Record<string, unknown>;
+    rawOutput?: Record<string, unknown>;
+    _meta?: Record<string, unknown>;
+}
+interface ACPSessionUpdateParams {
+    sessionId: string;
+    update: ACPSessionToolUpdate;
+}
+interface ACPNotifier {
+    notify(method: 'session/update', params: ACPSessionUpdateParams): Promise<void>;
+    request?<T = unknown>(method: string, params: Record<string, unknown>): Promise<T>;
+}
+interface ACPAdapterContext {
+    sessionId: string;
+    appId: string;
+    userId: string;
+    workspaceId?: string;
+    provider?: 'gemini' | 'claude' | 'codex';
+    namespace?: string;
+}
+interface ACPToolInvocation {
+    toolCallId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+    title?: string;
+    kind?: ACPToolKind;
+}
+interface ACPExecutionReference {
+    sessionId: string;
+    toolCallId: string;
+    appId: string;
+    userId: string;
+    workspaceId?: string;
+    provider?: 'gemini' | 'claude' | 'codex';
+    namespace?: string;
+    title?: string;
+    kind?: ACPToolKind;
+}
+interface PermissionOption {
+    id: string;
+    label: string;
+    kind?: 'allow_once' | 'allow_always' | 'deny_once' | 'deny_always';
+}
+interface ACPContractRuntime {
+    executeToolCall(call: ToolCall, context: ExecutionContext): Promise<ExecutionResult>;
+    onExecutionEvent(handler: (event: RuntimeExecutionEvent) => void): () => void;
+    ingestExecutionEvent(input: IngestExecutionEventInput): RuntimeExecutionEvent | null;
+}
+interface ACPContractAdapterOptions {
+    runtime: ACPContractRuntime;
+    notifier: ACPNotifier;
+    requestPermission?: boolean;
+    buildPermissionOptions?: (input: ACPToolInvocation) => PermissionOption[];
+    telemetry?: ACPAdapterTelemetrySink;
+}
+interface ACPAdapterTelemetryEvent {
+    phase: 'execute' | 'notify' | 'permission' | 'runtime_event' | 'ingest';
+    result: 'ok' | 'failed' | 'skipped';
+    sessionId?: string;
+    toolCallId?: string;
+    toolName?: string;
+    taskId?: string;
+    attemptId?: string;
+    eventId?: string;
+    eventType?: string;
+    status?: ACPToolStatus;
+    error?: string;
+    metadata?: Record<string, unknown>;
+}
+interface ACPAdapterTelemetrySink {
+    emit(event: ACPAdapterTelemetryEvent): void | Promise<void>;
+}
+
+declare class ACPContractAdapter {
+    private readonly runtime;
+    private readonly notifier;
+    private readonly mapper;
+    private readonly permissionBridge;
+    private readonly telemetry;
+    private readonly taskReferences;
+    private readonly toolCallReferences;
+    private readonly runtimeUnsubscribe;
+    constructor(options: ACPContractAdapterOptions);
+    dispose(): void;
+    executeTool(invocation: ACPToolInvocation, context: ACPAdapterContext): Promise<ExecutionResult>;
+    ingestContractCallback(payload: Record<string, unknown>, context: Pick<ACPAdapterContext, 'sessionId'>): RuntimeExecutionEvent | null;
+    private handleRuntimeEvent;
+    private resolveReferenceForEvent;
+    private rememberReference;
+    private cleanupReference;
+    private notify;
+}
+
+declare class ACPEventMapper {
+    createReference(invocation: ACPToolInvocation, context: ACPAdapterContext): ACPExecutionReference;
+    buildPendingUpdate(invocation: ACPToolInvocation, reference: ACPExecutionReference): ACPSessionUpdateParams;
+    buildResultUpdate(result: ExecutionResult, reference: ACPExecutionReference): ACPSessionUpdateParams;
+    buildLifecycleUpdate(event: RuntimeExecutionEvent, reference: ACPExecutionReference): ACPSessionUpdateParams | null;
+    buildNotifyFailureUpdate(reference: ACPExecutionReference, error: unknown): ACPSessionUpdateParams;
+    mapContractEventStatus(eventType: string): ACPToolStatus | null;
+    private mapExecutionResultStatus;
+    private resolveEventText;
+}
+
+interface ACPPermissionBridgeOptions {
+    notifier: ACPNotifier;
+    enabled: boolean;
+    buildPermissionOptions?: (input: ACPToolInvocation) => PermissionOption[];
+}
+declare class ACPPermissionBridge {
+    private readonly notifier;
+    private readonly enabled;
+    private readonly buildPermissionOptions?;
+    constructor(options: ACPPermissionBridgeOptions);
+    requestToolPermission(invocation: ACPToolInvocation, context: ACPAdapterContext): Promise<boolean>;
+}
+
+declare class ACPTelemetry {
+    private readonly sink?;
+    constructor(sink?: ACPAdapterTelemetrySink);
+    emit(event: ACPAdapterTelemetryEvent): void;
+}
+
 /**
  * RealtimeX Local App SDK
  *
@@ -1068,6 +1705,8 @@ declare class RealtimeXSDK {
     stt: STTModule;
     agent: AgentModule;
     mcp: MCPModule;
+    contract: ContractModule;
+    contractRuntime: ContractRuntime;
     readonly appId: string;
     readonly appName: string | undefined;
     readonly apiKey: string | undefined;
@@ -1102,4 +1741,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 { type ACPAdapterContext, type ACPAdapterTelemetryEvent, type ACPAdapterTelemetrySink, ACPContractAdapter, type ACPContractAdapterOptions, type ACPContractRuntime, ACPEventMapper, type ACPExecutionReference, type ACPNotifier, ACPPermissionBridge, type ACPSessionToolUpdate, type ACPSessionUpdateParams, ACPTelemetry, type ACPTextContent, type ACPToolInvocation, type ACPToolKind, type ACPToolStatus, ActivitiesModule, type Activity, type Agent, type AgentChatOptions, type AgentChatResponse, AgentModule, type AgentSession, type AgentSessionInfo, type AgentSessionOptions, ApiModule, type AuthProvider, CONTRACT_ATTEMPT_PREFIX, CONTRACT_EVENT_ID_HEADER, CONTRACT_SIGNATURE_ALGORITHM, CONTRACT_SIGNATURE_HEADER, type CanonicalToolDefinition, type ChatContentBlock, type ChatCustomBlock, type ChatFileBlock, type ChatImageUrlBlock, type ChatMessage, type ChatMessageContent, type ChatOptions, type ChatResponse, type ChatTextBlock, ClaudeToolAdapter, type ClaudeToolCall, type ClaudeToolDefinition, type ClaudeToolResult, CodexToolAdapter, type CodexToolCall, type CodexToolDefinition, type CodexToolResult, ContractCache, type ContractCallbackMetadata, type ContractCallbackRules, type ContractCapability, type ContractCapabilityTrigger, ContractClient, type ContractClientOptions, type ContractDiscoveryResponse, ContractError, type ContractEventType, ContractHttpClient, type ContractHttpClientConfig, ContractModule, ContractRuntime, type ContractRuntimeInterface, type ContractRuntimeOptions, type ContractSignInput, type ContractStrictness, ContractValidationError, type EmbedOptions, type EmbedResponse, type ExecutionContext, type ExecutionResult, type GeminiFunctionDeclaration, GeminiToolAdapter, type GeminiToolCall, type GeminiToolResult, type GetToolsInput, type HostToolAdapter, type IngestExecutionEventInput, LLMModule, LLMPermissionError, LLMProviderError, LOCAL_APP_CONTRACT_VERSION, type LegacyLocalAppContractShape, type LifecycleEventType, type LocalAppContractDefinition, type LocalAppContractResponse, type LocalAppContractV1, MCPModule, type MCPServer, type MCPTool, type MCPToolResult, PermissionDeniedError, type PermissionOption, PermissionRequiredError, PortModule, type ProjectToolsInput, type Provider, type ProviderKind, type ProvidersResponse, RealtimeXSDK, RetryPolicy, type RetryPolicyOptions, type RuntimeExecutionEvent, RuntimeTransportError, type SDKConfig, type STTListenOptions, type STTModel, type STTModelsResponse, STTModule, type STTProvider, type STTProvidersResponse, type STTResponse, ScopeDeniedError, ScopeGuard, StaticAuthProvider, type StaticAuthProviderOptions, 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 ToolCall, ToolNotFoundError, ToolProjector, ToolValidationError, 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, normalizeLocalAppContractV1, normalizeSchema, parseAttemptRunId, signContractEvent, toStableToolName };