@ampcode/plugin 0.0.0-20260629024814-g800cf02 → 0.0.0-20260702003754-g0f76a16

package/README.md

@@ -10,7 +10,8 @@ Plugins can:
 - **Add tools** — `amp.registerTool(...)` for custom tools the agent can call
 - **Add commands** — `amp.registerCommand(...)` for command palette actions
 - **Show UI** — `ctx.ui.notify(...)`, `ctx.ui.confirm(...)`, `ctx.ui.input(...)`, and `ctx.ui.select(...)`
-- **Classify with AI** — `amp.ai.ask(...)` for yes/no decisions with confidence and reasoning
+- **Use AI** — `amp.ai.ask(...)` for thread-scoped yes/no classification that defaults to no
+  reasoning unless `{ reasoningEffort }` is set
 
 ## Locations
 

package/index.d.ts

@@ -253,7 +253,7 @@ declare module '@ampcode/plugin' {
 		 * Run `amp plugins show-agent-options --json` for the public model IDs intended for
 		 * plugin agents.
 		 */
-		model: string
+		model: PluginAIModel
 		/** Instructions appended to Amp's base agent prompt. */
 		instructions: string
 		/**
@@ -420,16 +420,104 @@ declare module '@ampcode/plugin' {
 		reason: string
 	}
 
+	export type PluginAIModelProvider =
+		| 'amp'
+		| 'anthropic'
+		| 'baseten'
+		| 'fireworks'
+		| 'openai'
+		| 'vertexai'
+		| 'xai'
+
+	/** Model identifier in `provider/model` format, such as `openai/gpt-5.5`. */
+	export type PluginAIModel = `${PluginAIModelProvider}/${string}`
+
+	export type PluginAIFieldSchema = {
+		type: string | string[]
+		description?: string
+		[key: string]: unknown
+	}
+
+	export type PluginAIJSONSchema = {
+		type: 'object'
+		properties?: Record<string, PluginAIFieldSchema>
+		required?: string[]
+		additionalProperties?: boolean
+		[key: string]: unknown
+	}
+
+	/**
+	 * Options for an AI operation.
+	 */
+	export interface PluginAIOptions {
+		/** Thread to bill and route the AI request through. Required outside a thread-bound handler. */
+		threadID?: ThreadID
+		/** Model identifier in `provider/model` format. Defaults to Amp's fast classifier model. */
+		model?: PluginAIModel
+		/** Optional reasoning effort override for models that support it. Defaults to no reasoning. */
+		reasoningEffort?: AgentReasoningEffort
+		/** Optional system instructions. */
+		system?: string
+		/** Maximum output tokens. */
+		maxTokens?: number
+	}
+
+	/**
+	 * Options for an AI ask operation.
+	 */
+	export interface PluginAIAskOptions extends PluginAIOptions {}
+
+	export interface PluginAIObjectSchema {
+		name: string
+		description?: string
+		fields: Record<string, PluginAIFieldSchema>
+	}
+
+	export interface PluginAIGenerateTextRequest extends PluginAIOptions {
+		/** The prompt to send to the model. */
+		prompt: string
+		/** Omit schema to receive a text response. */
+		schema?: never
+	}
+
+	export interface PluginAIGenerateObjectRequest extends PluginAIOptions {
+		/** The prompt to send to the model. */
+		prompt: string
+		/** Schema for structured output. Supplying a schema returns the validated object. */
+		schema: PluginAIObjectSchema
+	}
+
 	/**
 	 * AI capabilities provided to plugins.
 	 */
 	export interface PluginAI {
+		/**
+		 * Ask an AI model for a text response.
+		 *
+		 * Calls are routed through the current thread. Pass `threadID` when calling outside a
+		 * thread-bound handler.
+		 */
+		generate(request: PluginAIGenerateTextRequest): Promise<string>
+
+		/**
+		 * Ask an AI model for a structured JSON object matching the provided schema.
+		 *
+		 * Calls are routed through the current thread. Pass `threadID` when calling outside a
+		 * thread-bound handler.
+		 */
+		generate<T extends Record<string, unknown> = Record<string, unknown>>(
+			request: PluginAIGenerateObjectRequest,
+		): Promise<T>
+
 		/**
 		 * Ask an AI model a yes/no question and get a confidence-based response with reasoning.
+		 * This is a convenience wrapper around {@link PluginAI.generate}.
+		 *
 		 * @param question - The yes/no question to ask
+		 * @param options - Thread to bill and route the AI request through. Omit inside a thread-bound handler.
 		 * @returns Object with result, probability, and reason
 		 */
-		ask(question: string): Promise<PluginAIAskResult>
+		ask(question: string, options?: PluginAIAskOptions): Promise<PluginAIAskResult>
 	}
 
 	/**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ampcode/plugin",
-	"version": "0.0.0-20260629024814-g800cf02",
+	"version": "0.0.0-20260702003754-g0f76a16",
 	"description": "Amp Plugin API",
 	"homepage": "https://ampcode.com/manual/plugin-api",
 	"author": {