@ampcode/plugin 0.0.0-20260505003009-gecb28b5 → 0.0.0-20260507002947-gc0f61c8

package/README.md

@@ -1,79 +1,46 @@
-<!-- This file is rendered directly on https://ampcode.com/manual/plugin-api -->
+<!-- This file is the npm package README. The full guide lives at https://ampcode.com/manual#plugins -->
 
 # Amp Plugin API
 
-Amp plugins are TypeScript files that extend and customize [Amp](https://ampcode.com). Plugins live in `.amp/plugins/` (project) or `~/.config/amp/plugins/` (system).
+Amp plugins are TypeScript files that extend and customize [Amp](https://ampcode.com).
 
-> The Amp plugin API is experimental. Expect many breaking changes if you choose to use it right now. Do not use it for anything critical.
+Plugins can:
 
-The plugin API supports:
+- **Handle events** — `amp.on(...)` for tool calls, tool results, and agent lifecycle events
+- **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
 
-- **Event handlers** — `amp.on(...)` for hooking into tool calls, messages, and other events
-- **Tools** — `amp.registerTool(...)` for custom tools
-- **Commands** — `amp.registerCommand(...)` to add to Amp's command palette
-- **User input and UI** — `ctx.ui.notify(...)`, `ctx.ui.confirm(...)`
-- **AI & system utilities** — `amp.ai.ask(...)` for yes-no LLM answers
+## Locations
 
-<br/>
+Amp loads plugins from three locations:
 
-You can use plugins to:
+- **Project plugins** — `.amp/plugins/*.ts`
+- **System plugins** — `~/.config/amp/plugins/*.ts`
+- **Global plugins** — configured in workspace settings (limited experimental release)
 
-- Format files and report file diagnostics after each edit
-- Ensure Amp runs tests before finishing its work
-- Block or require confirmation for commands you deem risky
-- Correct common agent mistakes that AGENTS.md alone can't fix
-
-See [Amp Plugin API documentation](https://ampcode.com/manual/plugin-api).
-
-## Using Plugins
-
-Run the Amp CLI with `PLUGINS=all amp` to use plugins. If the `PLUGINS` env var is not set, plugins are disabled. Plugins can execute arbitrary code, so only enable plugins when running Amp in trusted workspaces.
-
-**Limitations:**
-
-- The Amp plugin API only works in the Amp CLI, not the Amp editor extension.
-- The Amp plugin API only works when the Amp CLI is installed via the binary install method, not via `npm install`.
-
-## Authoring Plugins
-
-Use this prompt:
-
-```
-Make an Amp plugin to __________. See https://ampcode.com/manual/plugin-api for docs.
-```
-
-- Ensure you're running with `PLUGINS=all amp`
-- Use `Ctrl-o` `plugins: reload` to reload all plugins after they're changed.
-- All plugin files must start with `// @i-know-the-amp-plugin-api-is-wip-and-very-experimental-right-now`.
-
-## Example Plugin
-
-`.amp/plugins/permissions.ts`:
+## Minimal Plugin
 
 ```ts
-// @i-know-the-amp-plugin-api-is-wip-and-very-experimental-right-now
 import type { PluginAPI } from '@ampcode/plugin'
 
 export default function (amp: PluginAPI) {
-	// Ask the user before executing any tool.
-	amp.on('tool.call', async (event, ctx) => {
-		const confirmed = await ctx.ui.confirm({
-			title: `Allow ${event.tool}?`,
-			message: `The agent wants to execute the "${event.tool}" tool.`,
-			confirmButtonText: 'Allow',
-		})
-		if (!confirmed) {
-			ctx.logger.log(`User rejected tool execution: ${event.tool}`)
-			return {
-				action: 'reject-and-continue',
-				message: `User rejected execution of tool ${event.tool}.`,
-			}
-		}
-		return { action: 'allow' }
+	amp.on('session.start', async (_event, ctx) => {
+		await ctx.ui.notify('Plugin loaded.')
 	})
 }
 ```
 
+After changing a plugin, open the command palette and run `plugins: reload`.
+
+## Documentation
+
+- Plugin guide and worked examples: <https://ampcode.com/manual#plugins>
+- Full `@ampcode/plugin` type reference and a complete kitchen-sink example: <https://ampcode.com/manual/plugin-api>
+
+Plugins execute code, so only use plugins from people and workspaces you trust.
+
 ## Acknowledgment
 
-Amp's plugin API is inspired by [pi's extension API](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/extensions.md), created by the awesome genius Mario Zechner.
+Amp's plugin API is inspired by [pi's extension API](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/extensions.md), created by Mario Zechner.

package/index.d.ts

@@ -47,6 +47,7 @@ declare module '@ampcode/plugin' {
 			toolCallsInMessages: ToolCallsInMessages
 			filesModifiedByToolCall: FilesModifiedByToolCall
 			filePathFromURI: FilePathFromURI
+			isPluginUINotAvailableError: IsPluginUINotAvailableError
 		}
 
 		/**
@@ -727,6 +728,11 @@ declare module '@ampcode/plugin' {
 	 */
 	export type FilePathFromURI = (uri: URI) => string
 
+	/**
+	 * Determines whether an instance of Error indicates that no Plugin UI is available.
+	 */
+	export type IsPluginUINotAvailableError = (error: Error) => boolean
+
 	/**
 	 * Options for registering a command.
 	 */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ampcode/plugin",
-	"version": "0.0.0-20260505003009-gecb28b5",
+	"version": "0.0.0-20260507002947-gc0f61c8",
 	"description": "Amp Plugin API",
 	"homepage": "https://ampcode.com/manual/plugin-api",
 	"author": {