@ampcode/plugin 0.0.0-20260511003151-g13ad60d → 0.0.0-20260513003404-g32e421b

package/README.md

@@ -26,12 +26,16 @@ Amp loads plugins from three locations:
 import type { PluginAPI } from '@ampcode/plugin'
 
 export default function (amp: PluginAPI) {
-	amp.on('session.start', async (_event, ctx) => {
-		await ctx.ui.notify('Plugin loaded.')
+	amp.logger.log('Plugin initialized')
+
+	amp.on('session.start', async (event, ctx) => {
+		await ctx.ui.notify(`Thread ${event.thread.id} started.`)
 	})
 }
 ```
 
+Code in the exported function runs when the plugin loads. Use `session.start` only for work that should run when Amp starts a specific thread session.
+
 After changing a plugin, open the command palette and run `plugins: reload`.
 
 ## Documentation

package/index.d.ts

@@ -13,9 +13,7 @@ declare module '@ampcode/plugin' {
 	 * import type { PluginAPI } from '@ampcode/plugin'
 	 *
 	 * export default function (amp: PluginAPI) {
-	 *   amp.on('session.start', (event, ctx) => {
-	 *     ctx.ui.notify('Welcome')
-	 *   })
+	 *   amp.logger.log('Plugin initialized')
 	 * }
 	 * ```
 	 */
@@ -81,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.
@@ -129,6 +127,20 @@ declare module '@ampcode/plugin' {
 		 * If no initial value is provided, the item is hidden until its first update.
 		 */
 		createStatusItem(initial?: StatusItemValue): StatusItem
+
+		/**
+		 * Observable that emits the currently active thread (the one the user is focused on
+		 * in the UI), or `null` when no thread is active.
+		 *
+		 * Use this to determine whether the thread that triggered an event is the one the user
+		 * is currently looking at, or is running in the background. For example, in a
+		 * `tool.call` handler, compare `event.thread.id` to
+		 * `amp.experimental.activeThread.current` to decide whether to surface a UI prompt
+		 * (active) or take a non-interactive default (background).
+		 */
+		activeThread: Observable<{ id: ThreadID } | null> & {
+			readonly current: { id: ThreadID } | null
+		}
 	}
 
 	/**
@@ -143,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
 	}
 
@@ -197,21 +214,33 @@ declare module '@ampcode/plugin' {
 	export type PluginConfigurationTarget = 'workspace' | 'global'
 
 	/**
-	 * Observable-like interface for Amp configuration.
-	 * Provides a limited subset of Observable functionality for plugins.
+	 * Minimal Observable interface used by plugin APIs that stream values over time.
+	 *
+	 * Subscribers receive subsequent values until they unsubscribe.
 	 */
-	export interface PluginConfiguration<T> {
+	export interface Observable<T> {
 		/**
-		 * Subscribe to configuration changes.
+		 * Subscribe to values emitted by this observable.
 		 */
 		subscribe(observer: PluginConfigurationObserver<T>): Subscription
 		subscribe(onNext: (value: T) => void): Subscription
 
 		/**
-		 * Pipe operators for transforming the configuration observable.
+		 * Pipe operators for transforming this observable.
+		 */
+		pipe<Out>(op: (input: Observable<T>) => Out): Out
+
+		/**
+		 * Return this observable for interop with observable libraries.
 		 */
-		pipe<Out>(op: (input: PluginConfiguration<T>) => Out): Out
+		[Symbol.observable](): Observable<T>
+	}
 
+	/**
+	 * Observable-like interface for Amp configuration.
+	 * Provides a limited subset of Observable functionality for plugins.
+	 */
+	export interface PluginConfiguration<T> extends Observable<T> {
 		/**
 		 * Get the current configuration value.
 		 */
@@ -441,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[]
 	}
@@ -482,11 +514,12 @@ declare module '@ampcode/plugin' {
 
 	/**
 	 * Event payload for session.start event.
-	 * Fired when the plugin session starts and before the first event for each thread.
+	 * Fired when Amp starts a thread session, such as when the user sends the first
+	 * message in a new thread or opens/switches to an existing thread.
 	 */
 	export interface SessionStartEvent {
-		/** The active thread for this session, when available */
-		thread?: { id: ThreadID }
+		/** The thread that started running */
+		thread: { id: ThreadID }
 	}
 
 	/**
@@ -711,10 +744,11 @@ declare module '@ampcode/plugin' {
 
 	/**
 	 * Context passed as the second argument to event handlers.
-	 * `session.start` may be emitted before a thread exists, while all other events are thread-scoped.
+	 * All plugin events are thread-scoped.
 	 */
-	export type PluginEventContext<E extends keyof PluginEventMap> = PluginEventContextBase &
-		(E extends 'session.start' ? { thread?: PluginThread } : { thread: PluginThread })
+	export type PluginEventContext<E extends keyof PluginEventMap> = PluginEventContextBase & {
+		thread: PluginThread
+	}
 
 	/**
 	 * Handler return type based on whether the event expects a response.
@@ -769,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.
 	 */
@@ -781,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-20260511003151-g13ad60d",
+	"version": "0.0.0-20260513003404-g32e421b",
 	"description": "Amp Plugin API",
 	"homepage": "https://ampcode.com/manual/plugin-api",
 	"author": {