@ampcode/plugin 0.0.0-20260922001754-ga9ffbd3 → 0.0.0-20260924001720-g7fda6e0

package/index.d.ts

@@ -1270,10 +1270,28 @@ declare module '@ampcode/plugin' {
 		steer?: boolean
 	}
 
+	/**
+	 * Options shared by the dialogs that wait for an answer (`ui.input`, `ui.confirm`, and
+	 * `ui.select`).
+	 */
+	export interface PluginDialogOptions {
+		/**
+		 * Require a human response rather than an agent response. The thread owner can answer these
+		 * dialogs. While multiplayer is active, human contributors can also answer interactive
+		 * selections, confirmations, and non-secret inputs, including dialogs with `requireHuman: true`.
+		 * Secret inputs (`secret: true`) remain owner-only and always require a human. Dialogs targeted
+		 * to a specific connection are not shared with contributors.
+		 *
+		 * Use this for approval and permission prompts. It does not grant agents access to dialogs
+		 * or enable them to answer on the owner's behalf.
+		 */
+		requireHuman?: boolean
+	}
+
 	/**
 	 * Options for the input dialog.
 	 */
-	export interface PluginInputOptions {
+	export interface PluginInputOptions extends PluginDialogOptions {
 		/** Dialog title */
 		title?: string
 
@@ -1306,7 +1324,7 @@ declare module '@ampcode/plugin' {
 	/**
 	 * Options for the confirm dialog.
 	 */
-	export interface PluginConfirmOptions {
+	export interface PluginConfirmOptions extends PluginDialogOptions {
 		/** Dialog title */
 		title: string
 
@@ -1317,21 +1335,27 @@ declare module '@ampcode/plugin' {
 		confirmButtonText?: string
 	}
 
-	/** An editable text field in a confirmation dialog. */
+	/** A field shown in a confirmation dialog. */
 	export interface PluginConfirmField {
+		/**
+		 * How to show the field. Text fields are editable. Image fields show a read-only preview
+		 * of an HTTP(S) image URL and are omitted from the returned values. Defaults to `text`.
+		 */
+		type?: 'text' | 'image'
+
 		/** Stable key used in the returned record */
 		name: string
 
 		/** Label shown above the field */
 		label: string
 
-		/** Initial field value */
+		/** Initial text value or, for an image field, an HTTP(S) image URL */
 		value: string
 
-		/** Allow the field to span multiple lines */
+		/** Allow a text field to span multiple lines */
 		multiline?: boolean
 
-		/** Allow the field to be left empty. Fields are required unless this is set. */
+		/** Allow a text field to be left empty. Text fields are required unless this is set. */
 		optional?: boolean
 	}
 
@@ -1343,7 +1367,7 @@ declare module '@ampcode/plugin' {
 	/**
 	 * Options for the select dialog.
 	 */
-	export interface PluginSelectOptions {
+	export interface PluginSelectOptions extends PluginDialogOptions {
 		/** Dialog title */
 		title: string
 
@@ -1376,8 +1400,9 @@ declare module '@ampcode/plugin' {
 		input(options: PluginInputOptions): Promise<string | undefined>
 
 		/**
-		 * Show required editable fields in a confirmation dialog.
-		 * @returns The edited values by field name, or undefined if cancelled.
+		 * Show editable text fields and read-only image previews in a confirmation dialog.
+		 * @returns The edited text values by field name, or undefined if cancelled. Image fields
+		 * are omitted.
 		 */
 		confirm(options: PluginEditableConfirmOptions): Promise<Record<string, string> | undefined>
 		/**
@@ -1961,7 +1986,13 @@ declare module '@ampcode/plugin' {
 			[key: string]: unknown
 		}
 
-		/** Execute the tool with the given input and return a result */
+		/**
+		 * Execute the tool with the given input and return a result.
+		 *
+		 * Returning nothing is allowed and is shown to the model as `(no tool output)`. Throw an
+		 * error to report a failure; the model then sees a tool error instead of a successful
+		 * empty result.
+		 */
 		execute: (
 			input: Record<string, unknown>,
 			ctx: PluginToolContext,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ampcode/plugin",
-	"version": "0.0.0-20260922001754-ga9ffbd3",
+	"version": "0.0.0-20260924001720-g7fda6e0",
 	"description": "Amp Plugin API",
 	"homepage": "https://ampcode.com/docs/plugin-api",
 	"author": {