@ampcode/plugin 0.0.0-20260511003151-g13ad60d → 0.0.0-20260512003045-g373e11b

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')
 	 * }
 	 * ```
 	 */
@@ -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
+		}
 	}
 
 	/**
@@ -197,16 +209,23 @@ 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
+	}
 
+	/**
+	 * Observable-like interface for Amp configuration.
+	 * Provides a limited subset of Observable functionality for plugins.
+	 */
+	export interface PluginConfiguration<T> extends Observable<T> {
 		/**
 		 * Pipe operators for transforming the configuration observable.
 		 */
@@ -482,11 +501,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 +731,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.

package/package.json

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