@ampcode/plugin 0.0.0-20260921001857-g6fa23da → 0.0.0-20260923001649-g009f5d9

package/index.d.ts

@@ -129,6 +129,24 @@ declare module '@ampcode/plugin' {
 		 */
 		registerSkill(definition: PluginSkillDefinition): Promise<Subscription>
 
+		/**
+		 * Register a text pattern that Amp turns into a link wherever it appears in a thread
+		 * transcript: user messages and the prose of assistant replies.
+		 *
+		 * Amp records the patterns on each thread this plugin's executor connects to, so readers
+		 * who open the thread later without an executor still see the links.
+		 *
+		 * @example
+		 * ```ts
+		 * amp.registerLinkPattern({
+		 *   id: 'issue',
+		 *   pattern: 'ENG-\\d{1,6}',
+		 *   href: 'https://linear.app/acme/issue/{{match}}',
+		 * })
+		 * ```
+		 */
+		registerLinkPattern(definition: PluginLinkPatternDefinition): Subscription
+
 		/**
 		 * Register a callback that runs before this plugin instance is stopped.
 		 *
@@ -1252,10 +1270,25 @@ 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 {
+		/**
+		 * Mark this dialog as one only the thread owner may answer in person. Without it, an agent
+		 * acting for the owner, such as a Puck thread that created and supervises this thread, may
+		 * be allowed to answer on the owner's behalf. Set this when the dialog is a deterministic
+		 * gate, such as a permission or approval prompt, so that only a human can pass it. Agents
+		 * can still see what the dialog asks. Secret inputs (`secret: true`) always require a human.
+		 */
+		requireHuman?: boolean
+	}
+
 	/**
 	 * Options for the input dialog.
 	 */
-	export interface PluginInputOptions {
+	export interface PluginInputOptions extends PluginDialogOptions {
 		/** Dialog title */
 		title?: string
 
@@ -1288,7 +1321,7 @@ declare module '@ampcode/plugin' {
 	/**
 	 * Options for the confirm dialog.
 	 */
-	export interface PluginConfirmOptions {
+	export interface PluginConfirmOptions extends PluginDialogOptions {
 		/** Dialog title */
 		title: string
 
@@ -1299,19 +1332,28 @@ declare module '@ampcode/plugin' {
 		confirmButtonText?: string
 	}
 
-	/** An editable, required 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 a text field to be left empty. Text fields are required unless this is set. */
+		optional?: boolean
 	}
 
 	/** Options for a confirmation dialog that returns edited field values. */
@@ -1322,7 +1364,7 @@ declare module '@ampcode/plugin' {
 	/**
 	 * Options for the select dialog.
 	 */
-	export interface PluginSelectOptions {
+	export interface PluginSelectOptions extends PluginDialogOptions {
 		/** Dialog title */
 		title: string
 
@@ -1355,8 +1397,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>
 		/**
@@ -1541,6 +1584,14 @@ declare module '@ampcode/plugin' {
 
 		/** The message ID */
 		id: ThreadMessageID
+
+		/**
+		 * Set when a client's canned changes workflow started this turn: `ship` for the Ship
+		 * button and `push_branch` for Push to Branch. Absent for prompts the user typed.
+		 * Use it to append workflow-specific instructions (for example, issue-tracker follow-up
+		 * after shipping) instead of matching on the prompt text.
+		 */
+		changesWorkflow?: 'ship' | 'push_branch'
 	}
 
 	/**
@@ -1594,6 +1645,52 @@ declare module '@ampcode/plugin' {
 		maxContinuations?: number
 	} | void
 
+	/**
+	 * Event payload for changes.prompt event.
+	 * Fired when a client prepares the prompt behind its Ship or Push to Branch button, before
+	 * the user sees it. The Ship dialog shows the assembled prompt, so the user can edit anything a
+	 * plugin adds before sending.
+	 */
+	export interface ChangesPromptEvent {
+		/** The thread whose changes are about to be shipped or pushed */
+		thread: { id: ThreadID }
+
+		/** `ship` for the Ship button, `push_branch` for Push to Branch */
+		workflow: 'ship' | 'push_branch'
+	}
+
+	/**
+	 * Result returned from a changes.prompt handler.
+	 * Return `append` to add instructions after the prompt, such as issue-tracker follow-up steps
+	 * for the shipped commits. Every plugin's `append` is added, in plugin load order.
+	 */
+	export type ChangesPromptResult = { append?: string } | void
+
+	/**
+	 * A text pattern that Amp turns into a link in thread transcripts.
+	 * See {@link PluginAPI.registerLinkPattern}.
+	 */
+	export interface PluginLinkPatternDefinition {
+		/** Stable identifier within this plugin, such as `issue`. Letters, digits, and hyphens; up to 64 characters. */
+		id: string
+
+		/**
+		 * Regular expression source that matches one token, such as `ENG-\d{1,6}`, written
+		 * without anchors, flags, or delimiters. Amp compiles it with the `u` flag, requires a
+		 * token boundary on both sides, and limits it to 200 characters. Backreferences and
+		 * lookbehind are rejected, as is a pattern that matches the empty string. Named capture
+		 * groups can be used in `href`.
+		 */
+		pattern: string
+
+		/**
+		 * URL template for the link. `{{match}}` is replaced with the whole match and
+		 * `{{name}}` with the named capture group `name`, both URL-encoded. The result must be an
+		 * `http:` or `https:` URL, or an absolute path on Amp such as `/admin/bug-reports/{{match}}`.
+		 */
+		href: string
+	}
+
 	/**
 	 * Map of event names to their payload types.
 	 */
@@ -1603,6 +1700,7 @@ declare module '@ampcode/plugin' {
 		'tool.result': ToolResultEvent
 		'agent.start': AgentStartEvent
 		'agent.end': AgentEndEvent
+		'changes.prompt': ChangesPromptEvent
 	}
 
 	/**
@@ -1614,6 +1712,7 @@ declare module '@ampcode/plugin' {
 		'tool.result': ToolResultResult
 		'agent.start': AgentStartResult
 		'agent.end': AgentEndResult
+		'changes.prompt': ChangesPromptResult
 	}
 
 	/**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ampcode/plugin",
-	"version": "0.0.0-20260921001857-g6fa23da",
+	"version": "0.0.0-20260923001649-g009f5d9",
 	"description": "Amp Plugin API",
 	"homepage": "https://ampcode.com/docs/plugin-api",
 	"author": {