@ampcode/plugin 0.0.0-20260709003202-g32d9f9d → 0.0.0-20260711002658-g78d5e54

package/index.d.ts

@@ -120,9 +120,11 @@ 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.
+		 * Get an agent handle for one of Amp's built-in agent modes (`low`,
+		 * `medium`, `high`, or `ultra`). Threads spawned from the handle run the
+		 * built-in mode's prompt and tools, like a thread the user started in that
+		 * mode. Deprecated modes (`smart`, `deep`, `rush`) are accepted for
+		 * backward compatibility and spawn threads in their replacement mode.
 		 */
 		getBuiltinAgent(mode: BuiltinAgentMode, options?: GetBuiltinAgentOptions): Agent
 
@@ -179,9 +181,11 @@ 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.
+		 * Get an agent handle for one of Amp's built-in agent modes (`low`,
+		 * `medium`, `high`, or `ultra`). Threads spawned from the handle run the
+		 * built-in mode's prompt and tools, like a thread the user started in that
+		 * mode. Deprecated modes (`smart`, `deep`, `rush`) are accepted for
+		 * backward compatibility and spawn threads in their replacement mode.
 		 */
 		getBuiltinAgent(mode: BuiltinAgentMode, options?: GetBuiltinAgentOptions): Agent
 
@@ -231,8 +235,13 @@ declare module '@ampcode/plugin' {
 		| 'xhigh'
 		| 'max'
 
-	/** Amp built-in agent modes available to plugins. */
-	export type BuiltinAgentMode = 'smart' | 'deep' | 'rush'
+	/**
+	 * Amp built-in agent modes available to plugins. The `smart`, `deep`, and
+	 * `rush` modes are deprecated: existing threads in those modes keep working,
+	 * but new threads spawned from them start in the replacement mode
+	 * (`rush` → `low`; `smart`/`deep` → `medium`).
+	 */
+	export type BuiltinAgentMode = 'low' | 'medium' | 'high' | 'ultra' | 'smart' | 'deep' | 'rush'
 
 	export type AgentToolSelection =
 		| readonly string[]
@@ -300,6 +309,15 @@ declare module '@ampcode/plugin' {
 		reasoningEffort?: AgentReasoningEffort
 	}
 
+	export type AgentThreadExecutor =
+		| 'local'
+		| 'orb'
+		| {
+				type: 'runner'
+				/** Stable ID of a live Amp runner process. */
+				id: string
+		  }
+
 	export interface RunAgentOptions {
 		/** Maximum time to wait for the agent run to finish, in milliseconds (default 10 minutes). */
 		timeoutMs?: number
@@ -308,6 +326,12 @@ declare module '@ampcode/plugin' {
 		 * When omitted, the thread is created without a parent.
 		 */
 		parentThreadID?: ThreadID
+		/**
+		 * Where the thread should execute. Defaults to `local`, which uses the current
+		 * client as the executor. Use `orb` for Amp's cloud sandbox or a runner target
+		 * for a live Amp runner process such as `amp --no-tui`.
+		 */
+		executor?: AgentThreadExecutor
 	}
 
 	export interface CreateAgentThreadOptions {
@@ -318,6 +342,12 @@ declare module '@ampcode/plugin' {
 		parentThreadID?: ThreadID
 		/** Show the created thread and make it active in the client when supported. */
 		show?: boolean
+		/**
+		 * Where the thread should execute. Defaults to `local`, which uses the current
+		 * client as the executor. Use `orb` for Amp's cloud sandbox or a runner target
+		 * for a live Amp runner process such as `amp --no-tui`.
+		 */
+		executor?: AgentThreadExecutor
 	}
 
 	/** Thread handle returned by {@link Agent.createThread}. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ampcode/plugin",
-	"version": "0.0.0-20260709003202-g32d9f9d",
+	"version": "0.0.0-20260711002658-g78d5e54",
 	"description": "Amp Plugin API",
 	"homepage": "https://ampcode.com/manual/plugin-api",
 	"author": {