@ampcode/plugin 0.0.0-20260512003045-g373e11b → 0.0.0-20260513003404-g32e421b

package/index.d.ts

@@ -79,7 +79,7 @@ declare module '@ampcode/plugin' {
 			id: string,
 			options: PluginCommandOptions,
 			handler: (ctx: PluginCommandContext) => void | Promise<void>,
-		): Subscription
+		): CommandSubscription
 
 		/**
 		 * Register a tool that the agent can call.
@@ -155,7 +155,12 @@ declare module '@ampcode/plugin' {
 		/** Text to show. */
 		text: string
 
-		/** URL to open when clicked, if any. */
+		/**
+		 * URL to open when clicked, if any.
+		 *
+		 * Use a `command:` URI to execute a command registered by a plugin or the
+		 * command palette. For example, `command:foo` runs the command with ID `foo`.
+		 */
 		url?: string
 	}
 
@@ -219,6 +224,16 @@ declare module '@ampcode/plugin' {
 		 */
 		subscribe(observer: PluginConfigurationObserver<T>): Subscription
 		subscribe(onNext: (value: T) => void): Subscription
+
+		/**
+		 * Pipe operators for transforming this observable.
+		 */
+		pipe<Out>(op: (input: Observable<T>) => Out): Out
+
+		/**
+		 * Return this observable for interop with observable libraries.
+		 */
+		[Symbol.observable](): Observable<T>
 	}
 
 	/**
@@ -226,11 +241,6 @@ declare module '@ampcode/plugin' {
 	 * Provides a limited subset of Observable functionality for plugins.
 	 */
 	export interface PluginConfiguration<T> extends Observable<T> {
-		/**
-		 * Pipe operators for transforming the configuration observable.
-		 */
-		pipe<Out>(op: (input: PluginConfiguration<T>) => Out): Out
-
 		/**
 		 * Get the current configuration value.
 		 */
@@ -460,6 +470,9 @@ declare module '@ampcode/plugin' {
 		/** Message body shown below the title */
 		message?: string
 
+		/** Initially selected option value */
+		initialValue?: string
+
 		/** Entries to display as choices */
 		options: string[]
 	}
@@ -790,6 +803,18 @@ declare module '@ampcode/plugin' {
 	 */
 	export type IsPluginUINotAvailableError = (error: Error) => boolean
 
+	/**
+	 * Whether a registered command is selectable in the command palette.
+	 *
+	 * - `enabled`: shown and selectable.
+	 * - `disabled`: shown but not selectable; `reason` is displayed alongside the command.
+	 * - `hidden`: not shown in the palette at all.
+	 */
+	export type CommandAvailability =
+		| { type: 'enabled' }
+		| { type: 'disabled'; reason: string }
+		| { type: 'hidden' }
+
 	/**
 	 * Options for registering a command.
 	 */
@@ -802,6 +827,31 @@ declare module '@ampcode/plugin' {
 
 		/** Human-readable description of what this command does */
 		description?: string
+
+		/**
+		 * Initial availability of the command in the command palette.
+		 * Defaults to `{ type: 'enabled' }`.
+		 *
+		 * Use the {@link CommandSubscription.setAvailability} method on the
+		 * subscription returned by {@link PluginAPI.registerCommand} to update
+		 * availability dynamically.
+		 */
+		availability?: CommandAvailability
+	}
+
+	/**
+	 * Subscription returned by {@link PluginAPI.registerCommand}.
+	 *
+	 * Allows updating the command's availability in the palette in addition to
+	 * unregistering it.
+	 */
+	export interface CommandSubscription extends Subscription {
+		/**
+		 * Update whether this command is selectable in the command palette.
+		 * Triggers a refresh in the host so the palette reflects the new state
+		 * on its next read.
+		 */
+		setAvailability(status: CommandAvailability): void
 	}
 
 	/**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ampcode/plugin",
-	"version": "0.0.0-20260512003045-g373e11b",
+	"version": "0.0.0-20260513003404-g32e421b",
 	"description": "Amp Plugin API",
 	"homepage": "https://ampcode.com/manual/plugin-api",
 	"author": {