@realtimex/sdk 1.3.7-rc.1 → 1.4.0

package/dist/index.d.mts

@@ -1117,6 +1117,134 @@ declare class AgentModule {
     }>;
 }
 
+/**
+ * ACP Agent Module — CLI-based agent sessions via ACP bridge
+ *
+ * Provides session lifecycle, sync/streaming chat, permission resolution,
+ * and turn control for CLI agents (Claude, Gemini, Codex, etc.).
+ *
+ * Unlike AgentModule (LLM API-based), ACP agents spawn CLI processes
+ * and can execute commands, read/write files, and interact with tools.
+ */
+
+interface AcpAgentInfo {
+    id: string;
+    label: string;
+    handles: string[];
+    installed: boolean;
+    authReady: boolean;
+    version?: string | null;
+    status: "installed" | "not_installed";
+    /** Present when listAgents({ includeModels: true }). */
+    models?: Array<{
+        id: string;
+        name?: string;
+    }>;
+    /** "provider_api" | "fallback" — how models were resolved. */
+    source?: string | null;
+    /** Non-null if model fetch failed and fell back. */
+    error?: string | null;
+}
+interface AcpSessionOptions {
+    agent_id: string;
+    cwd?: string;
+    label?: string;
+    model?: string;
+    approvalPolicy?: "approve-all" | "approve-reads" | "deny-all";
+}
+interface AcpSession {
+    session_key: string;
+    agent_id: string;
+    state: "initializing" | "ready" | "stale" | "closed";
+    backend_id: string;
+    created_at: string;
+}
+interface AcpSessionStatus extends AcpSession {
+    runtime_options: AcpRuntimeOptionPatch;
+    last_activity_at: string | null;
+    last_error?: string;
+}
+interface AcpRuntimeOptionPatch {
+    model?: string;
+    cwd?: string;
+    timeoutSeconds?: number;
+    runtimeMode?: string;
+    approvalPolicy?: "approve-all" | "approve-reads" | "deny-all";
+    extras?: Record<string, string>;
+}
+interface AcpAttachment {
+    contentString: string;
+    mime: string;
+}
+interface AcpChatResponse {
+    text: string;
+    stop_reason?: string;
+}
+interface AcpStreamEvent {
+    type: "text_delta" | "status" | "tool_call" | "permission_request" | "done" | "error" | "close";
+    data: Record<string, unknown>;
+}
+interface AcpPermissionDecision {
+    requestId: string;
+    optionId: string;
+    outcome?: string;
+}
+declare class AcpAgentModule {
+    private httpClient;
+    constructor(httpClient: HttpClient);
+    /** List available CLI agents. Pass includeModels to get model lists per agent. */
+    listAgents(opts?: {
+        includeModels?: boolean;
+    }): Promise<AcpAgentInfo[]>;
+    /** Create and initialize a new ACP session. Spawns the CLI agent process. */
+    createSession(options: AcpSessionOptions): Promise<AcpSession>;
+    /** Get session status and runtime options. */
+    getSession(sessionKey: string): Promise<AcpSessionStatus>;
+    /** List active ACP sessions owned by this app. */
+    listSessions(): Promise<AcpSessionStatus[]>;
+    /** Update runtime options (applied on next turn). */
+    patchSession(sessionKey: string, patch: AcpRuntimeOptionPatch): Promise<void>;
+    /** Close session and stop the agent process. */
+    closeSession(sessionKey: string, reason?: string): Promise<void>;
+    /**
+     * Synchronous turn — waits for completion, returns full response.
+     * Requires approvalPolicy set on the session (via create or patchSession).
+     */
+    chat(sessionKey: string, message: string, attachments?: AcpAttachment[]): Promise<AcpChatResponse>;
+    /**
+     * Streaming turn via SSE. Yields events as they arrive.
+     *
+     * Uses named SSE events (event: + data: lines). The event type comes
+     * from the `event:` line, not from inside the JSON payload.
+     *
+     * @example
+     * ```typescript
+     * for await (const event of sdk.acpAgent.streamChat(key, 'Explain this')) {
+     *   if (event.type === 'text_delta') console.log(event.data.text);
+     *   if (event.type === 'permission_request') {
+     *     await sdk.acpAgent.resolvePermission(key, {
+     *       requestId: event.data.requestId as string,
+     *       optionId: 'allow_once',
+     *     });
+     *   }
+     * }
+     * ```
+     */
+    streamChat(sessionKey: string, message: string, attachments?: AcpAttachment[]): AsyncIterableIterator<AcpStreamEvent>;
+    /** Cancel the active turn on a session. */
+    cancelTurn(sessionKey: string, reason?: string): Promise<void>;
+    /** Resolve a pending permission request (call while SSE stream is active). */
+    resolvePermission(sessionKey: string, decision: AcpPermissionDecision): Promise<{
+        resolved: boolean;
+        reason?: string;
+    }>;
+    /** Convenience: create session + first sync chat in one call. */
+    startChat(message: string, options: AcpSessionOptions): Promise<{
+        session: AcpSession;
+        response: AcpChatResponse;
+    }>;
+}
+
 /**
  * MCP Module - Interact with MCP servers via RealtimeX SDK
  */
