gauss-ts 1.1.0 → 2.0.0

package/dist/{agent-CMp1wFzs.d.cts → agent-DXZT4Hd-.d.cts}

@@ -1,4 +1,6 @@
-import { H as Handle, T as ToolDef, M as Message, A as AgentOptions, a as ToolExecutor, b as AgentResult, D as Disposable, P as ProviderType, c as ProviderOptions, C as CodeExecutionOptions, d as ProviderCapabilities, S as StreamCallback } from './types-BkwC4s1P.cjs';
+import { H as Handle, T as ToolDef, a as Message, A as AgentOptions, b as ToolExecutor, c as AgentResult, D as Disposable, d as ProviderType, e as ProviderOptions, C as CodeExecutionOptions, f as ProviderCapabilities, S as StreamCallback } from './types-BayYAhZL.cjs';
+import { M as MiddlewareChain, G as GuardrailChain } from './guardrail-BGqhOeWA.cjs';
+import { M as Memory } from './memory-BGrAWNqI.cjs';
 
 /**
  * A single event emitted during agent streaming.
@@ -100,6 +102,219 @@ declare class AgentStream implements AsyncIterable<StreamEvent> {
     [Symbol.asyncIterator](): AsyncIterator<StreamEvent>;
 }
 
+/**
+ * Typed Tool System — define tools with inline execute callbacks.
+ *
+ * Quick start:
+ *   const weather = tool({
+ *     name: "get_weather",
+ *     description: "Get current weather for a city",
+ *     parameters: { city: { type: "string", description: "City name" } },
+ *     execute: async ({ city }) => ({ temp: 72, unit: "F", city }),
+ *   });
+ *   agent.addTools([weather]);
+ *
+ * The tool() helper creates a TypedToolDef that the agent auto-wires
+ * into a ToolExecutor when it detects typed tools with execute callbacks.
+ *
+ * @since 1.2.0
+ */
+
+/**
+ * A tool definition with a typed execute callback.
+ *
+ * @typeParam TParams - The shape of the tool's input parameters.
+ * @typeParam TResult - The shape of the tool's return value.
+ */
+interface TypedToolDef<TParams = Record<string, unknown>, TResult = unknown> extends ToolDef {
+    /** The function to execute when the LLM invokes this tool. */
+    execute: (params: TParams) => Promise<TResult> | TResult;
+}
+/**
+ * Create a typed tool with an inline execute callback.
+ *
+ * @description Defines a tool that the agent can invoke during the agentic loop.
+ * When the LLM calls this tool, the `execute` callback is automatically invoked
+ * with the parsed parameters and the return value is sent back to the model.
+ *
+ * @param config - Tool configuration with name, description, parameters schema, and execute callback.
+ * @returns A {@link TypedToolDef} that can be passed to `agent.addTool()` or `agent.addTools()`.
+ *
+ * @example
+ * ```ts
+ * const calculator = tool({
+ *   name: "calculate",
+ *   description: "Evaluate a math expression",
+ *   parameters: {
+ *     expression: { type: "string", description: "Math expression to evaluate" },
+ *   },
+ *   execute: async ({ expression }) => {
+ *     return { result: eval(expression) };
+ *   },
+ * });
+ *
+ * const agent = new Agent({ instructions: "You can do math." });
+ * agent.addTools([calculator]);
+ * const result = await agent.run("What is 2+2?");
+ * ```
+ *
+ * @since 1.2.0
+ */
+declare function tool<TParams = Record<string, unknown>, TResult = unknown>(config: {
+    name: string;
+    description: string;
+    parameters?: Record<string, unknown>;
+    execute: (params: TParams) => Promise<TResult> | TResult;
+}): TypedToolDef<TParams, TResult>;
+/**
+ * Check if a tool definition has an execute callback (is a TypedToolDef).
+ */
+declare function isTypedTool(t: ToolDef): t is TypedToolDef;
+/**
+ * Build a {@link ToolExecutor} from an array of typed tools.
+ *
+ * @description Creates a single async function that dispatches tool calls
+ * to the correct typed tool's execute callback based on the tool name.
+ *
+ * @param tools - Array of typed tool definitions with execute callbacks.
+ * @param fallback - Optional fallback executor for tools without execute callbacks.
+ * @returns A {@link ToolExecutor} that can be passed to `agent.runWithTools()`.
+ *
+ * @since 1.2.0
+ */
+declare function createToolExecutor(tools: TypedToolDef<any, any>[], fallback?: ToolExecutor): ToolExecutor;
+
+/**
+ * MCP Client — consume tools from external MCP servers.
+ *
+ * Quick start:
+ *   const client = new McpClient({ command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem"] });
+ *   await client.connect();
+ *   const tools = await client.listTools();
+ *   const result = await client.callTool("read_file", { path: "README.md" });
+ *   client.close();
+ *
+ * Supports stdio transport (spawn subprocess) for local MCP servers.
+ *
+ * @since 1.2.0
+ */
+
+/** Configuration for creating an MCP client. */
+interface McpClientConfig {
+    /** Command to spawn the MCP server process (stdio transport). */
+    command: string;
+    /** Arguments for the command. */
+    args?: string[];
+    /** Environment variables for the subprocess. */
+    env?: Record<string, string>;
+    /** Connection timeout in milliseconds (default: 10000). */
+    timeoutMs?: number;
+}
+/** A tool definition from an MCP server. */
+interface McpToolDef {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+}
+/** Result from calling a tool on an MCP server. */
+interface McpToolResult {
+    content: Array<{
+        type: string;
+        text?: string;
+        data?: string;
+        mimeType?: string;
+    }>;
+    isError?: boolean;
+}
+/**
+ * Client for consuming tools from external MCP (Model Context Protocol) servers.
+ *
+ * @description Connects to an MCP server via stdio transport (subprocess),
+ * performs the initialization handshake, and provides methods to list and
+ * call tools. Tools can be wired into agents via `agent.useMcpServer()`.
+ *
+ * @example
+ * ```ts
+ * const client = new McpClient({
+ *   command: "npx",
+ *   args: ["-y", "@modelcontextprotocol/server-everything"],
+ * });
+ * await client.connect();
+ *
+ * const tools = await client.listTools();
+ * console.log(tools); // [{ name: "echo", description: "...", parameters: {...} }]
+ *
+ * const result = await client.callTool("echo", { message: "hello" });
+ * console.log(result); // { content: [{ type: "text", text: "hello" }] }
+ *
+ * client.close();
+ * ```
+ *
+ * @since 1.2.0
+ */
+declare class McpClient implements Disposable {
+    private readonly config;
+    private process;
+    private connected;
+    private closed;
+    private nextId;
+    private readonly pending;
+    private buffer;
+    private serverCapabilities;
+    private cachedTools;
+    constructor(config: McpClientConfig);
+    /**
+     * Connect to the MCP server and perform the initialization handshake.
+     *
+     * @throws {Error} If connection times out or the server rejects initialization.
+     */
+    connect(): Promise<void>;
+    /**
+     * List all tools available on the connected MCP server.
+     *
+     * @returns Array of tool definitions in Gauss SDK format.
+     * @throws {Error} If not connected.
+     */
+    listTools(): Promise<ToolDef[]>;
+    /**
+     * Call a tool on the MCP server.
+     *
+     * @param toolName - Name of the tool to invoke.
+     * @param args - Arguments to pass to the tool.
+     * @returns The tool execution result.
+     * @throws {Error} If not connected or the tool call fails.
+     */
+    callTool(toolName: string, args?: Record<string, unknown>): Promise<McpToolResult>;
+    /**
+     * Get all tools as Gauss ToolDefs with a wired ToolExecutor.
+     *
+     * @description Returns the tools and a ToolExecutor that routes
+     * tool calls to this MCP server. Used by `agent.useMcpServer()`.
+     *
+     * @returns Object with `tools` (ToolDef[]) and `executor` (ToolExecutor).
+     */
+    getToolsWithExecutor(): Promise<{
+        tools: ToolDef[];
+        executor: (callJson: string) => Promise<string>;
+    }>;
+    /**
+     * Close the connection and terminate the subprocess.
+     */
+    close(): void;
+    /** Alias for close() — enables `using` pattern. */
+    destroy(): void;
+    [Symbol.dispose](): void;
+    /** Whether the client is currently connected. */
+    get isConnected(): boolean;
+    private request;
+    private notify;
+    private send;
+    private onData;
+    private onProcessError;
+    private onProcessClose;
+    private assertConnected;
+}
+
 /**
  * Configuration object for creating an {@link Agent} instance.
  *
@@ -129,8 +344,18 @@ interface AgentConfig {
     providerOptions?: ProviderOptions;
     /** System instructions prepended to every conversation. */
     instructions?: string;
