@strands-agents/sdk 1.10.0 → 1.11.1

package/dist/src/vended-tools/sleep/make-sleep.js

@@ -0,0 +1,81 @@
+/**
+ * Sleep tool factory: pauses execution for a bounded, cooperative duration.
+ *
+ * The returned tool honors the invocation's `AbortSignal` (from
+ * `context.agent.cancelSignal`), so cancelling the agent aborts the sleep
+ * immediately rather than waiting for the full duration.
+ */
+import { tool } from '../../tools/tool-factory.js';
+import { z } from 'zod';
+import { DEFAULT_MAX_DURATION, sleepDescription } from './types.js';
+/**
+ * Creates a sleep tool with a configurable maximum duration.
+ *
+ * The returned tool pauses for the requested number of seconds. It attaches a
+ * one-shot listener to `context.agent.cancelSignal` so that cancellation of
+ * the enclosing agent invocation immediately aborts the sleep with an
+ * `AbortError`.
+ *
+ * @param options - Configuration options.
+ * @returns A tool that pauses execution for the requested duration.
+ * @throws Error if `maxDuration` is not a finite, positive number.
+ *
+ * @example
+ * ```typescript
+ * const shortSleep = makeSleep({ maxDuration: 5 })
+ * const agent = new Agent({ tools: [shortSleep] })
+ * ```
+ */
+export function makeSleep(options = {}) {
+    const maxDuration = options.maxDuration ?? DEFAULT_MAX_DURATION;
+    if (typeof maxDuration !== 'number' || !Number.isFinite(maxDuration) || maxDuration <= 0) {
+        throw new Error(`maxDuration must be a positive, finite number, got ${String(maxDuration)}`);
+    }
+    const inputSchema = z.object({
+        duration: z
+            .number()
+            .finite('duration must be a finite number')
+            .nonnegative('duration must be non-negative')
+            .max(maxDuration, `duration exceeds maximum of ${maxDuration} seconds`)
+            .describe(`Seconds to pause. Must be finite, non-negative, and no larger than ${maxDuration}.`),
+    });
+    return tool({
+        name: options.name ?? 'sleep',
+        description: options.description ?? sleepDescription(maxDuration),
+        inputSchema,
+        callback: async (input, context) => {
+            const { duration } = input;
+            const cancelSignal = context?.agent.cancelSignal;
+            if (cancelSignal?.aborted) {
+                throw cancelSignal.reason ?? new DOMException('Sleep cancelled before it started', 'AbortError');
+            }
+            await new Promise((resolve, reject) => {
+                function cleanup() {
+                    if (cancelSignal) {
+                        cancelSignal.removeEventListener('abort', onAbort);
+                    }
+                }
+                function onAbort() {
+                    globalThis.clearTimeout(timer);
+                    cleanup();
+                    reject(cancelSignal?.reason ?? new DOMException('Sleep cancelled', 'AbortError'));
+                }
+                const timer = globalThis.setTimeout(() => {
+                    cleanup();
+                    resolve();
+                }, duration * 1000);
+                if (cancelSignal) {
+                    cancelSignal.addEventListener('abort', onAbort, { once: true });
+                    // Re-check after attaching: the signal may have aborted between the
+                    // pre-flight check and here, and abort listeners do not fire for
+                    // events dispatched before they were added.
+                    if (cancelSignal.aborted) {
+                        onAbort();
+                    }
+                }
+            });
+            return `Slept for ${duration} seconds`;
+        },
+    });
+}
+//# sourceMappingURL=make-sleep.js.map