@@ -1847,6 +1975,7 @@ declare class RealtimeXSDK {
     tts: TTSModule;
     stt: STTModule;
     agent: AgentModule;
+    acpAgent: AcpAgentModule;
     mcp: MCPModule;
     contract: ContractModule;
     contractRuntime: ContractRuntime;
@@ -1886,4 +2015,4 @@ declare class RealtimeXSDK {
     getAppDataDir(): Promise<string>;
 }
 
-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, AuthModule, type AuthProvider, type AuthTokenResponse, 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, type ContractInvokePayload, ContractModule, ContractRuntime, type ContractRuntimeInterface, type ContractRuntimeOptions, type ContractSignInput, type ContractStrictness, ContractValidationError, type DatabaseConfig, DatabaseModule, 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 LocalAppCapabilitiesResponse, type LocalAppCapabilityDetailResponse, type LocalAppCapabilitySearchResponse, 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 SyncTokenResponse, 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 };
+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, type AcpAgentInfo, AcpAgentModule, type AcpAttachment, type AcpChatResponse, type AcpPermissionDecision, type AcpRuntimeOptionPatch, type AcpSession, type AcpSessionOptions, type AcpSessionStatus, type AcpStreamEvent, ActivitiesModule, type Activity, type Agent, type AgentChatOptions, type AgentChatResponse, AgentModule, type AgentSession, type AgentSessionInfo, type AgentSessionOptions, ApiModule, AuthModule, type AuthProvider, type AuthTokenResponse, 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, type ContractInvokePayload, ContractModule, ContractRuntime, type ContractRuntimeInterface, type ContractRuntimeOptions, type ContractSignInput, type ContractStrictness, ContractValidationError, type DatabaseConfig, DatabaseModule, 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 LocalAppCapabilitiesResponse, type LocalAppCapabilityDetailResponse, type LocalAppCapabilitySearchResponse, 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 SyncTokenResponse, 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 };

package/dist/index.d.ts

@@ -1117,6 +1117,134 @@ declare class AgentModule {
     }>;
 }
 
