@posthog/agent 1.24.2 → 1.25.0

package/dist/node_modules/@agentclientprotocol/sdk/dist/acp.js

@@ -0,0 +1,610 @@
+import { z } from 'zod';
+import { CLIENT_METHODS, AGENT_METHODS, setSessionModelRequestSchema, promptRequestSchema, authenticateRequestSchema, setSessionModeRequestSchema, loadSessionRequestSchema, newSessionRequestSchema, initializeRequestSchema, cancelNotificationSchema } from './schema.js';
+export { agentCapabilitiesSchema, agentNotificationSchema, agentOutgoingMessageSchema, agentRequestSchema, agentResponseSchema, annotationsSchema, authMethodSchema, authenticateResponseSchema, availableCommandInputSchema, availableCommandSchema, blobResourceContentsSchema, clientCapabilitiesSchema, clientNotificationSchema, clientOutgoingMessageSchema, clientRequestSchema, clientResponseSchema, contentBlockSchema, createTerminalRequestSchema, createTerminalResponseSchema, embeddedResourceResourceSchema, envVariableSchema, errorSchema, extMethodRequest1Schema, extMethodRequestSchema, extMethodResponse1Schema, extMethodResponseSchema, extNotification1Schema, extNotificationSchema, fileSystemCapabilitySchema, httpHeaderSchema, implementationSchema, initializeResponseSchema, killTerminalCommandRequestSchema, killTerminalResponseSchema, loadSessionResponseSchema, mcpCapabilitiesSchema, mcpServerSchema, modelInfoSchema, newSessionResponseSchema, notification1Schema, notificationSchema, null1Schema, nullSchema, number1Schema, numberSchema, permissionOptionSchema, planEntrySchema, promptCapabilitiesSchema, promptResponseSchema, readTextFileRequestSchema, readTextFileResponseSchema, releaseTerminalRequestSchema, releaseTerminalResponseSchema, request1Schema, requestPermissionRequestSchema, requestPermissionResponseSchema, requestSchema, response1Schema, responseSchema, roleSchema, sessionModeIdSchema, sessionModeSchema, sessionModeStateSchema, sessionModelStateSchema, sessionNotificationSchema, setSessionModeResponseSchema, setSessionModelResponseSchema, stdioSchema, string1Schema, stringSchema, terminalExitStatusSchema, terminalOutputRequestSchema, terminalOutputResponseSchema, textResourceContentsSchema, toolCallContentSchema, toolCallLocationSchema, toolCallStatusSchema, toolKindSchema, unstructuredCommandInputSchema, waitForTerminalExitRequestSchema, waitForTerminalExitResponseSchema, writeTextFileRequestSchema, writeTextFileResponseSchema } from './schema.js';
+
+/**
+ * An agent-side connection to a client.
+ *
+ * This class provides the agent's view of an ACP connection, allowing
+ * agents to communicate with clients. It implements the {@link Client} interface
+ * to provide methods for requesting permissions, accessing the file system,
+ * and sending session updates.
+ *
+ * See protocol docs: [Agent](https://agentclientprotocol.com/protocol/overview#agent)
+ */
+class AgentSideConnection {
+    #connection;
+    /**
+     * Creates a new agent-side connection to a client.
+     *
+     * This establishes the communication channel from the agent's perspective
+     * following the ACP specification.
+     *
+     * @param toAgent - A function that creates an Agent handler to process incoming client requests
+     * @param stream - The bidirectional message stream for communication. Typically created using
+     *                 {@link ndJsonStream} for stdio-based connections.
+     *
+     * See protocol docs: [Communication Model](https://agentclientprotocol.com/protocol/overview#communication-model)
+     */
+    constructor(toAgent, stream) {
+        const agent = toAgent(this);
+        const requestHandler = async (method, params) => {
+            switch (method) {
+                case AGENT_METHODS.initialize: {
+                    const validatedParams = initializeRequestSchema.parse(params);
+                    return agent.initialize(validatedParams);
+                }
+                case AGENT_METHODS.session_new: {
+                    const validatedParams = newSessionRequestSchema.parse(params);
+                    return agent.newSession(validatedParams);
+                }
+                case AGENT_METHODS.session_load: {
+                    if (!agent.loadSession) {
+                        throw RequestError.methodNotFound(method);
+                    }
+                    const validatedParams = loadSessionRequestSchema.parse(params);
+                    return agent.loadSession(validatedParams);
+                }
+                case AGENT_METHODS.session_set_mode: {
+                    if (!agent.setSessionMode) {
+                        throw RequestError.methodNotFound(method);
+                    }
+                    const validatedParams = setSessionModeRequestSchema.parse(params);
+                    const result = await agent.setSessionMode(validatedParams);
+                    return result ?? {};
+                }
+                case AGENT_METHODS.authenticate: {
+                    const validatedParams = authenticateRequestSchema.parse(params);
+                    const result = await agent.authenticate(validatedParams);
+                    return result ?? {};
+                }
+                case AGENT_METHODS.session_prompt: {
+                    const validatedParams = promptRequestSchema.parse(params);
+                    return agent.prompt(validatedParams);
+                }
+                case AGENT_METHODS.session_set_model: {
+                    if (!agent.setSessionModel) {
+                        throw RequestError.methodNotFound(method);
+                    }
+                    const validatedParams = setSessionModelRequestSchema.parse(params);
+                    const result = await agent.setSessionModel(validatedParams);
+                    return result ?? {};
+                }
+                default:
+                    if (method.startsWith("_")) {
+                        if (!agent.extMethod) {
+                            throw RequestError.methodNotFound(method);
+                        }
+                        return agent.extMethod(method.substring(1), params);
+                    }
+                    throw RequestError.methodNotFound(method);
+            }
+        };
+        const notificationHandler = async (method, params) => {
+            switch (method) {
+                case AGENT_METHODS.session_cancel: {
+                    const validatedParams = cancelNotificationSchema.parse(params);
+                    return agent.cancel(validatedParams);
+                }
+                default:
+                    if (method.startsWith("_")) {
+                        if (!agent.extNotification) {
+                            return;
+                        }
+                        return agent.extNotification(method.substring(1), params);
+                    }
+                    throw RequestError.methodNotFound(method);
+            }
+        };
+        this.#connection = new Connection(requestHandler, notificationHandler, stream);
+    }
+    /**
+     * Handles session update notifications from the agent.
+     *
+     * This is a notification endpoint (no response expected) that sends
+     * real-time updates about session progress, including message chunks,
+     * tool calls, and execution plans.
+     *
+     * Note: Clients SHOULD continue accepting tool call updates even after
+     * sending a `session/cancel` notification, as the agent may send final
+     * updates before responding with the cancelled stop reason.
+     *
+     * See protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/prompt-turn#3-agent-reports-output)
+     */
+    async sessionUpdate(params) {
+        return await this.#connection.sendNotification(CLIENT_METHODS.session_update, params);
+    }
+    /**
+     * Requests permission from the user for a tool call operation.
+     *
+     * Called by the agent when it needs user authorization before executing
+     * a potentially sensitive operation. The client should present the options
+     * to the user and return their decision.
+     *
+     * If the client cancels the prompt turn via `session/cancel`, it MUST
+     * respond to this request with `RequestPermissionOutcome::Cancelled`.
+     *
+     * See protocol docs: [Requesting Permission](https://agentclientprotocol.com/protocol/tool-calls#requesting-permission)
+     */
+    async requestPermission(params) {
+        return await this.#connection.sendRequest(CLIENT_METHODS.session_request_permission, params);
+    }
+    /**
+     * Reads content from a text file in the client's file system.
+     *
+     * Only available if the client advertises the `fs.readTextFile` capability.
+     * Allows the agent to access file contents within the client's environment.
+     *
+     * See protocol docs: [Client](https://agentclientprotocol.com/protocol/overview#client)
+     */
+    async readTextFile(params) {
+        return await this.#connection.sendRequest(CLIENT_METHODS.fs_read_text_file, params);
+    }
+    /**
+     * Writes content to a text file in the client's file system.
+     *
+     * Only available if the client advertises the `fs.writeTextFile` capability.
+     * Allows the agent to create or modify files within the client's environment.
+     *
+     * See protocol docs: [Client](https://agentclientprotocol.com/protocol/overview#client)
+     */
+    async writeTextFile(params) {
+        return ((await this.#connection.sendRequest(CLIENT_METHODS.fs_write_text_file, params)) ?? {});
+    }
+    /**
+     * Executes a command in a new terminal.
+     *
+     * Returns a `TerminalHandle` that can be used to get output, wait for exit,
+     * kill the command, or release the terminal.
+     *
+     * The terminal can also be embedded in tool calls by using its ID in
+     * `ToolCallContent` with type "terminal".
+     *
+     * @param params - The terminal creation parameters
+     * @returns A handle to control and monitor the terminal
+     */
+    async createTerminal(params) {
+        const response = await this.#connection.sendRequest(CLIENT_METHODS.terminal_create, params);
+        return new TerminalHandle(response.terminalId, params.sessionId, this.#connection);
+    }
+    /**
+     * Extension method
+     *
+     * Allows the Agent to send an arbitrary request that is not part of the ACP spec.
+     */
+    async extMethod(method, params) {
+        return await this.#connection.sendRequest(`_${method}`, params);
+    }
+    /**
+     * Extension notification
+     *
+     * Allows the Agent to send an arbitrary notification that is not part of the ACP spec.
+     */
+    async extNotification(method, params) {
+        return await this.#connection.sendNotification(`_${method}`, params);
+    }
+    /**
+     * AbortSignal that aborts when the connection closes.
+     *
+     * This signal can be used to:
+     * - Listen for connection closure: `connection.signal.addEventListener('abort', () => {...})`
+     * - Check connection status synchronously: `if (connection.signal.aborted) {...}`
+     * - Pass to other APIs (fetch, setTimeout) for automatic cancellation
+     *
+     * The connection closes when the underlying stream ends, either normally or due to an error.
+     *
+     * @example
+     * ```typescript
+     * const connection = new AgentSideConnection(agent, stream);
+     *
+     * // Listen for closure
+     * connection.signal.addEventListener('abort', () => {
+     *   console.log('Connection closed - performing cleanup');
+     * });
+     *
+     * // Check status
+     * if (connection.signal.aborted) {
+     *   console.log('Connection is already closed');
+     * }
+     *
+     * // Pass to other APIs
+     * fetch(url, { signal: connection.signal });
+     * ```
+     */
+    get signal() {
+        return this.#connection.signal;
+    }
+    /**
+     * Promise that resolves when the connection closes.
+     *
+     * The connection closes when the underlying stream ends, either normally or due to an error.
+     * Once closed, the connection cannot send or receive any more messages.
+     *
+     * This is useful for async/await style cleanup:
+     *
+     * @example
+     * ```typescript
+     * const connection = new AgentSideConnection(agent, stream);
+     * await connection.closed;
+     * console.log('Connection closed - performing cleanup');
+     * ```
+     */
+    get closed() {
+        return this.#connection.closed;
+    }
+}
+/**
+ * Handle for controlling and monitoring a terminal created via `createTerminal`.
+ *
+ * Provides methods to:
+ * - Get current output without waiting
+ * - Wait for command completion
+ * - Kill the running command
+ * - Release terminal resources
+ *
+ * **Important:** Always call `release()` when done with the terminal to free resources.
+
+ * The terminal supports async disposal via `Symbol.asyncDispose` for automatic cleanup.
+
+ * You can use `await using` to ensure the terminal is automatically released when it
+ * goes out of scope.
+ */
+class TerminalHandle {
+    id;
+    #sessionId;
+    #connection;
+    constructor(id, sessionId, conn) {
+        this.id = id;
+        this.#sessionId = sessionId;
+        this.#connection = conn;
+    }
+    /**
+     * Gets the current terminal output without waiting for the command to exit.
+     */
+    async currentOutput() {
+        return await this.#connection.sendRequest(CLIENT_METHODS.terminal_output, {
+            sessionId: this.#sessionId,
+            terminalId: this.id,
+        });
+    }
+    /**
+     * Waits for the terminal command to complete and returns its exit status.
+     */
+    async waitForExit() {
+        return await this.#connection.sendRequest(CLIENT_METHODS.terminal_wait_for_exit, {
+            sessionId: this.#sessionId,
+            terminalId: this.id,
+        });
+    }
+    /**
+     * Kills the terminal command without releasing the terminal.
+     *
+     * The terminal remains valid after killing, allowing you to:
+     * - Get the final output with `currentOutput()`
+     * - Check the exit status
+     * - Release the terminal when done
+     *
+     * Useful for implementing timeouts or cancellation.
+     */
+    async kill() {
+        return ((await this.#connection.sendRequest(CLIENT_METHODS.terminal_kill, {
+            sessionId: this.#sessionId,
+            terminalId: this.id,
+        })) ?? {});
+    }
+    /**
+     * Releases the terminal and frees all associated resources.
+     *
+     * If the command is still running, it will be killed.
+     * After release, the terminal ID becomes invalid and cannot be used
+     * with other terminal methods.
+     *
+     * Tool calls that already reference this terminal will continue to
+     * display its output.
+     *
+     * **Important:** Always call this method when done with the terminal.
+     */
+    async release() {
+        return ((await this.#connection.sendRequest(CLIENT_METHODS.terminal_release, {
+            sessionId: this.#sessionId,
+            terminalId: this.id,
+        })) ?? {});
+    }
+    async [Symbol.asyncDispose]() {
+        await this.release();
+    }
+}
+class Connection {
+    #pendingResponses = new Map();
+    #nextRequestId = 0;
+    #requestHandler;
+    #notificationHandler;
+    #stream;
+    #writeQueue = Promise.resolve();
+    #abortController = new AbortController();
+    #closedPromise;
+    constructor(requestHandler, notificationHandler, stream) {
+        this.#requestHandler = requestHandler;
+        this.#notificationHandler = notificationHandler;
+        this.#stream = stream;
+        this.#closedPromise = new Promise((resolve) => {
+            this.#abortController.signal.addEventListener("abort", () => resolve());
+        });
+        this.#receive();
+    }
+    /**
+     * AbortSignal that aborts when the connection closes.
+     *
+     * This signal can be used to:
+     * - Listen for connection closure via event listeners
+     * - Check connection status synchronously with `signal.aborted`
+     * - Pass to other APIs (fetch, setTimeout) for automatic cancellation
+     */
+    get signal() {
+        return this.#abortController.signal;
+    }
+    /**
+     * Promise that resolves when the connection closes.
+     *
+     * The connection closes when the underlying stream ends, either normally
+     * or due to an error. Once closed, the connection cannot send or receive
+     * any more messages.
+     *
+     * @example
+     * ```typescript
+     * const connection = new ClientSideConnection(client, stream);
+     * await connection.closed;
+     * console.log('Connection closed - performing cleanup');
+     * ```
+     */
+    get closed() {
+        return this.#closedPromise;
+    }
+    async #receive() {
+        const reader = this.#stream.readable.getReader();
+        try {
+            while (true) {
+                const { value: message, done } = await reader.read();
+                if (done) {
+                    break;
+                }
+                if (!message) {
+                    continue;
+                }
+                try {
+                    this.#processMessage(message);
+                }
+                catch (err) {
+                    console.error("Unexpected error during message processing:", message, err);
+                    // Only send error response if the message had an id (was a request)
+                    if ("id" in message && message.id !== undefined) {
+                        this.#sendMessage({
+                            jsonrpc: "2.0",
+                            id: message.id,
+                            error: {
+                                code: -32700,
+                                message: "Parse error",
+                            },
+                        });
+                    }
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+            this.#abortController.abort();
+        }
+    }
+    async #processMessage(message) {
+        if ("method" in message && "id" in message) {
+            // It's a request
+            const response = await this.#tryCallRequestHandler(message.method, message.params);
+            if ("error" in response) {
+                console.error("Error handling request", message, response.error);
+            }
+            await this.#sendMessage({
+                jsonrpc: "2.0",
+                id: message.id,
+                ...response,
+            });
+        }
+        else if ("method" in message) {
+            // It's a notification
+            const response = await this.#tryCallNotificationHandler(message.method, message.params);
+            if ("error" in response) {
+                console.error("Error handling notification", message, response.error);
+            }
+        }
+        else if ("id" in message) {
+            // It's a response
+            this.#handleResponse(message);
+        }
+        else {
+            console.error("Invalid message", { message });
+        }
+    }
+    async #tryCallRequestHandler(method, params) {
+        try {
+            const result = await this.#requestHandler(method, params);
+            return { result: result ?? null };
+        }
+        catch (error) {
+            if (error instanceof RequestError) {
+                return error.toResult();
+            }
+            if (error instanceof z.ZodError) {
+                return RequestError.invalidParams(error.format()).toResult();
+            }
+            let details;
+            if (error instanceof Error) {
+                details = error.message;
+            }
+            else if (typeof error === "object" &&
+                error != null &&
+                "message" in error &&
+                typeof error.message === "string") {
+                details = error.message;
+            }
+            try {
+                return RequestError.internalError(details ? JSON.parse(details) : {}).toResult();
+            }
+            catch {
+                return RequestError.internalError({ details }).toResult();
+            }
+        }
+    }
+    async #tryCallNotificationHandler(method, params) {
+        try {
+            await this.#notificationHandler(method, params);
+            return { result: null };
+        }
+        catch (error) {
+            if (error instanceof RequestError) {
+                return error.toResult();
+            }
+            if (error instanceof z.ZodError) {
+                return RequestError.invalidParams(error.format()).toResult();
+            }
+            let details;
+            if (error instanceof Error) {
+                details = error.message;
+            }
+            else if (typeof error === "object" &&
+                error != null &&
+                "message" in error &&
+                typeof error.message === "string") {
+                details = error.message;
+            }
+            try {
+                return RequestError.internalError(details ? JSON.parse(details) : {}).toResult();
+            }
+            catch {
+                return RequestError.internalError({ details }).toResult();
+            }
+        }
+    }
+    #handleResponse(response) {
+        const pendingResponse = this.#pendingResponses.get(response.id);
+        if (pendingResponse) {
+            if ("result" in response) {
+                pendingResponse.resolve(response.result);
+            }
+            else if ("error" in response) {
+                pendingResponse.reject(response.error);
+            }
+            this.#pendingResponses.delete(response.id);
+        }
+        else {
+            console.error("Got response to unknown request", response.id);
+        }
+    }
+    async sendRequest(method, params) {
+        const id = this.#nextRequestId++;
+        const responsePromise = new Promise((resolve, reject) => {
+            this.#pendingResponses.set(id, { resolve, reject });
+        });
+        await this.#sendMessage({ jsonrpc: "2.0", id, method, params });
+        return responsePromise;
+    }
+    async sendNotification(method, params) {
+        await this.#sendMessage({ jsonrpc: "2.0", method, params });
+    }
+    async #sendMessage(message) {
+        this.#writeQueue = this.#writeQueue
+            .then(async () => {
+            const writer = this.#stream.writable.getWriter();
+            try {
+                await writer.write(message);
+            }
+            finally {
+                writer.releaseLock();
+            }
+        })
+            .catch((error) => {
+            // Continue processing writes on error
+            console.error("ACP write error:", error);
+        });
+        return this.#writeQueue;
+    }
+}
+/**
+ * JSON-RPC error object.
+ *
+ * Represents an error that occurred during method execution, following the
+ * JSON-RPC 2.0 error object specification with optional additional data.
+ *
+ * See protocol docs: [JSON-RPC Error Object](https://www.jsonrpc.org/specification#error_object)
+ */
+class RequestError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.code = code;
+        this.name = "RequestError";
+        this.data = data;
+    }
+    /**
+     * Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text.
+     */
+    static parseError(data, additionalMessage) {
+        return new RequestError(-32700, `Parse error${additionalMessage ? `: ${additionalMessage}` : ""}`, data);
+    }
+    /**
+     * The JSON sent is not a valid Request object.
+     */
+    static invalidRequest(data, additionalMessage) {
+        return new RequestError(-32600, `Invalid request${additionalMessage ? `: ${additionalMessage}` : ""}`, data);
+    }
+    /**
+     * The method does not exist / is not available.
+     */
+    static methodNotFound(method) {
+        return new RequestError(-32601, `"Method not found": ${method}`, {
+            method,
+        });
+    }
+    /**
+     * Invalid method parameter(s).
+     */
+    static invalidParams(data, additionalMessage) {
+        return new RequestError(-32602, `Invalid params${additionalMessage ? `: ${additionalMessage}` : ""}`, data);
+    }
+    /**
+     * Internal JSON-RPC error.
+     */
+    static internalError(data, additionalMessage) {
+        return new RequestError(-32603, `Internal error${additionalMessage ? `: ${additionalMessage}` : ""}`, data);
+    }
+    /**
+     * Authentication required.
+     */
+    static authRequired(data, additionalMessage) {
+        return new RequestError(-32e3, `Authentication required${additionalMessage ? `: ${additionalMessage}` : ""}`, data);
+    }
+    /**
+     * Resource, such as a file, was not found
+     */
+    static resourceNotFound(uri) {
+        return new RequestError(-32002, `Resource not found${uri ? `: ${uri}` : ""}`, uri && { uri });
+    }
+    toResult() {
+        return {
+            error: {
+                code: this.code,
+                message: this.message,
+                data: this.data,
+            },
+        };
+    }
+    toErrorResponse() {
+        return {
+            code: this.code,
+            message: this.message,
+            data: this.data,
+        };
+    }
+}
+
+export { AGENT_METHODS, AgentSideConnection, CLIENT_METHODS, RequestError, TerminalHandle, authenticateRequestSchema, cancelNotificationSchema, initializeRequestSchema, loadSessionRequestSchema, newSessionRequestSchema, promptRequestSchema, setSessionModeRequestSchema, setSessionModelRequestSchema };
+//# sourceMappingURL=acp.js.map