-    /** Tool definitions available to the agent. */
-    tools?: ToolDef[];
+    /** Tool definitions available to the agent. Accepts both raw ToolDef and typed tools with execute callbacks. */
+    tools?: (ToolDef | TypedToolDef)[];
+    /** Middleware chain to apply (logging, caching, rate limiting). */
+    middleware?: MiddlewareChain;
+    /** Guardrail chain to apply (PII, content moderation, schema validation). */
+    guardrails?: GuardrailChain;
+    /** Memory instance for automatic conversation history. */
+    memory?: Memory;
+    /** Session ID for memory scoping (default: auto-generated). */
+    sessionId?: string;
+    /** MCP clients to consume tools from external MCP servers. */
+    mcpClients?: McpClient[];
     /** Sampling temperature (0–2). Higher values produce more creative output. */
     temperature?: number;
     /** Maximum number of agentic loop iterations before stopping. */
@@ -191,6 +416,12 @@ declare class Agent implements Disposable {
     private _tools;
     private _options;
     private disposed;
+    private _middleware;
+    private _guardrails;
+    private _memory;
+    private _sessionId;
+    private _mcpClients;
+    private _mcpToolsLoaded;
     /**
      * Create a new Agent.
      *
@@ -256,7 +487,7 @@ declare class Agent implements Disposable {
      *
      * @since 1.0.0
      */
-    addTool(tool: ToolDef): this;
+    addTool(tool: ToolDef | TypedToolDef): this;
     /**
      * Register multiple tool definitions at once. Chainable.
      *
@@ -275,7 +506,7 @@ declare class Agent implements Disposable {
      *
      * @since 1.0.0
      */
-    addTools(tools: ToolDef[]): this;
+    addTools(tools: (ToolDef | TypedToolDef)[]): this;
     /**
      * Merge additional agent options into the current configuration. Chainable.
      *
@@ -292,6 +523,79 @@ declare class Agent implements Disposable {
      * @since 1.0.0
      */
     setOptions(options: Partial<AgentOptions>): this;
+    /**
+     * Attach a middleware chain (logging, caching, rate limiting). Chainable.
+     *
+     * @param chain - A configured {@link MiddlewareChain} instance.
+     * @returns `this` for fluent chaining.
+     *
+     * @example
+     * ```ts
+     * agent.withMiddleware(
+     *   new MiddlewareChain().useLogging().useCaching(60000).useRateLimit(100)
+     * );
+     * ```
+     *
+     * @since 1.2.0
+     */
+    withMiddleware(chain: MiddlewareChain): this;
+    /**
+     * Attach a guardrail chain (content moderation, PII, schema validation). Chainable.
+     *
+     * @param chain - A configured {@link GuardrailChain} instance.
+     * @returns `this` for fluent chaining.
+     *
+     * @example
+     * ```ts
+     * agent.withGuardrails(
+     *   new GuardrailChain().addPiiDetection("redact").addContentModeration(["violence"], [])
+     * );
+     * ```
+     *
+     * @since 1.2.0
+     */
+    withGuardrails(chain: GuardrailChain): this;
+    /**
+     * Attach memory for automatic conversation history. Chainable.
+     *
+     * @description When memory is attached, the agent automatically:
+     * - Recalls recent entries before each run (prepended as context)
+     * - Stores the conversation (input + output) after each run
+     *
+     * @param memory - A {@link Memory} instance.
+     * @param sessionId - Optional session ID for scoping memory entries.
+     * @returns `this` for fluent chaining.
+     *
+     * @example
+     * ```ts
+     * const memory = new Memory();
+     * agent.withMemory(memory, "session-123");
+     * await agent.run("Hello!"); // stored in memory
+     * await agent.run("What did I just say?"); // recalls previous context
+     * ```
+     *
+     * @since 1.2.0
+     */
+    withMemory(memory: Memory, sessionId?: string): this;
+    /**
+     * Consume tools from an external MCP server. Chainable.
+     *
+     * @description Registers an MCP client whose tools will be loaded
+     * and made available to the agent on the first run.
+     *
+     * @param client - A connected {@link McpClient} instance.
+     * @returns `this` for fluent chaining.
+     *
+     * @example
+     * ```ts
+     * const mcp = new McpClient({ command: "npx", args: ["-y", "@mcp/server-fs"] });
+     * await mcp.connect();
+     * agent.useMcpServer(mcp);
+     * ```
+     *
+     * @since 1.2.0
+     */
+    useMcpServer(client: McpClient): this;
     /**
      * Run the agentic loop to completion.
      *
@@ -458,6 +762,16 @@ declare class Agent implements Disposable {
      */
     [Symbol.dispose](): void;
     private assertNotDisposed;
+    /**
+     * Resolve typed tools into plain ToolDefs + a ToolExecutor.
+     * @internal
+     */
+    private resolveToolsAndExecutor;
+    /**
+     * Load tools from all connected MCP clients (lazy, once).
+     * @internal
+     */
+    private ensureMcpTools;
 }
 /**
  * One-liner convenience function — create an agent, run a prompt, and return the text.
@@ -482,4 +796,4 @@ declare class Agent implements Disposable {
  */
 declare function gauss(prompt: string, config?: Omit<AgentConfig, "name">): Promise<string>;
 
-export { type AgentConfig as A, type StreamEvent as S, Agent as a, AgentStream as b, gauss as g };
+export { type AgentConfig as A, McpClient as M, type StreamEvent as S, type TypedToolDef as T, Agent as a, AgentStream as b, type McpClientConfig as c, type McpToolDef as d, type McpToolResult as e, createToolExecutor as f, gauss as g, isTypedTool as i, tool as t };