package/dist/src/vended-tools/sleep/make-sleep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"make-sleep.js","sourceRoot":"","sources":["../../../../src/vended-tools/sleep/make-sleep.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,IAAI,EAAE,MAAM,6BAA6B,CAAA;AAClD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAqBnE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,SAAS,CAAC,UAA4B,EAAE;IACtD,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,oBAAoB,CAAA;IAC/D,IAAI,OAAO,WAAW,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,WAAW,IAAI,CAAC,EAAE,CAAC;QACzF,MAAM,IAAI,KAAK,CAAC,sDAAsD,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAA;IAC9F,CAAC;IAED,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;QAC3B,QAAQ,EAAE,CAAC;aACR,MAAM,EAAE;aACR,MAAM,CAAC,kCAAkC,CAAC;aAC1C,WAAW,CAAC,+BAA+B,CAAC;aAC5C,GAAG,CAAC,WAAW,EAAE,+BAA+B,WAAW,UAAU,CAAC;aACtE,QAAQ,CAAC,sEAAsE,WAAW,GAAG,CAAC;KAClG,CAAC,CAAA;IAEF,OAAO,IAAI,CAAC;QACV,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,OAAO;QAC7B,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,gBAAgB,CAAC,WAAW,CAAC;QACjE,WAAW;QACX,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;YACjC,MAAM,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAA;YAE1B,MAAM,YAAY,GAAG,OAAO,EAAE,KAAK,CAAC,YAAY,CAAA;YAChD,IAAI,YAAY,EAAE,OAAO,EAAE,CAAC;gBAC1B,MAAM,YAAY,CAAC,MAAM,IAAI,IAAI,YAAY,CAAC,mCAAmC,EAAE,YAAY,CAAC,CAAA;YAClG,CAAC;YAED,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBAC1C,SAAS,OAAO;oBACd,IAAI,YAAY,EAAE,CAAC;wBACjB,YAAY,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;oBACpD,CAAC;gBACH,CAAC;gBACD,SAAS,OAAO;oBACd,UAAU,CAAC,YAAY,CAAC,KAAK,CAAC,CAAA;oBAC9B,OAAO,EAAE,CAAA;oBACT,MAAM,CAAC,YAAY,EAAE,MAAM,IAAI,IAAI,YAAY,CAAC,iBAAiB,EAAE,YAAY,CAAC,CAAC,CAAA;gBACnF,CAAC;gBAED,MAAM,KAAK,GAAG,UAAU,CAAC,UAAU,CAAC,GAAG,EAAE;oBACvC,OAAO,EAAE,CAAA;oBACT,OAAO,EAAE,CAAA;gBACX,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC,CAAA;gBAEnB,IAAI,YAAY,EAAE,CAAC;oBACjB,YAAY,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;oBAC/D,oEAAoE;oBACpE,iEAAiE;oBACjE,4CAA4C;oBAC5C,IAAI,YAAY,CAAC,OAAO,EAAE,CAAC;wBACzB,OAAO,EAAE,CAAA;oBACX,CAAC;gBACH,CAAC;YACH,CAAC,CAAC,CAAA;YAEF,OAAO,aAAa,QAAQ,UAAU,CAAA;QACxC,CAAC;KACF,CAAC,CAAA;AACJ,CAAC"}

package/dist/src/vended-tools/sleep/sleep.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Default sleep tool with the built-in maximum duration.
+ */
+/**
+ * Default sleep tool. Pauses execution for up to 60 seconds and aborts
+ * immediately when the agent invocation is cancelled.
+ *
+ * @example
+ * ```typescript
+ * // With an agent
+ * const agent = new Agent({ tools: [sleep] })
+ * await agent.invoke('Wait 2 seconds, then continue')
+ *
+ * // Direct usage
+ * await sleep.invoke({ duration: 0.5 })
+ * ```
+ */
+export declare const sleep: import("../../index.js").InvokableTool<import("./types.js").SleepInput, import("../../index.js").JSONValue>;
+//# sourceMappingURL=sleep.d.ts.map

package/dist/src/vended-tools/sleep/sleep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep.d.ts","sourceRoot":"","sources":["../../../../src/vended-tools/sleep/sleep.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,KAAK,6GAAc,CAAA"}

package/dist/src/vended-tools/sleep/sleep.js

@@ -0,0 +1,20 @@
+/**
+ * Default sleep tool with the built-in maximum duration.
+ */
+import { makeSleep } from './make-sleep.js';
+/**
+ * Default sleep tool. Pauses execution for up to 60 seconds and aborts
+ * immediately when the agent invocation is cancelled.
+ *
+ * @example
+ * ```typescript
+ * // With an agent
+ * const agent = new Agent({ tools: [sleep] })
+ * await agent.invoke('Wait 2 seconds, then continue')
+ *
+ * // Direct usage
+ * await sleep.invoke({ duration: 0.5 })
+ * ```
+ */
+export const sleep = makeSleep();
+//# sourceMappingURL=sleep.js.map

