@actant/acp 0.1.2

package/dist/index.d.ts

@@ -0,0 +1,281 @@
+import { SessionNotification, RequestPermissionRequest, RequestPermissionResponse, ReadTextFileRequest, ReadTextFileResponse, WriteTextFileRequest, WriteTextFileResponse, CreateTerminalRequest, CreateTerminalResponse, TerminalOutputRequest, TerminalOutputResponse, WaitForTerminalExitRequest, WaitForTerminalExitResponse, KillTerminalCommandRequest, KillTerminalCommandResponse, ReleaseTerminalRequest, ReleaseTerminalResponse, InitializeResponse, ClientSideConnection, NewSessionResponse, ContentBlock, ClientCapabilities } from '@agentclientprotocol/sdk';
+export { ContentBlock, SessionNotification } from '@agentclientprotocol/sdk';
+import { PermissionsConfig } from '@actant/shared';
+import { Socket } from 'node:net';
+import { PermissionPolicyEnforcer, AgentCommunicator, RunPromptOptions, PromptResult, StreamChunk } from '@actant/core';
+
+/**
+ * Pluggable handler for every Client callback the Agent can invoke.
+ * Implementations decide whether to handle locally or forward to IDE.
+ */
+interface ClientCallbackHandler {
+    requestPermission(params: RequestPermissionRequest): Promise<RequestPermissionResponse>;
+    sessionUpdate(params: SessionNotification): Promise<void>;
+    readTextFile(params: ReadTextFileRequest): Promise<ReadTextFileResponse>;
+    writeTextFile(params: WriteTextFileRequest): Promise<WriteTextFileResponse>;
+    createTerminal?(params: CreateTerminalRequest): Promise<CreateTerminalResponse>;
+    terminalOutput?(params: TerminalOutputRequest): Promise<TerminalOutputResponse>;
+    waitForTerminalExit?(params: WaitForTerminalExitRequest): Promise<WaitForTerminalExitResponse>;
+    killTerminal?(params: KillTerminalCommandRequest): Promise<KillTerminalCommandResponse>;
+    releaseTerminal?(params: ReleaseTerminalRequest): Promise<ReleaseTerminalResponse>;
+}
+interface AcpConnectionOptions {
+    /** Auto-approve all tool permission requests (fallback when no permissionPolicy). */
+    autoApprove?: boolean;
+    /** Permission policy for the ACP Client allowlist (Layer 2 enforcement). */
+    permissionPolicy?: PermissionsConfig;
+    /** Instance name for audit logging. */
+    instanceName?: string;
+    /** Global session update listener. */
+    onSessionUpdate?: (notification: SessionNotification) => void;
+    /** Env vars to pass to the agent subprocess. */
+    env?: Record<string, string>;
+    /**
+     * Override the default local Client callbacks.
+     * When provided, AcpConnection delegates ALL Client requests to this handler
+     * instead of using the built-in local implementation.
+     * Used by AcpGateway to route callbacks to IDE or local depending on lease state.
+     */
+    callbackHandler?: ClientCallbackHandler;
+}
+interface AcpSessionInfo {
+    sessionId: string;
+    modes?: NewSessionResponse["modes"];
+    configOptions?: NewSessionResponse["configOptions"];
+}
+/**
+ * Wraps a ClientSideConnection + child process lifecycle.
+ * Manages spawn → initialize → session/new → prompt → cancel → close.
+ *
+ * Implements ALL ACP Client callbacks:
+ * - requestPermission (auto-approve or delegate)
+ * - sessionUpdate
+ * - fs/read_text_file (with line/limit)
+ * - fs/write_text_file
+ * - terminal/* (create, output, wait_for_exit, kill, release)
+ */
+declare class AcpConnection {
+    private child;
+    private conn;
+    private initResponse;
+    private sessions;
+    private updateListeners;
+    private readonly options;
+    private readonly terminalManager;
+    private enforcer;
+    private auditLogger;
+    constructor(options?: AcpConnectionOptions);
+    /** Update the permission policy at runtime (hot-reload). */
+    updatePermissionPolicy(config: PermissionsConfig): void;
+    get isConnected(): boolean;
+    get agentCapabilities(): InitializeResponse | null;
+    get rawConnection(): ClientSideConnection | null;
+    spawn(command: string, args: string[], cwd: string): Promise<void>;
+    initialize(): Promise<InitializeResponse>;
+    newSession(cwd: string, mcpServers?: NewSessionResponse["modes"] extends unknown ? unknown[] : never[]): Promise<AcpSessionInfo>;
+    loadSession(sessionId: string, cwd: string): Promise<void>;
+    setSessionMode(sessionId: string, modeId: string): Promise<void>;
+    setSessionConfigOption(sessionId: string, configId: string, value: string): Promise<unknown>;
+    authenticate(methodId: string): Promise<void>;
+    /**
+     * Send a prompt with arbitrary content blocks.
+     * For text-only convenience, use the string overload.
+     */
+    prompt(sessionId: string, content: string | ContentBlock[]): Promise<{
+        stopReason: string;
+        text: string;
+    }>;
+    /**
+     * Stream prompt — yields every SessionNotification as it arrives.
+     */
+    streamPrompt(sessionId: string, content: string | ContentBlock[]): AsyncIterable<SessionNotification>;
+    cancel(sessionId: string): Promise<void>;
+    getSession(sessionId: string): AcpSessionInfo | undefined;
+    listSessions(): string[];
+    close(): Promise<void>;
+    private buildClient;
+    private localRequestPermission;
+    private localSessionUpdate;
+    private localReadTextFile;
+    private localWriteTextFile;
+    addUpdateListener(sessionId: string, listener: (n: SessionNotification) => void): void;
+    removeUpdateListener(sessionId: string, listener: (n: SessionNotification) => void): void;
+}
+
+/**
+ * Upstream (IDE) handler interface.
+ * When a lease is active, agent callbacks are forwarded to the IDE
+ * through this interface, which wraps the AgentSideConnection facing the IDE.
+ */
+interface UpstreamHandler {
+    requestPermission(params: RequestPermissionRequest): Promise<RequestPermissionResponse>;
+    sessionUpdate(params: SessionNotification): Promise<void>;
+    readTextFile(params: ReadTextFileRequest): Promise<ReadTextFileResponse>;
+    writeTextFile(params: WriteTextFileRequest): Promise<WriteTextFileResponse>;
+    createTerminal(params: CreateTerminalRequest): Promise<CreateTerminalResponse>;
+    terminalOutput(params: TerminalOutputRequest): Promise<TerminalOutputResponse>;
+    waitForTerminalExit(params: WaitForTerminalExitRequest): Promise<WaitForTerminalExitResponse>;
+    killTerminal(params: KillTerminalCommandRequest): Promise<KillTerminalCommandResponse>;
+    releaseTerminal(params: ReleaseTerminalRequest): Promise<ReleaseTerminalResponse>;
+}
+/**
+ * Routes Client callbacks from the Agent to either:
+ *   (A) the IDE (upstream) — when a lease is active and IDE supports the capability
+ *   (B) local handlers (impersonation) — when no lease or IDE lacks the capability
+ *
+ * The Agent always sees full capabilities; the router handles fallback transparently.
+ */
+declare class ClientCallbackRouter implements ClientCallbackHandler {
+    private readonly local;
+    private upstream;
+    private ideCapabilities;
+    private enforcer;
+    constructor(local: ClientCallbackHandler);
+    /** Attach a PermissionPolicyEnforcer for pre-filtering in lease mode. */
+    setEnforcer(enforcer: PermissionPolicyEnforcer | null): void;
+    /**
+     * Activate lease-forwarding mode.
+     * Callbacks will be routed to the IDE for supported capabilities.
+     */
+    attachUpstream(handler: UpstreamHandler, capabilities: ClientCapabilities): void;
+    /**
+     * Deactivate lease-forwarding. All callbacks revert to local handlers.
+     */
+    detachUpstream(): void;
+    get isLeaseActive(): boolean;
+    requestPermission(params: RequestPermissionRequest): Promise<RequestPermissionResponse>;
+    sessionUpdate(params: SessionNotification): Promise<void>;
+    readTextFile(params: ReadTextFileRequest): Promise<ReadTextFileResponse>;
+    writeTextFile(params: WriteTextFileRequest): Promise<WriteTextFileResponse>;
+    createTerminal(params: CreateTerminalRequest): Promise<CreateTerminalResponse>;
+    terminalOutput(params: TerminalOutputRequest): Promise<TerminalOutputResponse>;
+    waitForTerminalExit(params: WaitForTerminalExitRequest): Promise<WaitForTerminalExitResponse>;
+    killTerminal(params: KillTerminalCommandRequest): Promise<KillTerminalCommandResponse>;
+    releaseTerminal(params: ReleaseTerminalRequest): Promise<ReleaseTerminalResponse>;
+}
+
+interface GatewayOptions {
+    /** The downstream AcpConnection (Daemon → Agent). */
+    downstream: AcpConnection;
+    /** The callback router to attach upstream when IDE connects. */
+    callbackRouter: ClientCallbackRouter;
+}
+/**
+ * ACP Gateway — bridges upstream IDE (ACP Client) and downstream Agent (ACP Server).
+ *
+ * Architecture:
+ *   IDE ← ACP/socket → AgentSideConnection (upstream)
+ *                            ↕ (bridged)
+ *                       ClientSideConnection (downstream) ← ACP/stdio → Agent
+ *
+ * The Gateway:
+ * - Exposes an Agent interface to the IDE via AgentSideConnection
+ * - Forwards IDE requests (prompt, cancel, etc.) to the downstream Agent
+ * - Routes Agent callbacks (permissions, fs, terminal) to IDE or local
+ *   via the ClientCallbackRouter
+ */
+declare class AcpGateway {
+    private upstream;
+    private readonly downstream;
+    private readonly callbackRouter;
+    private ideCapabilities;
+    /**
+     * WORKAROUND for SDK API limitation (see #95):
+     * AgentSideConnection exposes flat methods for fs (readTextFile, writeTextFile)
+     * but wraps terminal ops behind TerminalHandle. Ideally the Gateway should be
+     * stateless — the IDE (Client) manages its own terminal state keyed by terminalId.
+     * We maintain this map only because the SDK doesn't expose flat terminalOutput(),
+     * waitForTerminalExit(), killTerminal(), releaseTerminal() on AgentSideConnection.
+     * Remove this once the SDK adds flat terminal methods.
+     */
+    private terminalHandles;
+    constructor(options: GatewayOptions);
+    get isUpstreamConnected(): boolean;
+    /**
+     * Accept an IDE connection on a Unix/named-pipe socket.
+     * Creates an AgentSideConnection that bridges to the downstream Agent.
+     */
+    acceptSocket(socket: Socket): void;
+    /**
+     * Disconnect the upstream IDE.
+     */
+    disconnectUpstream(): void;
+    private buildAgentHandler;
+}
+
+interface ConnectOptions {
+    command: string;
+    args: string[];
+    cwd: string;
+    connectionOptions?: AcpConnectionOptions;
+}
+/**
+ * Manages a pool of ACP connections keyed by agent instance name.
+ * Handles spawn → initialize → session lifecycle for each agent.
+ * Supports Gateway mode for Session Lease (IDE ↔ Gateway ↔ Agent).
+ */
+declare class AcpConnectionManager {
+    private connections;
+    private primarySessions;
+    private routers;
+    private gateways;
+    private enforcers;
+    /**
+     * Spawn an ACP agent process, initialize, and create a default session.
+     * Uses ClientCallbackRouter so Gateway can later attach an IDE upstream.
+     * When connectionOptions.permissionPolicy is set, creates a PermissionPolicyEnforcer
+     * for Layer 2 ACP Client allowlist enforcement.
+     */
+    connect(name: string, options: ConnectOptions): Promise<AcpSessionInfo>;
+    /**
+     * Accept an IDE connection on the Gateway for a named agent.
+     * The IDE socket carries ACP protocol messages.
+     */
+    acceptLeaseSocket(name: string, socket: Socket): void;
+    /**
+     * Disconnect IDE from the Gateway.
+     */
+    disconnectLease(name: string): void;
+    getConnection(name: string): AcpConnection | undefined;
+    getGateway(name: string): AcpGateway | undefined;
+    getRouter(name: string): ClientCallbackRouter | undefined;
+    getPrimarySessionId(name: string): string | undefined;
+    has(name: string): boolean;
+    disconnect(name: string): Promise<void>;
+    disposeAll(): Promise<void>;
+    /**
+     * Update the permission policy for a named connection at runtime.
+     * Propagates to both the AcpConnection and the local handler enforcer.
+     */
+    updatePermissionPolicy(name: string, config: PermissionsConfig): void;
+}
+
+/**
+ * Bridges an AcpConnection to the AgentCommunicator interface.
+ * Used by AgentManager to send prompts through ACP sessions.
+ */
+declare class AcpCommunicator implements AgentCommunicator {
+    private readonly connection;
+    private readonly sessionId;
+    constructor(connection: AcpConnection, sessionId: string);
+    runPrompt(_workspaceDir: string, prompt: string, _options?: RunPromptOptions): Promise<PromptResult>;
+    streamPrompt(_workspaceDir: string, prompt: string, _options?: RunPromptOptions): AsyncIterable<StreamChunk>;
+}
+
+/**
+ * Manages local terminal processes for ACP Client terminal/* callbacks.
+ * Each terminal is a child process with captured stdout/stderr output.
+ */
+declare class LocalTerminalManager {
+    private terminals;
+    private counter;
+    createTerminal(params: CreateTerminalRequest): Promise<CreateTerminalResponse>;
+    terminalOutput(params: TerminalOutputRequest): Promise<TerminalOutputResponse>;
+    waitForExit(params: WaitForTerminalExitRequest): Promise<WaitForTerminalExitResponse>;
+    killTerminal(params: KillTerminalCommandRequest): Promise<KillTerminalCommandResponse>;
+    releaseTerminal(params: ReleaseTerminalRequest): Promise<ReleaseTerminalResponse>;
+    disposeAll(): void;
+    private getTerminal;
+}
+
+export { AcpCommunicator, AcpConnection, AcpConnectionManager, type AcpConnectionOptions, AcpGateway, type AcpSessionInfo, type ClientCallbackHandler, ClientCallbackRouter, type ConnectOptions, type GatewayOptions, LocalTerminalManager, type UpstreamHandler };