@ampcode/plugin 0.0.0-20260610024544-gdeae2c5 → 0.0.0-20260612025159-g6d2b3bd

package/README.md

@@ -36,7 +36,7 @@ export default function (amp: PluginAPI) {
 
 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`.
+After changing a plugin, open the command palette and run `plugins: reload`, or restart Amp.
 
 ## Documentation
 

package/index.d.ts

@@ -25,7 +25,7 @@ declare module '@ampcode/plugin' {
 		/** Logger scoped to this plugin */
 		logger: PluginLogger
 
-		/** System capabilities and environment information */
+		/** System capabilities and information */
 		system: PluginSystem
 
 		/** Observable configuration that streams changes */
@@ -132,6 +132,13 @@ declare module '@ampcode/plugin' {
 		 */
 		createAgent(config: CreateAgentConfig): Agent
 
+		/**
+		 * Get an agent handle for one of Amp's built-in agent modes (`smart`,
+		 * `deep`, or `rush`). Threads spawned from the handle run the built-in
+		 * mode's prompt and tools, like a thread the user started in that mode.
+		 */
+		getBuiltinAgent(mode: BuiltinAgentMode, options?: GetBuiltinAgentOptions): Agent
+
 		/** Register a custom agent mode that clients may show alongside built-in modes. */
 		registerAgentMode(definition: PluginAgentModeDefinition): Subscription
 
@@ -160,7 +167,18 @@ declare module '@ampcode/plugin' {
 		threads: PluginThreads
 	}
 
-	export type AgentReasoningEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high'
+	/** Reasoning effort levels supported by plugin agents, for models that support them. */
+	export type AgentReasoningEffort =
+		| 'none'
+		| 'minimal'
+		| 'low'
+		| 'medium'
+		| 'high'
+		| 'xhigh'
+		| 'max'
+
+	/** Amp built-in agent modes available to plugins. */
+	export type BuiltinAgentMode = 'smart' | 'deep' | 'rush'
 
 	export type AgentToolSelection =
 		| readonly string[]
@@ -193,28 +211,96 @@ declare module '@ampcode/plugin' {
 		tools?: AgentToolSelection
 		/** Optional reasoning effort override for models that support it. */
 		reasoningEffort?: AgentReasoningEffort
+		/**
+		 * Display shown for threads running this agent. Travels with the agent
+		 * definition, so threads created from it — including by other plugins via
+		 * a `thread.agent()` handle — carry the label.
+		 */
+		display?: AgentDisplay
 	}
 
-	export interface AgentDefinition extends CreateAgentConfig {
+	/** Display metadata for a plugin agent. */
+	export interface AgentDisplay {
+		/** Label shown in mode pickers and thread headers, 16 characters or less. */
+		label: string
+		/** Optional label color as a hex RGB string, for example "#d97706". */
+		color?: string
+	}
+
+	export interface CustomAgentDefinition extends CreateAgentConfig {
 		readonly kind: 'agent-definition'
 	}
 
+	/** Reference to one of Amp's built-in agent modes. */
+	export interface BuiltinAgentDefinition {
+		readonly kind: 'builtin-agent'
+		mode: BuiltinAgentMode
+		/** Reasoning effort pinned on threads spawned from this agent. */
+		reasoningEffort?: AgentReasoningEffort
+	}
+
+	export type AgentDefinition = CustomAgentDefinition | BuiltinAgentDefinition
+
+	export interface GetBuiltinAgentOptions {
+		/** Reasoning effort pinned on threads spawned from this agent. */
+		reasoningEffort?: AgentReasoningEffort
+	}
+
 	export interface RunAgentOptions {
-		/** Maximum time to wait for the agent run to finish, in milliseconds. */
+		/** Maximum time to wait for the agent run to finish, in milliseconds (default 10 minutes). */
 		timeoutMs?: number
-		/** Parent thread for this run when the agent is being used as a subagent/tool. */
+		/**
+		 * Parent thread for this run when the agent is being used as a subagent/tool.
+		 * When omitted, the thread is created without a parent.
+		 */
 		parentThreadID?: ThreadID
 	}
 
+	export interface CreateAgentThreadOptions {
+		/**
+		 * Parent thread for the new thread when the agent is being used as a
+		 * subagent/tool. When omitted, the thread is created without a parent.
+		 */
+		parentThreadID?: ThreadID
+		/** Show the created thread in the client when supported. */
+		show?: boolean
+	}
+
+	/** Thread handle returned by {@link Agent.createThread}. */
+	export type AgentThread = PluginThread
+
 	export interface AgentRunResult {
-		/** Thread created for this run, when exposed by the runtime. */
-		threadID?: `T-${string}`
+		/** Thread created for this run. */
+		threadID: `T-${string}`
 		/** Final text response from the agent. */
 		text: string
 	}
 
+	/**
+	 * A handle to a custom or built-in agent, returned by
+	 * {@link ExperimentalPluginAPI.createAgent} and
+	 * {@link ExperimentalPluginAPI.getBuiltinAgent}.
+	 */
 	export interface Agent {
 		readonly definition: AgentDefinition
+
+		/**
+		 * Create a background thread running this agent and return a handle for
+		 * interacting with it: append messages, await replies with
+		 * {@link PluginThread.waitForResponse}, observe state, or cancel.
+		 *
+		 * The thread keeps running independently of the caller; there is no
+		 * lifecycle to manage.
+		 */
+		createThread(options?: CreateAgentThreadOptions): Promise<AgentThread>
+
+		/**
+		 * One-shot run: create a thread, send the message, and resolve with the
+		 * assistant's reply once the turn finishes.
+		 *
+		 * When called from inside an executing plugin tool, aborting that tool
+		 * cancels the agent's turn.
+		 */
 		run(message: string, options?: RunAgentOptions): Promise<AgentRunResult>
 	}
 
@@ -222,17 +308,26 @@ declare module '@ampcode/plugin' {
 	export interface PluginAgentModeDefinition {
 		/** Stable identifier within the plugin. */
 		key: string
-		/** Label shown in compact mode pickers, for example "review" or "architect". */
-		label: string
+		/**
+		 * Label shown in compact mode pickers, for example "review" or "architect".
+		 * Defaults to the agent definition's `display.label`; required when the
+		 * agent has no display.
+		 */
+		label?: string
 		/** Optional longer description shown in command palettes and pickers. */
 		description?: string
-		/** Optional label color as a hex RGB string, for example "#d97706". */
+		/**
+		 * Optional label color as a hex RGB string, for example "#d97706".
+		 * Defaults to the agent definition's `display.color`.
+		 */
 		color?: string
 		/** Agent definition used when creating a thread with this mode selected. */
 		agent: AgentDefinition
 	}
 
-	export interface PluginAgentMode extends Omit<PluginAgentModeDefinition, 'agent'> {
+	export interface PluginAgentMode extends Omit<PluginAgentModeDefinition, 'agent' | 'label'> {
+		/** Resolved mode label (from the definition or the agent's display). */
+		label: string
 		pluginName: string
 		agent: AgentDefinition
 	}
@@ -392,7 +487,46 @@ declare module '@ampcode/plugin' {
 	}
 
 	/**
-	 * System capabilities provided to plugins.
+	 * Identity of the authenticated Amp user exposed to plugins.
+	 */
+	export interface User {
+		/**
+		 * Opaque string that identifies the user.
+		 */
+		readonly id: string
+
+		/** User's email address. */
+		readonly email: string
+
+		/** User's first name, when set. */
+		readonly firstName: string | null
+
+		/** User's last name, when set. */
+		readonly lastName: string | null
+
+		/** User's Amp username, when set. */
+		readonly username: string | null
+
+		/** Workspace the user belongs to, or null when the user is not in a workspace. */
+		readonly workspace: Workspace | null
+	}
+
+	/**
+	 * Workspace identity for the authenticated user.
+	 */
+	export interface Workspace {
+		/** Opaque string that identifies the workspace. */
+		readonly id: string
+
+		/** Workspace slug/name. */
+		readonly name: string
+
+		/** Human-friendly workspace display name, when set. */
+		readonly displayName: string | null
+	}
+
+	/**
+	 * System capabilities and information provided to plugins.
 	 */
 	export interface PluginSystem {
 		/**
@@ -407,6 +541,11 @@ declare module '@ampcode/plugin' {
 		 */
 		readonly ampURL: URL
 
+		/**
+		 * Identity of the authenticated Amp user, or null when Amp is not authenticated.
+		 */
+		readonly user: User | null
+
 		/**
 		 * Information about the executor that is running this plugin.
 		 */
@@ -527,6 +666,16 @@ declare module '@ampcode/plugin' {
 		roles?: Array<'user' | 'assistant'>
 	}
 
+	/**
+	 * Agent activity state of a thread.
+	 *
+	 * - `idle`: the agent is not working; the last turn (if any) has finished.
+	 * - `running`: the agent is working (inference or tool execution in progress).
+	 * - `awaiting-approval`: the agent is blocked waiting for a tool approval.
+	 * - `error`: the thread has an active error.
+	 */
+	export type ThreadState = 'idle' | 'running' | 'awaiting-approval' | 'error'
+
 	/**
 	 * Thread API for reading and manipulating the current thread.
 	 */
@@ -534,9 +683,29 @@ declare module '@ampcode/plugin' {
 		/** Active thread ID for the current invocation context */
 		id: ThreadID
 
+		/** Agent currently used by this thread, suitable for creating related threads. */
+		agent(): Promise<Agent>
+
 		/** Current thread title stream, or `null` when no title has been set yet. */
 		readonly title: Observable<string | null> & { get(): Promise<string | null> }
 
+		/** Agent activity state stream for this thread. */
+		readonly state: Observable<ThreadState> & { get(): Promise<ThreadState> }
+
+		/**
+		 * Wait for the current or next agent turn to finish and resolve with the
+		 * assistant's reply.
+		 *
+		 * Waits until the thread has been `running` (or `awaiting-approval`) and
+		 * returns to `idle`, then resolves with the last assistant message.
+		 * Rejects if the thread enters the `error` state or the timeout elapses
+		 * (default 10 minutes).
+		 */
+		waitForResponse(options?: { timeoutMs?: number }): Promise<ThreadAssistantMessage>
+
+		/** Stop the agent's current turn in this thread, if one is running. */
+		cancel(): Promise<void>
+
 		/**
 		 * Read messages from the thread in a stable plugin-facing schema.
 		 *
@@ -888,7 +1057,7 @@ declare module '@ampcode/plugin' {
 		/** AI capabilities */
 		ai: PluginAI
 
-		/** System capabilities */
+		/** System capabilities and information */
 		system: PluginSystem
 
 		/** The trace span ID for this handler invocation, if tracing is enabled */
@@ -1018,7 +1187,7 @@ declare module '@ampcode/plugin' {
 		/** AI capabilities */
 		ai: PluginAI
 
-		/** System capabilities */
+		/** System capabilities and information */
 		system: PluginSystem
 
 		/** Bun's shell API for executing commands */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ampcode/plugin",
-	"version": "0.0.0-20260610024544-gdeae2c5",
+	"version": "0.0.0-20260612025159-g6d2b3bd",
 	"description": "Amp Plugin API",
 	"homepage": "https://ampcode.com/manual/plugin-api",
 	"author": {