package/dist/src/vended-tools/sleep/sleep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep.js","sourceRoot":"","sources":["../../../../src/vended-tools/sleep/sleep.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAE3C;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,SAAS,EAAE,CAAA"}

package/dist/src/vended-tools/sleep/types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Type definitions and constants for the sleep tool.
+ */
+/**
+ * Default upper bound on `duration` (seconds) accepted by `makeSleep`.
+ */
+export declare const DEFAULT_MAX_DURATION = 60;
+/**
+ * Build the model-facing description with the configured maximum interpolated
+ * so the model knows the exact ceiling.
+ */
+export declare function sleepDescription(maxDuration: number): string;
+/**
+ * Description for the default sleep tool (60-second cap).
+ */
+export declare const SLEEP_DESCRIPTION: string;
+/**
+ * Input parameters accepted by the sleep tool.
+ *
+ * The Zod schema in `make-sleep.ts` is the single source of truth for the
+ * validated input shape (it also enforces the configured maximum); this type
+ * describes the pre-refinement shape callers can pass directly.
+ */
+export interface SleepInput {
+    /**
+     * Seconds to pause. Must be a finite, non-negative number and no larger than
+     * the tool's configured maximum.
+     */
+    duration: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/vended-tools/sleep/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/vended-tools/sleep/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,eAAO,MAAM,oBAAoB,KAAK,CAAA;AAEtC;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAO5D;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB,QAAyC,CAAA;AAEvE;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAA;CACjB"}

package/dist/src/vended-tools/sleep/types.js

@@ -0,0 +1,22 @@
+/**
+ * Type definitions and constants for the sleep tool.
+ */
+/**
+ * Default upper bound on `duration` (seconds) accepted by `makeSleep`.
+ */
+export const DEFAULT_MAX_DURATION = 60;
+/**
+ * Build the model-facing description with the configured maximum interpolated
+ * so the model knows the exact ceiling.
+ */
+export function sleepDescription(maxDuration) {
+    return (`Pauses execution for a specified number of seconds (max ${maxDuration}). ` +
+        'Cooperative and cancellable: the sleep aborts immediately when the agent ' +
+        'invocation is cancelled. Rejects negative, NaN, infinite, or non-numeric ' +
+        `durations, and durations above ${maxDuration}.`);
+}
+/**
+ * Description for the default sleep tool (60-second cap).
+ */
+export const SLEEP_DESCRIPTION = sleepDescription(DEFAULT_MAX_DURATION);
+//# sourceMappingURL=types.js.map

package/dist/src/vended-tools/sleep/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/vended-tools/sleep/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAA;AAEtC;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,WAAmB;IAClD,OAAO,CACL,2DAA2D,WAAW,KAAK;QAC3E,2EAA2E;QAC3E,2EAA2E;QAC3E,kCAAkC,WAAW,GAAG,CACjD,CAAA;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,gBAAgB,CAAC,oBAAoB,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strands-agents/sdk",
-  "version": "1.10.0",
+  "version": "1.11.1",
   "description": "TypeScript SDK for Strands Agents framework",
   "main": "dist/src/index.js",
   "module": "dist/src/index.js",
@@ -68,6 +68,14 @@
       "types": "./dist/src/vended-tools/bash/index.d.ts",
       "default": "./dist/src/vended-tools/bash/index.js"
     },
+    "./vended-tools/sleep": {
+      "types": "./dist/src/vended-tools/sleep/index.d.ts",
+      "default": "./dist/src/vended-tools/sleep/index.js"
+    },
+    "./experimental/vended-tools/stop": {
+      "types": "./dist/src/experimental/vended-tools/stop/index.d.ts",
+      "default": "./dist/src/experimental/vended-tools/stop/index.js"
+    },
     "./a2a": {
       "types": "./dist/src/a2a/index.d.ts",
       "default": "./dist/src/a2a/index.js"