@realtimex/sdk 1.3.5-rc.1 → 1.3.5-rc.2

package/dist/index.d.mts

@@ -1177,6 +1177,516 @@ declare class ContractModule {
     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
  *
@@ -1196,6 +1706,7 @@ declare class RealtimeXSDK {
     agent: AgentModule;
     mcp: MCPModule;
     contract: ContractModule;
+    contractRuntime: ContractRuntime;
     readonly appId: string;
     readonly appName: string | undefined;
     readonly apiKey: string | undefined;
@@ -1230,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, 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 };
+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 };