@ampcode/plugin 0.0.0-20260816001043-ge65dd2b → 0.0.0-20260818001058-gcb0a91a

package/index.d.ts

@@ -341,7 +341,7 @@ declare module '@ampcode/plugin' {
 		 * Run `amp plugins show-agent-options --json` for the public model IDs intended for
 		 * plugin agents.
 		 */
-		model: PluginAIModel
+		model: PluginAgentModel
 		/** Instructions appended to Amp's base agent prompt. */
 		instructions: string
 		/**
@@ -561,6 +561,12 @@ declare module '@ampcode/plugin' {
 	/** Model identifier in `provider/model` format, such as `openai/gpt-5.6-sol`. */
 	export type PluginAIModel = `${PluginAIModelProvider}/${string}`
 
+	/**
+	 * Model identifier for a custom agent. Providers outside Amp's built-in set require a matching
+	 * AI router configured for the account at inference time.
+	 */
+	export type PluginAgentModel = `${string}/${string}`
+
 	export type PluginAIFieldSchema = {
 		type: string | string[]
 		description?: string
@@ -1662,6 +1668,12 @@ declare module '@ampcode/plugin' {
 		/** Tool name (must match ^[a-zA-Z0-9_-]+$) */
 		name: string
 
+		/**
+		 * Human-readable display title shown in Amp clients instead of the raw
+		 * tool name, e.g. `Tap screen` instead of `sim_tap`. Not sent to the LLM.
+		 */
+		title?: string
+
 		/** Description shown to the LLM explaining what the tool does */
 		description: string
 
@@ -1687,4 +1699,96 @@ declare module '@ampcode/plugin' {
 		/** Path to the skill directory, relative to the directory plugin's root. */
 		path: string
 	}
+
+	/**
+	 * Config for a declarative agent, the argument to {@link defineAgent} in an agent directory's
+	 * `agent.ts`. Amp parses this object statically, so it must be a plain object literal of
+	 * string, number, boolean, array, and object literals — no imports, variables, or computed
+	 * values. The file is required in every agent directory, but every config field is optional;
+	 * `defineAgent({})` is a complete config.
+	 */
+	export interface AgentConfig {
+		/** Label shown in mode pickers and thread headers, 24 characters or less. Defaults to the agent's directory name. */
+		label?: string
+		/** Description shown in agent listings, 500 characters or less. */
+		description?: string
+		/** Label color as a hex RGB string, for example "#d97706". */
+		color?: string
+		/**
+		 * Model identifier in `provider/model` format, such as `anthropic/claude-sonnet-4-6`.
+		 * Omit to use the default model.
+		 */
+		model?: PluginAIModel
+		/** Run entirely on Amp's thread actor without creating or attaching an executor. */
+		serverOnly?: boolean
+		/**
+		 * Built-in tools available to this agent: 'all' for all tools available in its runtime,
+		 * or a list of tool names with `*` suffix wildcards.
+		 */
+		tools?: 'all' | readonly string[]
+		/** Optional reasoning effort override for models that support it. */
+		reasoningEffort?: AgentReasoningEffort
+		/** Features required on threads created from this agent. */
+		features?: readonly AgentFeature[]
+	}
+
+	/**
+	 * Declare a declarative agent's config in its directory's `agent.ts`:
+	 *
+	 * ```ts
+	 * import { defineAgent } from '@ampcode/plugin'
+	 *
+	 * export default defineAgent({
+	 *   description: 'Researches requests and cites primary sources',
+	 *   model: 'openai/gpt-5-mini',
+	 *   tools: ['web_search', 'read_web_page'],
+	 *   reasoningEffort: 'medium',
+	 * })
+	 * ```
+	 *
+	 * Returns the config unchanged; it exists for typing and static parsing.
+	 */
+	export function defineAgent(config: AgentConfig): AgentConfig
+
+	/**
+	 * A custom tool declared in an agent directory's `tools/<name>.ts` file, the argument to
+	 * {@link defineTool}. The tool's name is the filename. The `description` and `execution`
+	 * fields must be static literals; `inputSchema` and `execute` are real code that is not
+	 * statically parsed and runs where `execution` places it.
+	 */
+	export interface AgentToolConfig {
+		/** Description shown to the LLM explaining what the tool does */
+		description?: string
+
+		/**
+		 * Where the tool executes. `server` tools run where the agent runs (its sandbox, no
+		 * repository checkout needed); `executor` tools are dispatched to the attached executor
+		 * at the repository checkout. Defaults to `server`.
+		 */
+		execution?: 'server' | 'executor'
+
+		/** JSON Schema for the tool's input parameters */
+		inputSchema: PluginToolDefinition['inputSchema']
+
+		/** Execute the tool with the given input and return a result */
+		execute: PluginToolDefinition['execute']
+	}
+
+	/**
+	 * Declare a custom tool in an agent directory's `tools/<name>.ts`:
+	 *
+	 * ```ts
+	 * import { defineTool } from '@ampcode/plugin'
+	 *
+	 * export default defineTool({
+	 *   description: 'Fetch open tickets',
+	 *   execution: 'server',
+	 *   inputSchema: { type: 'object', properties: { query: { type: 'string' } } },
+	 *   execute: async (input) => ({ content: [{ type: 'text', text: JSON.stringify(input) }] }),
+	 * })
+	 * ```
+	 *
+	 * Returns the tool unchanged; it exists for typing and static parsing.
+	 */
+	export function defineTool(tool: AgentToolConfig): AgentToolConfig
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ampcode/plugin",
-	"version": "0.0.0-20260816001043-ge65dd2b",
+	"version": "0.0.0-20260818001058-gcb0a91a",
 	"description": "Amp Plugin API",
 	"homepage": "https://ampcode.com/manual/plugin-api",
 	"author": {