+/**
+ * ACP Agent Module — CLI-based agent sessions via ACP bridge
+ *
+ * Provides session lifecycle, sync/streaming chat, permission resolution,
+ * and turn control for CLI agents (Claude, Gemini, Codex, etc.).
+ *
+ * Unlike AgentModule (LLM API-based), ACP agents spawn CLI processes
+ * and can execute commands, read/write files, and interact with tools.
+ */
+
+interface AcpAgentInfo {
+    id: string;
+    label: string;
+    handles: string[];
+    installed: boolean;
+    authReady: boolean;
+    version?: string | null;
+    status: "installed" | "not_installed";
+    /** Present when listAgents({ includeModels: true }). */
+    models?: Array<{
+        id: string;
+        name?: string;
+    }>;
+    /** "provider_api" | "fallback" — how models were resolved. */
+    source?: string | null;
+    /** Non-null if model fetch failed and fell back. */
+    error?: string | null;
+}
+interface AcpSessionOptions {
+    agent_id: string;
+    cwd?: string;
+    label?: string;
+    model?: string;
+    approvalPolicy?: "approve-all" | "approve-reads" | "deny-all";
+}
+interface AcpSession {
+    session_key: string;
+    agent_id: string;
+    state: "initializing" | "ready" | "stale" | "closed";
+    backend_id: string;
+    created_at: string;
+}
+interface AcpSessionStatus extends AcpSession {
+    runtime_options: AcpRuntimeOptionPatch;
+    last_activity_at: string | null;
+    last_error?: string;
+}
+interface AcpRuntimeOptionPatch {
+    model?: string;
+    cwd?: string;
+    timeoutSeconds?: number;
+    runtimeMode?: string;
+    approvalPolicy?: "approve-all" | "approve-reads" | "deny-all";
+    extras?: Record<string, string>;
+}
+interface AcpAttachment {
+    contentString: string;
+    mime: string;
+}
+interface AcpChatResponse {
+    text: string;
+    stop_reason?: string;
+}
+interface AcpStreamEvent {
+    type: "text_delta" | "status" | "tool_call" | "permission_request" | "done" | "error" | "close";
+    data: Record<string, unknown>;
+}
+interface AcpPermissionDecision {
+    requestId: string;
+    optionId: string;
+    outcome?: string;
+}
+declare class AcpAgentModule {
+    private httpClient;
+    constructor(httpClient: HttpClient);
+    /** List available CLI agents. Pass includeModels to get model lists per agent. */
+    listAgents(opts?: {
+        includeModels?: boolean;
+    }): Promise<AcpAgentInfo[]>;
+    /** Create and initialize a new ACP session. Spawns the CLI agent process. */
+    createSession(options: AcpSessionOptions): Promise<AcpSession>;
+    /** Get session status and runtime options. */
+    getSession(sessionKey: string): Promise<AcpSessionStatus>;
+    /** List active ACP sessions owned by this app. */
+    listSessions(): Promise<AcpSessionStatus[]>;
+    /** Update runtime options (applied on next turn). */
+    patchSession(sessionKey: string, patch: AcpRuntimeOptionPatch): Promise<void>;
+    /** Close session and stop the agent process. */
+    closeSession(sessionKey: string, reason?: string): Promise<void>;
+    /**
+     * Synchronous turn — waits for completion, returns full response.
+     * Requires approvalPolicy set on the session (via create or patchSession).
+     */
+    chat(sessionKey: string, message: string, attachments?: AcpAttachment[]): Promise<AcpChatResponse>;
+    /**
+     * Streaming turn via SSE. Yields events as they arrive.
+     *
+     * Uses named SSE events (event: + data: lines). The event type comes
+     * from the `event:` line, not from inside the JSON payload.
+     *
+     * @example
+     * ```typescript
+     * for await (const event of sdk.acpAgent.streamChat(key, 'Explain this')) {
+     *   if (event.type === 'text_delta') console.log(event.data.text);
+     *   if (event.type === 'permission_request') {
+     *     await sdk.acpAgent.resolvePermission(key, {
+     *       requestId: event.data.requestId as string,
+     *       optionId: 'allow_once',
+     *     });
+     *   }
+     * }
+     * ```
+     */
+    streamChat(sessionKey: string, message: string, attachments?: AcpAttachment[]): AsyncIterableIterator<AcpStreamEvent>;
+    /** Cancel the active turn on a session. */
+    cancelTurn(sessionKey: string, reason?: string): Promise<void>;
+    /** Resolve a pending permission request (call while SSE stream is active). */
+    resolvePermission(sessionKey: string, decision: AcpPermissionDecision): Promise<{
+        resolved: boolean;
+        reason?: string;
+    }>;
+    /** Convenience: create session + first sync chat in one call. */
+    startChat(message: string, options: AcpSessionOptions): Promise<{
+        session: AcpSession;
+        response: AcpChatResponse;
+    }>;
+}
+
 /**
  * MCP Module - Interact with MCP servers via RealtimeX SDK
  */
