@ampcode/plugin 0.0.0-20260527003623-g8232386 → 0.0.0-20260528003340-g17febba

package/index.d.ts

@@ -124,6 +124,12 @@ declare module '@ampcode/plugin' {
 	 * APIs under `PluginAPI.experimental` are not stable and may change or be removed.
 	 */
 	export interface ExperimentalPluginAPI {
+		/** Create a custom agent bound to this plugin runtime. */
+		createAgent(config: CreateAgentConfig): Agent
+
+		/** Register a custom agent mode that clients may show alongside built-in modes. */
+		registerAgentMode(definition: PluginAgentModeDefinition): Subscription
+
 		/**
 		 * Create a status item shown near the prompt editor or status bar in the Amp client.
 		 *
@@ -146,6 +152,73 @@ declare module '@ampcode/plugin' {
 		}
 	}
 
+	export type AgentReasoningEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high'
+
+	export type AgentToolSelection =
+		| readonly string[]
+		| 'all'
+		| {
+				/** Tool names to include. Defaults to all tools. */
+				include?: readonly string[] | 'all'
+				/** Tool names to exclude after applying include. */
+				exclude?: readonly string[]
+		  }
+
+	export interface CreateAgentConfig {
+		/** Optional stable identifier for logs, UI, and persisted run metadata. */
+		name?: string
+		/** Model identifier in `provider/model` format, such as `anthropic/claude-sonnet-4-6`. */
+		model: string
+		/** Instructions appended to Amp's base agent prompt. */
+		instructions: string
+		/** Tools available to this agent. Use 'all' for all tools available in its runtime. */
+		tools?: AgentToolSelection
+		/** Optional reasoning effort override for models that support it. */
+		reasoningEffort?: AgentReasoningEffort
+	}
+
+	export interface AgentDefinition extends CreateAgentConfig {
+		readonly kind: 'agent-definition'
+	}
+
+	export interface RunAgentOptions {
+		/** Maximum time to wait for the agent run to finish, in milliseconds. */
+		timeoutMs?: number
+		/** Parent thread for this run when the agent is being used as a subagent/tool. */
+		parentThreadID?: ThreadID
+	}
+
+	export interface AgentRunResult {
+		/** Thread created for this run, when exposed by the runtime. */
+		threadID?: `T-${string}`
+		/** Final text response from the agent. */
+		text: string
+	}
+
+	export interface Agent {
+		readonly definition: AgentDefinition
+		run(message: string, options?: RunAgentOptions): Promise<AgentRunResult>
+	}
+
+	/** A plugin-defined agent mode shown by supported Amp clients. */
+	export interface PluginAgentModeDefinition {
+		/** Stable identifier within the plugin. */
+		key: string
+		/** Label shown in compact mode pickers, for example "review" or "architect". */
+		label: string
+		/** Optional longer description shown in command palettes and pickers. */
+		description?: string
+		/** Optional label color as a hex RGB string, for example "#d97706". */
+		color?: string
+		/** Agent definition used when creating a thread with this mode selected. */
+		agent: AgentDefinition
+	}
+
+	export interface PluginAgentMode extends Omit<PluginAgentModeDefinition, 'agent'> {
+		pluginName: string
+		agent: AgentDefinition
+	}
+
 	/**
 	 * A plugin status item shown in supported Amp clients.
 	 */
@@ -411,12 +484,46 @@ declare module '@ampcode/plugin' {
 	export type ThreadMessage = ThreadUserMessage | ThreadAssistantMessage | ThreadInfoMessage
 
 	/**
-	 * Thread API for manipulating the current thread.
+	 * Options for reading messages from a thread.
+	 */
+	export interface ThreadMessagesOptions {
+		/**
+		 * Where to read from. Defaults to `end` so callers read recent messages by
+		 * default instead of accidentally loading the start of a large thread.
+		 */
+		from?: 'start' | 'end'
+
+		/**
+		 * What the offset is in relation to `from`.  Defaults to 0.
+		 */
+		offset?: number
+
+		/**
+		 * Maximum number of messages to return. Clamped to 20.
+		 */
+		limit?: number
+
+		/**
+		 * Optional role filter.
+		 */
+		roles?: Array<'user' | 'assistant'>
+	}
+
+	/**
+	 * Thread API for reading and manipulating the current thread.
 	 */
 	export interface PluginThread {
 		/** Active thread ID for the current invocation context */
 		id: ThreadID
 
+		/**
+		 * Read messages from the thread in a stable plugin-facing schema.
+		 *
+		 * Defaults to `{ from: 'end', limit: 10 }`. The maximum `limit`
+		 * is 20.  Combine with `offset` to fetch more messages.
+		 */
+		messages(options?: ThreadMessagesOptions): Promise<ThreadMessage[]>
+
 		/**
 		 * Append a user message to the thread.
 		 */
@@ -544,7 +651,7 @@ declare module '@ampcode/plugin' {
 	 * This is a request that expects a response from the handler.
 	 */
 	export interface ToolCallEvent extends ToolCall {
-		/** The active thread for this tool invocation */
+		/** The active thread reference for this tool invocation. */
 		thread: { id: ThreadID }
 	}
 
@@ -887,6 +994,9 @@ declare module '@ampcode/plugin' {
 
 		/** Scoped logger for plugin output */
 		logger: PluginLogger
+
+		/** Current thread context for this tool invocation */
+		thread: PluginThread
 	}
 
 	/**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ampcode/plugin",
-	"version": "0.0.0-20260527003623-g8232386",
+	"version": "0.0.0-20260528003340-g17febba",
 	"description": "Amp Plugin API",
 	"homepage": "https://ampcode.com/manual/plugin-api",
 	"author": {