@ampcode/plugin 0.0.0-20260817001132-gbee24f5 → 0.0.0-20260818221056-gdf9ae7e

package/index.d.ts

@@ -354,6 +354,12 @@ declare module '@ampcode/plugin' {
 		tools?: AgentToolSelection
 		/** Optional reasoning effort override for models that support it. */
 		reasoningEffort?: AgentReasoningEffort
+		/**
+		 * Estimated input-token count at which Amp automatically compacts the thread.
+		 * Must be a positive safe integer. When omitted, Amp uses the configured
+		 * percentage threshold, which defaults to 90%.
+		 */
+		compactionThresholdTokens?: number
 		/**
 		 * Features required on threads created from this agent. Omit this field to inherit
 		 * the creating thread's features when the caller also omits
@@ -491,7 +497,10 @@ declare module '@ampcode/plugin' {
 		 * agent has no display.
 		 */
 		label?: string
-		/** Optional longer description shown in command palettes and pickers. */
+		/**
+		 * Optional longer description shown in command palettes and pickers. State both what the
+		 * mode does and when to use it.
+		 */
 		description?: string
 		/**
 		 * Optional label color as a hex RGB string, for example "#d97706".
@@ -1067,6 +1076,20 @@ declare module '@ampcode/plugin' {
 		 */
 		cancel(): Promise<void>
 
+		/**
+		 * Make this thread private or visible to every member of its workspace.
+		 * Making a thread private closes multiplayer. The authenticated user must
+		 * own the thread.
+		 */
+		setVisibility(visibility: 'private' | 'workspace'): Promise<void>
+
+		/**
+		 * Open multiplayer for the given number of seconds, or close it with `null`.
+		 * Opening multiplayer requires an Orb thread that is already shared. Valid
+		 * durations range from 5 minutes to 7 days.
+		 */
+		setMultiplayer(options: { ttlSeconds: number | null }): Promise<void>
+
 		/**
 		 * Read messages from the thread in a stable plugin-facing schema.
 		 *
@@ -1699,4 +1722,99 @@ 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. State both what the agent
+		 * does and when to use it.
+		 */
+		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. Use for evidence-backed research.',
+	 *   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-20260817001132-gbee24f5",
+	"version": "0.0.0-20260818221056-gdf9ae7e",
 	"description": "Amp Plugin API",
 	"homepage": "https://ampcode.com/manual/plugin-api",
 	"author": {