@@ -1847,6 +1975,7 @@ declare class RealtimeXSDK {
     tts: TTSModule;
     stt: STTModule;
     agent: AgentModule;
+    acpAgent: AcpAgentModule;
     mcp: MCPModule;
     contract: ContractModule;
     contractRuntime: ContractRuntime;
@@ -1886,4 +2015,4 @@ declare class RealtimeXSDK {
     getAppDataDir(): Promise<string>;
 }
 
-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, AuthModule, type AuthProvider, type AuthTokenResponse, 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, type ContractInvokePayload, ContractModule, ContractRuntime, type ContractRuntimeInterface, type ContractRuntimeOptions, type ContractSignInput, type ContractStrictness, ContractValidationError, type DatabaseConfig, DatabaseModule, 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 LocalAppCapabilitiesResponse, type LocalAppCapabilityDetailResponse, type LocalAppCapabilitySearchResponse, 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 SyncTokenResponse, 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 };
+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, type AcpAgentInfo, AcpAgentModule, type AcpAttachment, type AcpChatResponse, type AcpPermissionDecision, type AcpRuntimeOptionPatch, type AcpSession, type AcpSessionOptions, type AcpSessionStatus, type AcpStreamEvent, ActivitiesModule, type Activity, type Agent, type AgentChatOptions, type AgentChatResponse, AgentModule, type AgentSession, type AgentSessionInfo, type AgentSessionOptions, ApiModule, AuthModule, type AuthProvider, type AuthTokenResponse, 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, type ContractInvokePayload, ContractModule, ContractRuntime, type ContractRuntimeInterface, type ContractRuntimeOptions, type ContractSignInput, type ContractStrictness, ContractValidationError, type DatabaseConfig, DatabaseModule, 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 LocalAppCapabilitiesResponse, type LocalAppCapabilityDetailResponse, type LocalAppCapabilitySearchResponse, 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 SyncTokenResponse, 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 };

package/dist/index.js

