@strands-agents/sdk 1.0.0-rc.5 → 1.1.0

package/dist/src/interrupt.js

@@ -0,0 +1,274 @@
+/**
+ * Human-in-the-loop interrupt system for agent workflows.
+ *
+ * Interrupt Flow:
+ * 1. Hook or tool calls `event.interrupt()` or `context.interrupt()`
+ * 2. If resuming (response exists), the response is returned
+ * 3. Otherwise, agent execution halts with `stopReason: 'interrupt'`
+ * 4. User resumes by invoking agent with `interruptResponse` content blocks
+ * 5. On resume, `interrupt()` returns the user's response
+ */
+import { InterruptResponseContent } from './types/interrupt.js';
+import { Message, ToolResultBlock } from './types/messages.js';
+/**
+ * Represents an interrupt that can pause agent execution for human-in-the-loop workflows.
+ */
+export class Interrupt {
+    /**
+     * Unique identifier for this interrupt.
+     */
+    id;
+    /**
+     * User-defined name for the interrupt.
+     */
+    name;
+    /**
+     * User-provided reason for raising the interrupt.
+     */
+    reason;
+    /**
+     * Human response provided when resuming the agent after an interrupt.
+     */
+    response;
+    constructor(data) {
+        this.id = data.id;
+        this.name = data.name;
+        if (data.reason !== undefined) {
+            this.reason = data.reason;
+        }
+        if (data.response !== undefined) {
+            this.response = data.response;
+        }
+    }
+    /**
+     * Serializes the interrupt to a JSON-compatible object.
+     */
+    toJSON() {
+        return {
+            id: this.id,
+            name: this.name,
+            ...(this.reason !== undefined && { reason: this.reason }),
+            ...(this.response !== undefined && { response: this.response }),
+        };
+    }
+    /**
+     * Creates an Interrupt instance from a JSON object.
+     *
+     * @param data - JSON data to deserialize
+     * @returns Interrupt instance
+     */
+    static fromJSON(data) {
+        return new Interrupt(data);
+    }
+}
+/**
+ * Error thrown when human input is required to continue agent execution.
+ * Caught by the agent loop to trigger an interrupt stop.
+ */
+export class InterruptError extends Error {
+    /**
+     * The interrupts that caused this error.
+     */
+    interrupts;
+    constructor(interrupt) {
+        const all = Array.isArray(interrupt) ? interrupt : [interrupt];
+        const message = all.length === 1
+            ? `Interrupt raised: ${all[0].name}`
+            : `${all.length} interrupts raised: ${all.map((i) => i.name).join(', ')}`;
+        super(message);
+        this.name = 'InterruptError';
+        this.interrupts = all;
+    }
+}
+/**
+ * Tracks the state of interrupt events raised during agent execution.
+ *
+ * Interrupt state is cleared after resuming.
+ */
+export class InterruptState {
+    /** Record of interrupt IDs to Interrupt instances. */
+    interrupts;
+    /** Resume responses provided when resuming from an interrupt. */
+    resumeResponses;
+    /** Whether the agent is in an interrupted state. */
+    activated;
+    /** Pending tool execution state for resume. */
+    pendingToolExecution;
+    constructor() {
+        this.interrupts = {};
+        this.resumeResponses = undefined;
+        this.activated = false;
+        this.pendingToolExecution = undefined;
+    }
+    /**
+     * Gets the pending tool execution state with reconstructed Message and ToolResultBlock objects.
+     * Returns undefined if there is no pending execution.
+     */
+    getPendingExecution() {
+        if (!this.pendingToolExecution) {
+            return undefined;
+        }
+        const assistantMessage = Message.fromMessageData(this.pendingToolExecution.assistantMessageData);
+        const completedToolResults = new Map();
+        for (const [toolUseId, resultData] of Object.entries(this.pendingToolExecution.completedToolResults)) {
+            completedToolResults.set(toolUseId, ToolResultBlock.fromJSON(resultData));
+        }
+        return { assistantMessage, completedToolResults };
+    }
+    /**
+     * Sets the pending tool execution state.
+     */
+    setPendingToolExecution(pending) {
+        this.pendingToolExecution = pending;
+    }
+    /**
+     * Clears the pending tool execution state.
+     */
+    clearPendingToolExecution() {
+        this.pendingToolExecution = undefined;
+    }
+    /**
+     * Returns the list of interrupts as an array.
+     */
+    getInterruptsList() {
+        return Object.values(this.interrupts);
+    }
+    /**
+     * Returns all interrupts that have no response (i.e., were raised but not yet answered).
+     */
+    getUnansweredInterrupts() {
+        return Object.values(this.interrupts).filter((interrupt) => interrupt.response === undefined);
+    }
+    /**
+     * Returns the first interrupt that has no response (i.e., was raised but not yet answered).
+     */
+    getUnansweredInterrupt() {
+        for (const interrupt of Object.values(this.interrupts)) {
+            if (interrupt.response === undefined) {
+                return interrupt;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Activates the interrupt state.
+     */
+    activate() {
+        this.activated = true;
+    }
+    /**
+     * Deactivates the interrupt state and clears all interrupts and context.
+     */
+    deactivate() {
+        this.interrupts = {};
+        this.resumeResponses = undefined;
+        this.activated = false;
+        this.pendingToolExecution = undefined;
+    }
+    /**
+     * Configures the interrupt state for resuming from an interrupt.
+     * Populates interrupt responses from the provided content blocks.
+     *
+     * @param responses - Array of interrupt response content blocks
+     * @throws Error if an interrupt ID is not found
+     */
+    resume(responses) {
+        if (!this.activated) {
+            return;
+        }
+        for (const content of responses) {
+            const interruptId = content.interruptResponse.interruptId;
+            const response = content.interruptResponse.response;
+            const interrupt = this.interrupts[interruptId];
+            if (!interrupt) {
+                throw new Error(`interrupt_id=<${interruptId}> | no interrupt found`);
+            }
+            interrupt.response = response;
+        }
+        this.resumeResponses = responses;
+    }
+    /**
+     * Gets or creates an interrupt with the given ID.
+     * If the interrupt already exists, returns it (potentially with a response).
+     * If a preemptive response is provided and the interrupt is new, the response
+     * is stored on the interrupt so it returns immediately without halting execution.
+     *
+     * @param id - Unique identifier for the interrupt
+     * @param name - User-defined name for the interrupt
+     * @param reason - Optional reason for the interrupt
+     * @param response - Optional preemptive response to skip the interrupt
+     * @returns The interrupt (may have a response if resuming or preemptive)
+     */
+    getOrCreateInterrupt(id, name, reason, response) {
+        const existing = this.interrupts[id];
+        if (existing) {
+            return existing;
+        }
+        const interrupt = new Interrupt({
+            id,
+            name,
+            ...(reason !== undefined && { reason }),
+            ...(response !== undefined && { response }),
+        });
+        this.interrupts[id] = interrupt;
+        return interrupt;
+    }
+    /**
+     * Serializes the interrupt state to a JSON-compatible object.
+     */
+    toJSON() {
+        const interrupts = {};
+        for (const [id, interrupt] of Object.entries(this.interrupts)) {
+            interrupts[id] = interrupt.toJSON();
+        }
+        return {
+            interrupts,
+            ...(this.resumeResponses && { resumeResponses: this.resumeResponses }),
+            activated: this.activated,
+            ...(this.pendingToolExecution && { pendingToolExecution: this.pendingToolExecution }),
+        };
+    }
+    /**
+     * Creates an InterruptState instance from a JSON object.
+     *
+     * @param data - JSON data to deserialize
+     * @returns InterruptState instance
+     */
+    static fromJSON(data) {
+        const state = new InterruptState();
+        state.activated = data.activated;
+        for (const [id, interruptData] of Object.entries(data.interrupts)) {
+            state.interrupts[id] = Interrupt.fromJSON(interruptData);
+        }
+        if (data.resumeResponses) {
+            state.resumeResponses = data.resumeResponses.map((r) => InterruptResponseContent.fromJSON(r));
+        }
+        if (data.pendingToolExecution) {
+            state.pendingToolExecution = data.pendingToolExecution;
+        }
+        return state;
+    }
+}
+/**
+ * Shared interrupt logic that accesses the agent's interrupt state to register or resume an interrupt.
+ *
+ * @param agent - The agent whose interrupt state to access
+ * @param interruptId - Unique identifier for this interrupt instance
+ * @param params - Interrupt parameters including name and optional reason
+ * @returns The user's response when resuming from an interrupt
+ * @throws InterruptError when no response is available (first invocation)
+ *
+ * @internal
+ */
+export function interruptFromAgent(agent, interruptId, params) {
+    const interruptState = agent._interruptState;
+    if (!interruptState) {
+        throw new Error('Interrupt state not available');
+    }
+    const interrupt = interruptState.getOrCreateInterrupt(interruptId, params.name, params.reason, params.response);
+    if (interrupt.response !== undefined) {
+        return interrupt.response;
+    }
+    throw new InterruptError(interrupt);
+}
+//# sourceMappingURL=interrupt.js.map

package/dist/src/interrupt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interrupt.js","sourceRoot":"","sources":["../../src/interrupt.ts"],"names":[],"mappings":"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"}

package/dist/src/logging/__tests__/warn-once.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=warn-once.test.d.ts.map

package/dist/src/logging/__tests__/warn-once.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"warn-once.test.d.ts","sourceRoot":"","sources":["../../../../src/logging/__tests__/warn-once.test.ts"],"names":[],"mappings":""}

package/dist/src/logging/__tests__/warn-once.test.js

@@ -0,0 +1,30 @@
+import { describe, it, expect, vi } from 'vitest';
+import { warnOnce } from '../warn-once.js';
+function createLogger() {
+    return { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+}
+describe('warnOnce', () => {
+    it('emits a warning the first time a message is seen', () => {
+        const logger = createLogger();
+        warnOnce(logger, 'first-seen-msg');
+        expect(logger.warn).toHaveBeenCalledTimes(1);
+        expect(logger.warn).toHaveBeenCalledWith('first-seen-msg');
+    });
+    it('does not emit repeated warnings for the same message', () => {
+        const logger = createLogger();
+        warnOnce(logger, 'repeated-msg');
+        warnOnce(logger, 'repeated-msg');
+        warnOnce(logger, 'repeated-msg');
+        expect(logger.warn).toHaveBeenCalledTimes(1);
+    });
+    it('emits distinct messages independently', () => {
+        const logger = createLogger();
+        warnOnce(logger, 'distinct-alpha-msg');
+        warnOnce(logger, 'distinct-beta-msg');
+        warnOnce(logger, 'distinct-alpha-msg');
+        expect(logger.warn).toHaveBeenCalledTimes(2);
+        expect(logger.warn).toHaveBeenNthCalledWith(1, 'distinct-alpha-msg');
+        expect(logger.warn).toHaveBeenNthCalledWith(2, 'distinct-beta-msg');
+    });
+});
+//# sourceMappingURL=warn-once.test.js.map

package/dist/src/logging/__tests__/warn-once.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"warn-once.test.js","sourceRoot":"","sources":["../../../../src/logging/__tests__/warn-once.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAA;AAEjD,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAE1C,SAAS,YAAY;IACnB,OAAO,EAAE,KAAK,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAA;AACzE,CAAC;AAED,QAAQ,CAAC,UAAU,EAAE,GAAG,EAAE;IACxB,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC1D,MAAM,MAAM,GAAG,YAAY,EAAE,CAAA;QAC7B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;QAClC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAA;QAC5C,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,oBAAoB,CAAC,gBAAgB,CAAC,CAAA;IAC5D,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,sDAAsD,EAAE,GAAG,EAAE;QAC9D,MAAM,MAAM,GAAG,YAAY,EAAE,CAAA;QAC7B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;QAChC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;QAChC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;QAChC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAA;IAC9C,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,uCAAuC,EAAE,GAAG,EAAE;QAC/C,MAAM,MAAM,GAAG,YAAY,EAAE,CAAA;QAC7B,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAA;QACtC,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAA;QACrC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAA;QACtC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAA;QAC5C,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,uBAAuB,CAAC,CAAC,EAAE,oBAAoB,CAAC,CAAA;QACpE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,uBAAuB,CAAC,CAAC,EAAE,mBAAmB,CAAC,CAAA;IACrE,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/dist/src/logging/warn-once.d.ts

@@ -0,0 +1,13 @@
+import type { Logger } from './types.js';
+/**
+ * Emits a warning log at most once per unique message per process.
+ *
+ * Subsequent calls with the same message are no-ops, which prevents
+ * repeated nudges (e.g. "using default modelId") from flooding logs
+ * when many instances are constructed.
+ *
+ * @param logger - Logger to emit the warning on
+ * @param msg - Warning message; also used as the dedupe key
+ */
+export declare function warnOnce(logger: Logger, msg: string): void;
+//# sourceMappingURL=warn-once.d.ts.map

package/dist/src/logging/warn-once.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"warn-once.d.ts","sourceRoot":"","sources":["../../../src/logging/warn-once.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAIxC;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAI1D"}

package/dist/src/logging/warn-once.js

@@ -0,0 +1,18 @@
+const warned = new Set();
+/**
+ * Emits a warning log at most once per unique message per process.
+ *
+ * Subsequent calls with the same message are no-ops, which prevents
+ * repeated nudges (e.g. "using default modelId") from flooding logs
+ * when many instances are constructed.
+ *
+ * @param logger - Logger to emit the warning on
+ * @param msg - Warning message; also used as the dedupe key
+ */
+export function warnOnce(logger, msg) {
+    if (warned.has(msg))
+        return;
+    logger.warn(msg);
+    warned.add(msg);
+}
+//# sourceMappingURL=warn-once.js.map

package/dist/src/logging/warn-once.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"warn-once.js","sourceRoot":"","sources":["../../../src/logging/warn-once.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAA;AAEhC;;;;;;;;;GASG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAc,EAAE,GAAW;IAClD,IAAI,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC;QAAE,OAAM;IAC3B,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IAChB,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;AACjB,CAAC"}

package/dist/src/mcp.d.ts

@@ -1,7 +1,20 @@
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { type ServerCapabilities, type Implementation, type LoggingMessageNotificationParams } from '@modelcontextprotocol/sdk/types.js';
 import type { JSONValue } from './types/json.js';
+import type { ElicitationCallback } from './types/elicitation.js';
 import { McpTool } from './tools/mcp-tool.js';
+/**
+ * Widened transport type that accepts MCP transport implementations without requiring explicit casts.
+ *
+ * Under `exactOptionalPropertyTypes`, `StreamableHTTPClientTransport` is not directly assignable
+ * to `Transport` because its `sessionId` getter returns `string | undefined`, while `Transport`
+ * declares `sessionId?: string` (absent or string, but not explicitly undefined).
+ * This type relaxes that constraint so users can pass any MCP transport without `as Transport`.
+ */
+export type McpTransport = Omit<Transport, 'sessionId'> & {
+    sessionId?: string | undefined;
+};
 /** Temporary placeholder for RuntimeConfig */
 export interface RuntimeConfig {
     applicationName?: string;
@@ -29,9 +42,11 @@ export interface TasksConfig {
      */
     pollTimeout?: number;
 }
+/** Connection state of an MCP client. */
+export type McpConnectionState = 'disconnected' | 'connected' | 'failed';
 /** Arguments for configuring an MCP Client. */
 export type McpClientConfig = RuntimeConfig & {
-    transport: Transport;
+    transport: McpTransport;
     /** Disable OpenTelemetry MCP instrumentation. */
     disableMcpInstrumentation?: boolean;
     /**
@@ -40,6 +55,16 @@ export type McpClientConfig = RuntimeConfig & {
      * When undefined, tools are called directly without task management.
      */
     tasksConfig?: TasksConfig;
+    /**
+     * Callback to handle server-initiated elicitation requests.
+     * When provided, the client advertises elicitation support (form + url modes)
+     * and routes incoming elicitation requests to this callback.
+     */
+    elicitationCallback?: ElicitationCallback;
+    /** When true, connection failures are logged as warnings instead of throwing. */
+    failOpen?: boolean;
+    /** Called when the server emits a log message. Defaults to routing through the Strands logger. */
+    logHandler?: (params: LoggingMessageNotificationParams) => void;
 };
 /** MCP Client for interacting with Model Context Protocol servers. */
 export declare class McpClient {
@@ -50,17 +75,27 @@ export declare class McpClient {
     private _clientName;
     private _clientVersion;
     private _transport;
-    private _connected;
+    private _state;
     private _client;
+    private _failOpen;
+    private _logHandler;
     private _disableMcpInstrumentation;
     private _tasksConfig;
+    private _elicitationCallback;
     constructor(args: McpClientConfig);
     get client(): Client;
+    get serverCapabilities(): ServerCapabilities | undefined;
+    get serverVersion(): Implementation | undefined;
+    get serverInstructions(): string | undefined;
+    get connectionState(): McpConnectionState;
     /**
      * Connects the MCP client to the server.
      *
-     * This function is exposed to allow consumers to connect manually, but will be called lazily before any operations that require a connection.
+     * Called lazily before any operation that requires a connection. When `failOpen` is true,
+     * connection failures are swallowed and the client enters a `'failed'` state — subsequent
+     * calls are no-ops until `connect(true)` is called explicitly to retry.
      *
+     * @param reconnect - When true, forces a reconnect even if already connected or failed.
      * @returns A promise that resolves when the connection is established.
      */
     connect(reconnect?: boolean): Promise<void>;
@@ -70,6 +105,11 @@ export declare class McpClient {
      * @returns A promise that resolves when the disconnection is complete.
      */
     disconnect(): Promise<void>;
+    /**
+     * Enables the `await using` pattern for automatic resource cleanup.
+     * Delegates to {@link McpClient.disconnect}.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
     /**
      * Lists the tools available on the server and returns them as executable McpTool instances.
      *

package/dist/src/mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/mcp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAA;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAA;AAG9E,OAAO,KAAK,EAAc,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAG7C,8CAA8C;AAC9C,MAAM,WAAW,aAAa;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IAEZ;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,+CAA+C;AAC/C,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG;IAC5C,SAAS,EAAE,SAAS,CAAA;IAEpB,iDAAiD;IACjD,yBAAyB,CAAC,EAAE,OAAO,CAAA;IAEnC;;;;OAIG;IACH,WAAW,CAAC,EAAE,WAAW,CAAA;CAC1B,CAAA;AAED,sEAAsE;AACtE,qBAAa,SAAS;IACpB,iEAAiE;IACjE,gBAAuB,WAAW,SAAQ;IAE1C,4EAA4E;IAC5E,gBAAuB,oBAAoB,UAAS;IAEpD,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,cAAc,CAAQ;IAC9B,OAAO,CAAC,UAAU,CAAW;IAC7B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,0BAA0B,CAAS;IAC3C,OAAO,CAAC,YAAY,CAAyB;gBAEjC,IAAI,EAAE,eAAe;IAcjC,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;;;;;OAMG;IACU,OAAO,CAAC,SAAS,GAAE,OAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAe/D;;;;OAIG;IACU,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAOxC;;;;OAIG;IACU,SAAS,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAgB5C;;;;;;;;;;OAUG;IACU,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;CAqC1E"}
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/mcp.ts"],"names":[],"mappings":"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"}

package/dist/src/mcp.js

@@ -1,5 +1,6 @@
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { takeResult } from '@modelcontextprotocol/sdk/shared/responseMessage.js';
+import { ElicitRequestSchema, LoggingMessageNotificationSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { context, propagation, trace } from '@opentelemetry/api';
 import { McpTool } from './tools/mcp-tool.js';
 import { logger } from './logging/index.js';
@@ -12,42 +13,79 @@ export class McpClient {
     _clientName;
     _clientVersion;
     _transport;
-    _connected;
+    _state;
     _client;
+    _failOpen;
+    _logHandler;
     _disableMcpInstrumentation;
     _tasksConfig;
+    _elicitationCallback;
     constructor(args) {
         this._clientName = args.applicationName || 'strands-agents-ts-sdk';
         this._clientVersion = args.applicationVersion || '0.0.1';
         this._transport = args.transport;
-        this._connected = false;
+        this._state = 'disconnected';
+        this._failOpen = args.failOpen ?? false;
+        this._logHandler = args.logHandler ?? defaultLogHandler;
         this._tasksConfig = args.tasksConfig;
+        this._elicitationCallback = args.elicitationCallback;
         this._client = new Client({
             name: this._clientName,
             version: this._clientVersion,
+        }, this._elicitationCallback ? { capabilities: { elicitation: { form: {}, url: {} } } } : undefined);
+        this._client.setNotificationHandler(LoggingMessageNotificationSchema, (notification) => {
+            this._logHandler(notification.params);
         });
         this._disableMcpInstrumentation = args.disableMcpInstrumentation ?? false;
     }
     get client() {
         return this._client;
     }
+    get serverCapabilities() {
+        return this._client.getServerCapabilities();
+    }
+    get serverVersion() {
+        return this._client.getServerVersion();
+    }
+    get serverInstructions() {
+        return this._client.getInstructions();
+    }
+    get connectionState() {
+        return this._state;
+    }
     /**
      * Connects the MCP client to the server.
      *
-     * This function is exposed to allow consumers to connect manually, but will be called lazily before any operations that require a connection.
+     * Called lazily before any operation that requires a connection. When `failOpen` is true,
+     * connection failures are swallowed and the client enters a `'failed'` state — subsequent
+     * calls are no-ops until `connect(true)` is called explicitly to retry.
      *
+     * @param reconnect - When true, forces a reconnect even if already connected or failed.
      * @returns A promise that resolves when the connection is established.
      */
     async connect(reconnect = false) {
-        if (this._connected && !reconnect) {
+        if (this._state !== 'disconnected' && !reconnect)
             return;
-        }
-        if (this._connected && reconnect) {
+        if (this._state === 'connected' && reconnect) {
             await this._client.close();
-            this._connected = false;
+            this._state = 'disconnected';
+        }
+        if (this._elicitationCallback) {
+            const callback = this._elicitationCallback;
+            this._client.setRequestHandler(ElicitRequestSchema, async (request, extra) => {
+                return await callback(extra, request.params);
+            });
+        }
+        try {
+            await this._client.connect(this._transport);
+            this._state = 'connected';
+        }
+        catch (error) {
+            if (!this._failOpen)
+                throw error;
+            this._state = 'failed';
+            logger.warn(`client=<${this._clientName}>, error=<${error}> | MCP server failed to connect, continuing with failOpen`);
         }
-        await this._client.connect(this._transport);
-        this._connected = true;
     }
     /**
      * Disconnects the MCP client from the server and cleans up resources.
@@ -58,7 +96,14 @@ export class McpClient {
         // Must be done sequentially
         await this._client.close();
         await this._transport.close();
-        this._connected = false;
+        this._state = 'disconnected';
+    }
+    /**
+     * Enables the `await using` pattern for automatic resource cleanup.
+     * Delegates to {@link McpClient.disconnect}.
+     */
+    async [Symbol.asyncDispose]() {
+        await this.disconnect();
     }
     /**
      * Lists the tools available on the server and returns them as executable McpTool instances.
@@ -67,16 +112,21 @@ export class McpClient {
      */
     async listTools() {
         await this.connect();
-        const result = await this._client.listTools();
-        // Map the tool specifications to fully functional McpTool instances
-        return result.tools.map((toolSpec) => {
-            return new McpTool({
+        if (this._state === 'failed')
+            return [];
+        const tools = [];
+        let cursor;
+        do {
+            const result = await this._client.listTools(cursor ? { cursor } : undefined);
+            tools.push(...result.tools.map((toolSpec) => new McpTool({
                 name: toolSpec.name,
-                description: toolSpec.description ?? '',
+                description: toolSpec.description || `Tool which performs ${toolSpec.name}`,
                 inputSchema: toolSpec.inputSchema,
                 client: this,
-            });
-        });
+            })));
+            cursor = result.nextCursor;
+        } while (cursor);
+        return tools;
     }
     /**
      * Invoke a tool on the connected MCP server using an McpTool instance.
@@ -91,6 +141,8 @@ export class McpClient {
      */
     async callTool(tool, args) {
         await this.connect();
+        if (this._state === 'failed')
+            throw new Error('MCP server failed to connect. Call connect(true) to retry.');
         if (args === null || args === undefined) {
             return await this.callTool(tool, {});
         }
@@ -116,6 +168,22 @@ export class McpClient {
         return result;
     }
 }
+function defaultLogHandler(params) {
+    const { level, logger: serverLogger, data } = params;
+    const message = `logger=<${serverLogger ?? 'mcp'}>, data=<${JSON.stringify(data)}> | MCP server log`;
+    if (level === 'debug') {
+        logger.debug(message);
+    }
+    else if (level === 'info' || level === 'notice') {
+        logger.info(message);
+    }
+    else if (level === 'warning') {
+        logger.warn(message);
+    }
+    else {
+        logger.error(message);
+    }
+}
 /**
  * Injects OpenTelemetry trace context into MCP tool call arguments.
  * Returns the args with a `_meta` field containing W3C traceparent headers.