@mondaydotcomorg/atp-client/dist/client.d.ts

Client SDK for Agent Tool Protocol

import type { ExecutionResult, ExecutionConfig, SearchOptions, SearchResult, ClientTool, ClientToolDefinition, ExploreResult } from '@mondaydotcomorg/atp-protocol';
import type { RuntimeAPIName } from '@mondaydotcomorg/atp-runtime';
import { CallbackType } from '@mondaydotcomorg/atp-protocol';
import { type ClientLLMHandler, type ClientApprovalHandler, type ClientEmbeddingHandler, type ClientServiceProviders, type ClientHooks } from './core/index.js';
import { type Tool } from './tools/index.js';
interface InProcessServer {
    start(): Promise<void>;
    handleInit(ctx: unknown): Promise<unknown>;
    getDefinitions(ctx?: unknown): Promise<unknown>;
    getRuntimeDefinitions(ctx?: unknown): Promise<string>;
    getInfo(): unknown;
    handleSearch(ctx: unknown): Promise<unknown>;
    handleExplore(ctx: unknown): Promise<unknown>;
    handleExecute(ctx: unknown): Promise<unknown>;
    handleResume(ctx: unknown, executionId: string): Promise<unknown>;
}
/**
 * Options for creating an AgentToolProtocolClient
 */
export interface AgentToolProtocolClientOptions {
    /** Base URL of the Agent Tool Protocol server (HTTP mode) */
    baseUrl?: string;
    /** Server instance for in-process mode (no HTTP, no port binding) */
    server?: InProcessServer;
    /** Optional headers for authentication (e.g., { Authorization: 'Bearer token' }) */
    headers?: Record<string, string>;
    /** Optional client-provided services (LLM, approval, embedding) */
    serviceProviders?: ClientServiceProviders;
    /** Optional hooks for intercepting and modifying client behavior */
    hooks?: ClientHooks;
}
/**
 * AgentToolProtocolClient provides a client interface for connecting to
 * Agent Tool Protocol servers and executing code.
 */
export declare class AgentToolProtocolClient {
    private session;
    private inProcessSession?;
    private apiOps;
    private execOps;
    private serviceProviders;
    /**
     * Creates a new client instance.
     *
     * @example
     * ```typescript
     * // HTTP mode
     * const client = new AgentToolProtocolClient({
     *   baseUrl: 'http://localhost:3333',
     *   headers: { Authorization: 'Bearer token' },
     *   hooks: {
     *     preRequest: async (context) => {
     *       const token = await refreshToken();
     *       return { headers: { ...context.currentHeaders, Authorization: `Bearer ${token}` } };
     *     }
     *   }
     * });
     *
     * // In-process mode (no port binding)
     * const server = createServer();
     * server.use(myApiGroup);
     * const client = new AgentToolProtocolClient({ server });
     * ```
     */
    constructor(options: AgentToolProtocolClientOptions);
    /**
     * Initializes the client session with the server.
     * Automatically registers any client-provided tools and services with the server.
     */
    init(clientInfo?: {
        name?: string;
        version?: string;
        [key: string]: unknown;
    }): Promise<{
        clientId: string;
        token: string;
        expiresAt: number;
        tokenRotateAt: number;
    }>;
    /**
     * Gets the unique client ID.
     */
    getClientId(): string;
    /**
     * Provides an LLM implementation for server to use during execution.
     */
    provideLLM(handler: ClientLLMHandler): void;
    /**
     * Provides an approval handler for server to request human approval.
     */
    provideApproval(handler: ClientApprovalHandler): void;
    /**
     * Provides an embedding model for server to use.
     */
    provideEmbedding(handler: ClientEmbeddingHandler): void;
    /**
     * Provides custom tools that execute on the client side.
     * Note: Must be called before init() or re-initialize after calling this.
     */
    provideTools(tools: ClientTool[]): void;
    /**
     * Gets all client-provided tools (registered via provideTools).
     * Returns the full tool objects including handlers.
     */
    getClientTools(): ClientTool[];
    /**
     * Gets client-provided tool definitions (without handlers).
     * Useful for sending tool metadata to servers.
     */
    getClientToolDefinitions(): ClientToolDefinition[];
    /**
     * Gets the ATP tools (execute_code, explore_api, search_api, fetch_all_apis).
     * These are ready-to-use tools that can be exposed to MCP or other frameworks.
     *
     * @example
     * ```typescript
     * const tools = client.getATPTools();
     * for (const tool of tools) {
     *   mcpServer.tool(tool.name, tool.description, tool.inputSchema, async (args) => {
     *     const result = await tool.func(args);
     *     return { content: [{ type: 'text', text: result }] };
     *   });
     * }
     * ```
     */
    getATPTools(): Tool[];
    /**
     * Connects to the server and retrieves API definitions.
     */
    connect(options?: {
        apiGroups?: string[];
    }): Promise<{
        serverVersion: string;
        capabilities: unknown;
        apiGroups: string[];
    }>;
    /**
     * Gets the TypeScript type definitions for available APIs.
     */
    getTypeDefinitions(): string;
    /**
     * Searches for available API functions.
     */
    searchAPI(query: string, options?: SearchOptions): Promise<SearchResult[]>;
    /**
     * Explores the API filesystem at the given path.
     */
    exploreAPI(path: string): Promise<ExploreResult>;
    /**
     * Executes code on the server with real-time progress updates via SSE.
     */
    executeStream(code: string, config?: Partial<ExecutionConfig>, onProgress?: (message: string, fraction: number) => void): Promise<ExecutionResult>;
    /**
     * Executes code on the server in a sandboxed environment.
     */
    execute(code: string, config?: Partial<ExecutionConfig>): Promise<ExecutionResult>;
    /**
     * Resumes a paused execution with a callback result.
     */
    resume(executionId: string, callbackResult: unknown): Promise<ExecutionResult>;
    /**
     * Handles a callback request from the server during execution.
     */
    handleCallback(callbackType: CallbackType, payload: any): Promise<any>;
    /**
     * Gets information about the server.
     */
    getServerInfo(): Promise<{
        version: string;
        capabilities: Record<string, boolean>;
    }>;
    /**
     * Gets ATP runtime API definitions as TypeScript declarations.
     * Returns the full TypeScript definitions for atp.llm.*, atp.cache.*, etc.
     * These are the APIs available during code execution.
     *
     * Behavior:
     * - No options: Returns APIs based on client capabilities (default filtering)
     * - apis: ['llm', 'cache']: Returns only specified APIs (intersection with client capabilities)
     * - apis: []: Returns all APIs regardless of client capabilities
     *
     * @param options - Optional filtering options
     * @param options.apis - Specific APIs to include (e.g., ['llm', 'cache', 'approval'])
     */
    getRuntimeDefinitions(options?: {
        apis?: RuntimeAPIName[];
    }): Promise<string>;
}
export {};
//# sourceMappingURL=client.d.ts.map