@@ -34,6 +34,7 @@ __export(index_exports, {
   ACPEventMapper: () => ACPEventMapper,
   ACPPermissionBridge: () => ACPPermissionBridge,
   ACPTelemetry: () => ACPTelemetry,
+  AcpAgentModule: () => AcpAgentModule,
   ActivitiesModule: () => ActivitiesModule,
   AgentModule: () => AgentModule,
   ApiModule: () => ApiModule,
@@ -1783,6 +1784,193 @@ var AgentModule = class {
   }
 };
 
+// src/modules/acpAgent.ts
+function encodeSessionKey(sessionKey) {
+  return encodeURIComponent(sessionKey);
+}
+async function parseJsonResponse(response, fallbackError) {
+  const data = await response.json();
+  if (!response.ok) throw new Error(data.error || fallbackError);
+  return data;
+}
+var AcpAgentModule = class {
+  constructor(httpClient) {
+    this.httpClient = httpClient;
+  }
+  /** List available CLI agents. Pass includeModels to get model lists per agent. */
+  async listAgents(opts) {
+    const qs = opts?.includeModels ? "?includeModels=true" : "";
+    const response = await this.httpClient.fetch(`/sdk/acp/agents${qs}`);
+    const data = await parseJsonResponse(
+      response,
+      "Failed to list agents"
+    );
+    return data.agents;
+  }
+  /** Create and initialize a new ACP session. Spawns the CLI agent process. */
+  async createSession(options) {
+    const response = await this.httpClient.fetch("/sdk/acp/session", {
+      method: "POST",
+      body: JSON.stringify(options)
+    });
+    const data = await parseJsonResponse(
+      response,
+      "Failed to create session"
+    );
+    return data.session;
+  }
+  /** Get session status and runtime options. */
+  async getSession(sessionKey) {
+    const response = await this.httpClient.fetch(
+      `/sdk/acp/session/${encodeSessionKey(sessionKey)}`
+    );
+    const data = await parseJsonResponse(
+      response,
+      "Failed to get session"
+    );
+    return data.session;
+  }
+  /** List active ACP sessions owned by this app. */
+  async listSessions() {
+    const response = await this.httpClient.fetch("/sdk/acp/sessions");
+    const data = await parseJsonResponse(
+      response,
+      "Failed to list sessions"
+    );
+    return data.sessions;
+  }
+  /** Update runtime options (applied on next turn). */
+  async patchSession(sessionKey, patch) {
+    const response = await this.httpClient.fetch(
+      `/sdk/acp/session/${encodeSessionKey(sessionKey)}`,
+      { method: "PATCH", body: JSON.stringify(patch) }
+    );
+    await parseJsonResponse(response, "Failed to update session");
+  }
+  /** Close session and stop the agent process. */
+  async closeSession(sessionKey, reason) {
+    const response = await this.httpClient.fetch(
+      `/sdk/acp/session/${encodeSessionKey(sessionKey)}`,
+      {
+        method: "DELETE",
+        body: reason ? JSON.stringify({ reason }) : void 0
+      }
+    );
+    await parseJsonResponse(response, "Failed to close session");
+  }
+  /**
+   * Synchronous turn — waits for completion, returns full response.
+   * Requires approvalPolicy set on the session (via create or patchSession).
+   */
+  async chat(sessionKey, message, attachments) {
+    const body = { message };
+    if (attachments?.length) body.attachments = attachments;
+    const response = await this.httpClient.fetch(
+      `/sdk/acp/session/${encodeSessionKey(sessionKey)}/chat`,
+      { method: "POST", body: JSON.stringify(body) }
+    );
+    const data = await parseJsonResponse(
+      response,
+      "Chat request failed"
+    );
+    return data.response;
+  }
+  /**
+   * Streaming turn via SSE. Yields events as they arrive.
+   *
+   * Uses named SSE events (event: + data: lines). The event type comes
+   * from the `event:` line, not from inside the JSON payload.
+   *
+   * @example
+   * ```typescript
+   * for await (const event of sdk.acpAgent.streamChat(key, 'Explain this')) {
+   *   if (event.type === 'text_delta') console.log(event.data.text);
+   *   if (event.type === 'permission_request') {
+   *     await sdk.acpAgent.resolvePermission(key, {
+   *       requestId: event.data.requestId as string,
+   *       optionId: 'allow_once',
+   *     });
+   *   }
+   * }
+   * ```
+   */
+  async *streamChat(sessionKey, message, attachments) {
+    const body = { message };
+    if (attachments?.length) body.attachments = attachments;
+    const response = await this.httpClient.fetch(
+      `/sdk/acp/session/${encodeSessionKey(sessionKey)}/chat/stream`,
+      { method: "POST", body: JSON.stringify(body) }
+    );
+    if (!response.ok) {
+      const data = await response.json();
+      throw new Error(data.error || "Stream request failed");
+    }
+    if (!response.body) {
+      throw new Error("Response body is null");
+    }
+    yield* parseNamedSSEStream(response.body);
+  }
+  /** Cancel the active turn on a session. */
+  async cancelTurn(sessionKey, reason) {
+    const response = await this.httpClient.fetch(
+      `/sdk/acp/session/${encodeSessionKey(sessionKey)}/cancel`,
+      {
+        method: "POST",
+        body: reason ? JSON.stringify({ reason }) : void 0
+      }
+    );
+    await parseJsonResponse(response, "Failed to cancel turn");
+  }
+  /** Resolve a pending permission request (call while SSE stream is active). */
+  async resolvePermission(sessionKey, decision) {
+    const response = await this.httpClient.fetch(
+      `/sdk/acp/session/${encodeSessionKey(sessionKey)}/permission`,
+      { method: "POST", body: JSON.stringify(decision) }
+    );
+    return parseJsonResponse(response, "Failed to resolve permission");
+  }
+  /** Convenience: create session + first sync chat in one call. */
+  async startChat(message, options) {
+    const session = await this.createSession(options);
+    const chatResponse = await this.chat(session.session_key, message);
+    return { session, response: chatResponse };
+  }
+};
+async function* parseNamedSSEStream(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let currentEvent = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() || "";
+      for (const line of lines) {
+        if (line.startsWith("event: ")) {
+          currentEvent = line.slice(7).trim();
+        } else if (line.startsWith("data: ")) {
+          const jsonStr = line.slice(6);
+          const eventType = currentEvent || void 0;
+          currentEvent = "";
+          if (!eventType) continue;
+          try {
+            const data = JSON.parse(jsonStr);
+            yield { type: eventType, data };
+          } catch {
+          }
+        } else if (line === "") {
+          currentEvent = "";
+        }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
 // src/modules/mcp.ts
 var MCPModule = class extends ApiModule {
   constructor(realtimexUrl, appId, appName, apiKey) {
@@ -3506,6 +3694,7 @@ var _RealtimeXSDK = class _RealtimeXSDK {
     this.tts = new TTSModule(this.realtimexUrl, this.appId, this.appName, this.apiKey);
     this.stt = new STTModule(this.realtimexUrl, this.appId, this.appName, this.apiKey);
     this.agent = new AgentModule(this.httpClient);
+    this.acpAgent = new AcpAgentModule(this.httpClient);
     this.mcp = new MCPModule(this.realtimexUrl, this.appId, this.appName, this.apiKey);
     this.contract = new ContractModule(this.realtimexUrl, this.appName, this.appId, this.apiKey);
     this.contractRuntime = new ContractRuntime({
@@ -3622,6 +3811,7 @@ var RealtimeXSDK = _RealtimeXSDK;
   ACPEventMapper,
   ACPPermissionBridge,
   ACPTelemetry,
+  AcpAgentModule,
   ActivitiesModule,
   AgentModule,
   ApiModule,

package/dist/index.mjs

@@ -1691,6 +1691,193 @@ var AgentModule = class {
   }
 };
 
+// src/modules/acpAgent.ts
+function encodeSessionKey(sessionKey) {
+  return encodeURIComponent(sessionKey);
+}
+async function parseJsonResponse(response, fallbackError) {
+  const data = await response.json();
+  if (!response.ok) throw new Error(data.error || fallbackError);
+  return data;
+}
+var AcpAgentModule = class {
+  constructor(httpClient) {
+    this.httpClient = httpClient;
+  }
+  /** List available CLI agents. Pass includeModels to get model lists per agent. */
+  async listAgents(opts) {
+    const qs = opts?.includeModels ? "?includeModels=true" : "";
+    const response = await this.httpClient.fetch(`/sdk/acp/agents${qs}`);
+    const data = await parseJsonResponse(
+      response,
+      "Failed to list agents"
+    );
+    return data.agents;
+  }
+  /** Create and initialize a new ACP session. Spawns the CLI agent process. */
+  async createSession(options) {
+    const response = await this.httpClient.fetch("/sdk/acp/session", {
+      method: "POST",
+      body: JSON.stringify(options)
+    });
+    const data = await parseJsonResponse(
+      response,
+      "Failed to create session"
+    );
+    return data.session;
+  }
+  /** Get session status and runtime options. */
+  async getSession(sessionKey) {
+    const response = await this.httpClient.fetch(
+      `/sdk/acp/session/${encodeSessionKey(sessionKey)}`
+    );
+    const data = await parseJsonResponse(
+      response,
+      "Failed to get session"
+    );
+    return data.session;
+  }
+  /** List active ACP sessions owned by this app. */
+  async listSessions() {
+    const response = await this.httpClient.fetch("/sdk/acp/sessions");
+    const data = await parseJsonResponse(
+      response,
+      "Failed to list sessions"
+    );
+    return data.sessions;
+  }
+  /** Update runtime options (applied on next turn). */
+  async patchSession(sessionKey, patch) {
+    const response = await this.httpClient.fetch(
+      `/sdk/acp/session/${encodeSessionKey(sessionKey)}`,
+      { method: "PATCH", body: JSON.stringify(patch) }
+    );
+    await parseJsonResponse(response, "Failed to update session");
+  }
+  /** Close session and stop the agent process. */
+  async closeSession(sessionKey, reason) {
+    const response = await this.httpClient.fetch(
+      `/sdk/acp/session/${encodeSessionKey(sessionKey)}`,
+      {
+        method: "DELETE",
+        body: reason ? JSON.stringify({ reason }) : void 0
+      }
+    );
+    await parseJsonResponse(response, "Failed to close session");
+  }
+  /**
+   * Synchronous turn — waits for completion, returns full response.
+   * Requires approvalPolicy set on the session (via create or patchSession).
+   */
+  async chat(sessionKey, message, attachments) {
+    const body = { message };
+    if (attachments?.length) body.attachments = attachments;
+    const response = await this.httpClient.fetch(
+      `/sdk/acp/session/${encodeSessionKey(sessionKey)}/chat`,
+      { method: "POST", body: JSON.stringify(body) }
+    );
+    const data = await parseJsonResponse(
+      response,
+      "Chat request failed"
+    );
+    return data.response;
+  }
+  /**
+   * Streaming turn via SSE. Yields events as they arrive.
+   *
+   * Uses named SSE events (event: + data: lines). The event type comes
+   * from the `event:` line, not from inside the JSON payload.
+   *
+   * @example
+   * ```typescript
+   * for await (const event of sdk.acpAgent.streamChat(key, 'Explain this')) {
+   *   if (event.type === 'text_delta') console.log(event.data.text);
+   *   if (event.type === 'permission_request') {
+   *     await sdk.acpAgent.resolvePermission(key, {
+   *       requestId: event.data.requestId as string,
+   *       optionId: 'allow_once',
+   *     });
+   *   }
+   * }
+   * ```
+   */
+  async *streamChat(sessionKey, message, attachments) {
+    const body = { message };
+    if (attachments?.length) body.attachments = attachments;
+    const response = await this.httpClient.fetch(
+      `/sdk/acp/session/${encodeSessionKey(sessionKey)}/chat/stream`,
+      { method: "POST", body: JSON.stringify(body) }
+    );
+    if (!response.ok) {
+      const data = await response.json();
+      throw new Error(data.error || "Stream request failed");
+    }
+    if (!response.body) {
+      throw new Error("Response body is null");
+    }
+    yield* parseNamedSSEStream(response.body);
+  }
+  /** Cancel the active turn on a session. */
+  async cancelTurn(sessionKey, reason) {
+    const response = await this.httpClient.fetch(
+      `/sdk/acp/session/${encodeSessionKey(sessionKey)}/cancel`,
+      {
+        method: "POST",
+        body: reason ? JSON.stringify({ reason }) : void 0
+      }
+    );
+    await parseJsonResponse(response, "Failed to cancel turn");
+  }
+  /** Resolve a pending permission request (call while SSE stream is active). */
+  async resolvePermission(sessionKey, decision) {
+    const response = await this.httpClient.fetch(
+      `/sdk/acp/session/${encodeSessionKey(sessionKey)}/permission`,
+      { method: "POST", body: JSON.stringify(decision) }
+    );
+    return parseJsonResponse(response, "Failed to resolve permission");
+  }
+  /** Convenience: create session + first sync chat in one call. */
+  async startChat(message, options) {
+    const session = await this.createSession(options);
+    const chatResponse = await this.chat(session.session_key, message);
+    return { session, response: chatResponse };
+  }
+};
+async function* parseNamedSSEStream(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let currentEvent = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() || "";
+      for (const line of lines) {
+        if (line.startsWith("event: ")) {
+          currentEvent = line.slice(7).trim();
+        } else if (line.startsWith("data: ")) {
+          const jsonStr = line.slice(6);
+          const eventType = currentEvent || void 0;
+          currentEvent = "";
+          if (!eventType) continue;
+          try {
+            const data = JSON.parse(jsonStr);
+            yield { type: eventType, data };
+          } catch {
+          }
+        } else if (line === "") {
+          currentEvent = "";
+        }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
 // src/modules/mcp.ts
 var MCPModule = class extends ApiModule {
   constructor(realtimexUrl, appId, appName, apiKey) {
@@ -3414,6 +3601,7 @@ var _RealtimeXSDK = class _RealtimeXSDK {
     this.tts = new TTSModule(this.realtimexUrl, this.appId, this.appName, this.apiKey);
     this.stt = new STTModule(this.realtimexUrl, this.appId, this.appName, this.apiKey);
     this.agent = new AgentModule(this.httpClient);
+    this.acpAgent = new AcpAgentModule(this.httpClient);
     this.mcp = new MCPModule(this.realtimexUrl, this.appId, this.appName, this.apiKey);
     this.contract = new ContractModule(this.realtimexUrl, this.appName, this.appId, this.apiKey);
     this.contractRuntime = new ContractRuntime({
@@ -3529,6 +3717,7 @@ export {
   ACPEventMapper,
   ACPPermissionBridge,
   ACPTelemetry,
+  AcpAgentModule,
   ActivitiesModule,
   AgentModule,
   ApiModule,

package/package.json

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