@pwrdrvr/agent-acp 0.12.3 → 0.13.1

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Client } from '@agentclientprotocol/sdk';
+import { Client, McpServer } from '@agentclientprotocol/sdk';
 import { Logger, AgentBackend, NormalizedThreadEvent, Unsubscribe, AgentBackendToolCallHandler, AgentBackendApprovalHandler, AgentStartThreadOptions, AgentBackendStartThreadResult, AgentStartTurnOptions, NormalizedTokenUsage, NormalizedToolCall } from '@pwrdrvr/agent-core';
 import { JsonRpcId } from '@pwrdrvr/agent-transport';
 
@@ -24,8 +24,8 @@ interface AcpAgentConnection {
     setSessionMode(params: Record<string, unknown>): Promise<unknown>;
     setSessionModel(params: Record<string, unknown>): Promise<unknown>;
     authenticate(params: Record<string, unknown>): Promise<unknown>;
-    extMethod(method: string, params: Record<string, unknown>): Promise<Record<string, unknown>>;
-    extNotification(method: string, params: Record<string, unknown>): Promise<void>;
+    request(method: string, params: Record<string, unknown>): Promise<unknown>;
+    notify(method: string, params: Record<string, unknown>): Promise<void>;
 }
 /** Built connection + a teardown handle (kills the child / closes streams). */
 type AcpAgentConnectionHandle = {
@@ -178,8 +178,13 @@ type AcpRuntimeAgentInfo = {
     title?: string;
     version?: string;
 };
+type AcpRuntimeMcpCapabilities = {
+    http?: boolean;
+    sse?: boolean;
+};
 type AcpRuntimeAgentCapabilities = {
     loadSession?: boolean;
+    mcp?: AcpRuntimeMcpCapabilities;
     sessionHistoryReplay?: boolean;
     session?: {
         close?: boolean;
@@ -212,6 +217,10 @@ declare function normalizeAcpRuntimeCapabilities(params: {
     initialize?: AcpRuntimeCapabilities;
 }): AcpRuntimeCapabilities | undefined;
 declare function acpRuntimeSupportsSessionLoad(capabilities: AcpRuntimeCapabilities | undefined): boolean;
+/** Optional ACP MCP transports are supported only when explicitly advertised. */
+declare function acpRuntimeSupportsHttpMcp(capabilities: AcpRuntimeCapabilities | undefined): boolean;
+/** Optional ACP MCP transports are supported only when explicitly advertised. */
+declare function acpRuntimeSupportsSseMcp(capabilities: AcpRuntimeCapabilities | undefined): boolean;
 /** The configOption an agent uses to expose model choice (ACP `category:
  *  "model"`, falling back to a literal `model` id). Some agents (e.g. Kimi)
  *  advertise the active model HERE rather than via top-level
@@ -235,6 +244,43 @@ declare function mergeAcpRuntimeState(existing: AcpSessionRuntimeState | undefin
 /** Resolve the human-facing label for a mode id from the capabilities snapshot. */
 declare function modeLabelFor(capabilities: AcpRuntimeCapabilities | undefined, modeId: string): string | undefined;
 
+/** ACP key/value entry used by stdio environments and HTTP headers. */
+type AcpMcpKeyValue = {
+    name: string;
+    value: string;
+};
+/** Host-friendly collection accepted wherever ACP requires key/value entries. */
+type AcpMcpKeyValueCollection = Readonly<Record<string, string>> | readonly AcpMcpKeyValue[];
+/** Backward-compatible stdio MCP configuration. ACP stdio has no `type` field. */
+type AcpStdioMcpServerConfig = {
+    name: string;
+    command: string;
+    args?: readonly string[];
+    env?: AcpMcpKeyValueCollection;
+};
+/** Streamable HTTP MCP configuration from the ACP v1 schema. */
+type AcpHttpMcpServerConfig = {
+    name: string;
+    type: "http";
+    url: string;
+    headers: AcpMcpKeyValueCollection;
+};
+/** Legacy HTTP+SSE MCP configuration from the ACP v1 schema. */
+type AcpSseMcpServerConfig = {
+    name: string;
+    type: "sse";
+    url: string;
+    headers: AcpMcpKeyValueCollection;
+};
+/** Public MCP input accepted by agent-acp session lifecycle methods. */
+type AcpMcpServerConfig = AcpStdioMcpServerConfig | AcpHttpMcpServerConfig | AcpSseMcpServerConfig;
+/** Exact MCP server wire union from the pinned ACP protocol library. */
+type AcpMcpServerWireConfig = McpServer;
+/** Serialize a host-friendly config into the exact ACP v1 wire representation. */
+declare function normalizeAcpMcpServerConfig(server: AcpMcpServerConfig): AcpMcpServerWireConfig;
+/** Serialize a per-session list without retaining mutable caller collections. */
+declare function normalizeAcpMcpServerConfigs(servers: readonly AcpMcpServerConfig[]): AcpMcpServerWireConfig[];
+
 type AcpPromptContentBlock = {
     type: "text";
     text: string;
@@ -243,12 +289,6 @@ type AcpPromptContentBlock = {
     mimeType: string;
     data: string;
 };
-type AcpMcpServerConfig = {
-    name: string;
-    command: string;
-    args?: string[];
-    env?: Record<string, string>;
-};
 type AcpRuntimeOptionSource = "mode" | "model" | "configOption";
 type AcpAgentClientOptions = {
     /** The transport (real stdio or a fake). */
@@ -262,7 +302,7 @@ type AcpAgentClientOptions = {
     /** Default cwd for `session/new` when `startThread` omits one. */
     cwd?: string;
     /** MCP servers to attach at `session/new` / `session/load`. */
-    mcpServers?: AcpMcpServerConfig[];
+    mcpServers?: readonly AcpMcpServerConfig[];
     now?: () => number;
     logger?: Logger;
 };
@@ -274,7 +314,15 @@ type AcpAgentClientOptions = {
 type AcpStartThreadOptions = {
     /** Working directory for the agent session. */
     cwd?: string;
-    mcpServers?: AcpMcpServerConfig[];
+    mcpServers?: readonly AcpMcpServerConfig[];
+};
+/** ACP-native `session/load` options. The protocol session id is the id the
+ * agent persisted; `threadId` optionally preserves a separate host-facing id. */
+type AcpLoadThreadOptions = {
+    sessionId: string;
+    threadId?: string;
+    cwd?: string;
+    mcpServers?: readonly AcpMcpServerConfig[];
 };
 /** ACP-NATIVE turn/start options. Internal mapping target; the public `startTurn`
  *  takes neutral `AgentStartTurnOptions`. */
@@ -343,6 +391,10 @@ declare class AcpAgentClient implements AgentBackend {
      *  mapping cwd + dropping Codex-only fields. Exposed for hosts that need
      *  ACP-specific control (per-thread `mcpServers`). */
     startThreadNative(options?: AcpStartThreadOptions): Promise<AgentBackendStartThreadResult>;
+    /** ACP-native `session/load`. The pinned ACP v1 library has no separate
+     *  `session/resume` method; loading is the protocol-defined history restore
+     *  path and receives the same per-thread MCP configuration as `session/new`. */
+    loadThreadNative(options: AcpLoadThreadOptions): Promise<AgentBackendStartThreadResult>;
     /**
      * Re-establish a fresh ACP session for a PERSISTED thread id whose underlying
      * session is gone (e.g. resuming a chat after an app restart — the agent
@@ -362,7 +414,7 @@ declare class AcpAgentClient implements AgentBackend {
          *  surfaces with different tool sets (library vs sizzle): each surface
          *  passes its own servers, so its threads spawn its tools — overriding the
          *  client-level default. */
-        mcpServers?: AcpMcpServerConfig[];
+        mcpServers?: readonly AcpMcpServerConfig[];
     }): Promise<void>;
     /**
      * Mint a thread id WITHOUT spawning the agent or opening a session. The
@@ -383,6 +435,7 @@ declare class AcpAgentClient implements AgentBackend {
      *  `bindThreadId` is given (resume), in which case the new ACP session is
      *  bound to that existing host thread id. */
     private establishSession;
+    private openSession;
     /**
      * Public `AgentBackend.startTurn`: accepts NEUTRAL `AgentStartTurnOptions` and
      * maps them onto ACP prompt content blocks — a leading `text` block from
@@ -423,10 +476,6 @@ declare class AcpAgentClient implements AgentBackend {
     private handleNotification;
     private applySessionUpdate;
     private handleAcpRequest;
-    /** Every MCP server name this client knows about — the client-level default
-     *  plus the per-thread servers of every live session. Used to auto-approve a
-     *  configured MCP tool regardless of which session's permission request it is. */
-    private knownMcpServerNames;
     private handlePermissionRequest;
     private setRuntimeOption;
     private setRuntimeOptionOnTransport;
@@ -448,8 +497,13 @@ declare class AcpAgentClient implements AgentBackend {
     private notifyRuntimeCapabilities;
     private emitThreadSettings;
     private requireSession;
+    private assertMcpTransportSupport;
     /** Whether the agent advertises session/load support (for hosts that resume). */
     supportsSessionLoad(): boolean;
+    /** Whether the initialize result explicitly advertises streamable HTTP MCP. */
+    supportsHttpMcp(): boolean;
+    /** Whether the initialize result explicitly advertises legacy HTTP+SSE MCP. */
+    supportsSseMcp(): boolean;
 }
 /** Pick the value to set on a "thinking" config option for a neutral reasoning
  *  token: low-effort → the OFF-like value, high-effort → the ON-like value.
@@ -820,4 +874,4 @@ declare class AcpRegistryService {
 declare function evaluateAcpDistributionPolicy(distribution: AcpRegistryDistribution, allowlist: AcpAllowlistDecision): AcpDistributionPolicy;
 declare function normalizeRegistry(raw: unknown): AcpRegistryAgent[];
 
-export { ACP_REGISTRY_URL, AcpAgentAllowlist, type AcpAgentAllowlistRule, AcpAgentClient, type AcpAgentClientFactory, type AcpAgentClientOptions, AcpAgentClientPool, type AcpAgentClientPoolOptions, type AcpAgentConnection, type AcpAgentConnectionHandle, type AcpAgentInstanceSource, type AcpAgentQuirks, type AcpAgentStrategy, type AcpAllowlistDecision, type AcpApplyContext, type AcpBinaryPlatformDistribution, AcpConnection, type AcpConnectionOptions, type AcpDiscoveryProbe, type AcpDistributionKind, type AcpDistributionPolicy, type AcpJsonRpcTransport, type AcpMcpServerConfig, type AcpNormalizeResult, type AcpNormalizerOptions, AcpOneShotClient, type AcpOneShotClientOptions, type AcpOneShotRequest, type AcpOneShotResponse, type AcpPackageDistribution, type AcpPathExecutableLister, type AcpPromptContentBlock, type AcpRegistryAgent, type AcpRegistryAgentWithPolicy, type AcpRegistryAuthDescriptor, type AcpRegistryAuthMethod, type AcpRegistryDistribution, type AcpRegistryFetch, AcpRegistryService, type AcpRegistryServiceOptions, type AcpRegistrySnapshot, type AcpRuntimeAgentCapabilities, type AcpRuntimeAgentInfo, type AcpRuntimeCapabilities, type AcpRuntimeCapabilitiesHandler, type AcpRuntimeCapabilitiesSource, type AcpRuntimeConfigOption, type AcpRuntimeConfigOptionValue, type AcpRuntimeMode, type AcpRuntimeModel, type AcpRuntimeModels, type AcpRuntimeModes, type AcpRuntimeOptionSource, AcpSessionNormalizer, type AcpSessionRuntimeState, type AcpSpawnSpec, type AcpStartThreadOptions, type AcpStartTurnOptions, type AcpTitleHandler, type AcpVerificationStatus, BANNED_ACP_REGISTRY_IDS, BUILT_IN_ACP_STRATEGIES, DEFAULT_ACP_AGENT_ALLOWLIST, type DiscoveredAcpAgent, type DiscoveredAcpAgentGroup, type DiscoveredAcpAgentInstance, type LocalAcpAgentProbe, type LocalAcpDiscoveryOptions, type LocalAcpProbeResult, acpRuntimeSupportsSessionLoad, acpSessionRuntimeStateFromCapabilities, acpSessionRuntimeStateFromUpdate, asRecord, buildAcpBackendId, buildStrategyTable, defaultAcpAgentAllowlist, defaultQuirks, discoverLocalAcpAgentInstances, discoverLocalAcpAgents, evaluateAcpDistributionPolicy, geminiStrategy, grokStrategy, isBannedAcpRegistryId, kimiStrategy, mergeAcpRuntimeState, modeLabelFor, modelConfigOption, modelIdFromCapabilities, modelsFromCapabilities, normalizeAcpRuntimeCapabilities, normalizeRegistry, qwenStrategy, readAcpContentText, readBoolean, readContentText, readFirstLocationPath, readFirstString, readKind, readNonEmptyString, readNumber, readPromptText, readString, readToolCallId, readToolContentText, readToolOutput, readUpdateText, reasoningValueForThoughtLevel, strategyByBackendId, strategyById, toolCallFromUpdate, wellKnownAgentBinDirs };
+export { ACP_REGISTRY_URL, AcpAgentAllowlist, type AcpAgentAllowlistRule, AcpAgentClient, type AcpAgentClientFactory, type AcpAgentClientOptions, AcpAgentClientPool, type AcpAgentClientPoolOptions, type AcpAgentConnection, type AcpAgentConnectionHandle, type AcpAgentInstanceSource, type AcpAgentQuirks, type AcpAgentStrategy, type AcpAllowlistDecision, type AcpApplyContext, type AcpBinaryPlatformDistribution, AcpConnection, type AcpConnectionOptions, type AcpDiscoveryProbe, type AcpDistributionKind, type AcpDistributionPolicy, type AcpHttpMcpServerConfig, type AcpJsonRpcTransport, type AcpLoadThreadOptions, type AcpMcpKeyValue, type AcpMcpKeyValueCollection, type AcpMcpServerConfig, type AcpMcpServerWireConfig, type AcpNormalizeResult, type AcpNormalizerOptions, AcpOneShotClient, type AcpOneShotClientOptions, type AcpOneShotRequest, type AcpOneShotResponse, type AcpPackageDistribution, type AcpPathExecutableLister, type AcpPromptContentBlock, type AcpRegistryAgent, type AcpRegistryAgentWithPolicy, type AcpRegistryAuthDescriptor, type AcpRegistryAuthMethod, type AcpRegistryDistribution, type AcpRegistryFetch, AcpRegistryService, type AcpRegistryServiceOptions, type AcpRegistrySnapshot, type AcpRuntimeAgentCapabilities, type AcpRuntimeAgentInfo, type AcpRuntimeCapabilities, type AcpRuntimeCapabilitiesHandler, type AcpRuntimeCapabilitiesSource, type AcpRuntimeConfigOption, type AcpRuntimeConfigOptionValue, type AcpRuntimeMcpCapabilities, type AcpRuntimeMode, type AcpRuntimeModel, type AcpRuntimeModels, type AcpRuntimeModes, type AcpRuntimeOptionSource, AcpSessionNormalizer, type AcpSessionRuntimeState, type AcpSpawnSpec, type AcpSseMcpServerConfig, type AcpStartThreadOptions, type AcpStartTurnOptions, type AcpStdioMcpServerConfig, type AcpTitleHandler, type AcpVerificationStatus, BANNED_ACP_REGISTRY_IDS, BUILT_IN_ACP_STRATEGIES, DEFAULT_ACP_AGENT_ALLOWLIST, type DiscoveredAcpAgent, type DiscoveredAcpAgentGroup, type DiscoveredAcpAgentInstance, type LocalAcpAgentProbe, type LocalAcpDiscoveryOptions, type LocalAcpProbeResult, acpRuntimeSupportsHttpMcp, acpRuntimeSupportsSessionLoad, acpRuntimeSupportsSseMcp, acpSessionRuntimeStateFromCapabilities, acpSessionRuntimeStateFromUpdate, asRecord, buildAcpBackendId, buildStrategyTable, defaultAcpAgentAllowlist, defaultQuirks, discoverLocalAcpAgentInstances, discoverLocalAcpAgents, evaluateAcpDistributionPolicy, geminiStrategy, grokStrategy, isBannedAcpRegistryId, kimiStrategy, mergeAcpRuntimeState, modeLabelFor, modelConfigOption, modelIdFromCapabilities, modelsFromCapabilities, normalizeAcpMcpServerConfig, normalizeAcpMcpServerConfigs, normalizeAcpRuntimeCapabilities, normalizeRegistry, qwenStrategy, readAcpContentText, readBoolean, readContentText, readFirstLocationPath, readFirstString, readKind, readNonEmptyString, readNumber, readPromptText, readString, readToolCallId, readToolContentText, readToolOutput, readUpdateText, reasoningValueForThoughtLevel, strategyByBackendId, strategyById, toolCallFromUpdate, wellKnownAgentBinDirs };