@ampcode/plugin 0.0.0-20260727003132-g7dd9424 → 0.0.0-20260729002615-g8a974c9

package/README.md

@@ -12,6 +12,9 @@ Plugins can:
 - **Show UI** — `ctx.ui.notify(...)`, `ctx.ui.confirm(...)`, `ctx.ui.input(...)`, and `ctx.ui.select(...)`
 - **Use AI** — `amp.ai.ask(...)` for thread-scoped yes/no classification that defaults to no
   reasoning unless `{ reasoningEffort }` is set
+- **Upload attachments** — `amp.attachments.upload(...)` to upload image bytes and get back a URL
+  for URL-backed `{ type: 'image', mimeType, url }` tool result blocks, keeping large images out
+  of thread state
 
 ## Locations
 

package/index.d.ts

@@ -108,6 +108,32 @@ declare module '@ampcode/plugin' {
 		 */
 		registerTool(definition: PluginToolDefinition): Subscription
 
+		/**
+		 * Register a callback that runs before this plugin instance is stopped.
+		 *
+		 * Dispose callbacks run when the plugin is unloaded or reloaded and on graceful
+		 * host shutdown. Use them to release resources the plugin owns outside its own
+		 * process, such as child processes, remote sessions, or temporary files.
+		 *
+		 * The host bounds cleanup time: all of a plugin's dispose callbacks together
+		 * get about 3 seconds. After they settle or the budget elapses, the plugin
+		 * process is terminated. Callbacks run concurrently, in no guaranteed order,
+		 * and thrown errors are logged and otherwise ignored.
+		 *
+		 * Dispose callbacks do NOT run when the plugin process crashes or is killed
+		 * with SIGKILL. Keep an external backstop (such as a server-side idle
+		 * timeout) for resources that must not outlive the plugin in those cases.
+		 *
+		 * @example
+		 * ```ts
+		 * const server = await startHelperProcess()
+		 * amp.onDispose(async () => {
+		 *   await server.stop()
+		 * })
+		 * ```
+		 */
+		onDispose(callback: () => void | Promise<void>): Subscription
+
 		/**
 		 * Register a durable generic webhook for this plugin and the owning Orb thread.
 		 *
@@ -120,7 +146,6 @@ declare module '@ampcode/plugin' {
 		 * before durable consumption is recorded. Handlers have 30 seconds to complete;
 		 * `ctx.signal` is aborted when that deadline elapses, and the event is retried.
 		 *
-		 * @experimental
 		 * @example
 		 * ```ts
 		 * const { url } = await amp.createWebhook({
@@ -136,6 +161,9 @@ declare module '@ampcode/plugin' {
 		/** AI helpers */
 		ai: PluginAI
 
+		/** Attachment uploads, for URL-backed image tool result blocks */
+		attachments: PluginAttachments
+
 		/**
 		 * Create a custom agent bound to this plugin runtime.
 		 *
@@ -279,7 +307,11 @@ declare module '@ampcode/plugin' {
 		  }
 
 	export interface CreateAgentConfig {
-		/** Optional stable identifier for logs, UI, and persisted run metadata. */
+		/**
+		 * Optional agent identity. Amp includes this name in the base system prompt as
+		 * `You are <name>, a custom agent running in Amp.` It is also used for logs, UI,
+		 * and persisted run metadata. Omit it to avoid adding a named identity to the prompt.
+		 */
 		name?: string
 		/**
 		 * Model identifier in `provider/model` format, such as `anthropic/claude-sonnet-4-6`.
@@ -361,11 +393,10 @@ declare module '@ampcode/plugin' {
 		/** Show the created thread and make it active in the client when supported. */
 		show?: boolean
 		/**
-		 * Serving speed for the new thread. When omitted, the thread inherits the
-		 * creating thread's speed. Fast mode uses faster serving for supported
-		 * models and is billed at a premium.
+		 * Features for the new thread. Omit to inherit the creating thread's features;
+		 * pass an empty array to clear them.
 		 */
-		speed?: 'standard' | 'fast'
+		features?: readonly 'fast'[]
 		/**
 		 * Enable multiplayer for this many seconds. Multiplayer threads must run in an
 		 * Orb and belong to a workspace. Valid values range from 5 minutes to 7 days.
@@ -579,6 +610,58 @@ declare module '@ampcode/plugin' {
 		ask(question: string, options?: PluginAIAskOptions): Promise<PluginAIAskResult>
 	}
 
+	/**
+	 * Input for {@link PluginAttachments.upload}.
+	 */
+	export interface PluginAttachmentUploadInput {
+		/** Raw bytes, or a base64-encoded payload with no data: prefix. */
+		data: Uint8Array | string
+
+		/** MIME type, e.g. 'image/png', 'image/jpeg', or 'image/webp'. */
+		mimeType: string
+	}
+
+	/**
+	 * An attachment uploaded to the Amp server.
+	 */
+	export interface PluginAttachment {
+		/** HTTPS URL that serves the uploaded bytes. */
+		url: string
+	}
+
+	/**
+	 * Attachment upload capability provided to plugins.
+	 */
+	export interface PluginAttachments {
+		/**
+		 * Upload bytes to the Amp server as an attachment and get back a URL.
+		 *
+		 * The returned URL can be used in a `{ type: 'image', mimeType, url }` tool result
+		 * block, which keeps large image payloads (e.g. screenshots) out of thread state.
+		 * The upload is subject to the Amp server's attachment media-type and size policy,
+		 * and the resulting URL is fetchable by Amp's inference providers. Image uploads are
+		 * additionally validated against Amp's inference image limits before uploading:
+		 * at most 4.9 MB decoded and at most 8000px per dimension.
+		 *
+		 * Throws if the upload fails (e.g. offline, unauthorized, payload rejected by the
+		 * server's policy, or an image exceeding the inference image limits). Callers
+		 * returning tool results should catch errors and fall back to an inline base64
+		 * image block.
+		 *
+		 * @example
+		 * ```ts
+		 * const png: Uint8Array = await captureScreenshot()
+		 * try {
+		 *   const { url } = await amp.attachments.upload({ data: png, mimeType: 'image/png' })
+		 *   return [{ type: 'image', mimeType: 'image/png', url }]
+		 * } catch {
+		 *   return [{ type: 'image', mimeType: 'image/png', data: Buffer.from(png).toString('base64') }]
+		 * }
+		 * ```
+		 */
+		upload(input: PluginAttachmentUploadInput): Promise<PluginAttachment>
+	}
+
 	/**
 	 * Observer interface for subscribing to configuration changes.
 	 */
@@ -1013,7 +1096,7 @@ declare module '@ampcode/plugin' {
 		/** Dialog title */
 		title: string
 
-		/** Message body shown below the title */
+		/** Markdown message body shown below the title */
 		message?: string
 
 		/** Text for the confirm button (default: "Yes") */
@@ -1033,7 +1116,7 @@ declare module '@ampcode/plugin' {
 		 */
 		allowOther?: boolean
 
-		/** Message body shown below the title */
+		/** Markdown message body shown below the title */
 		message?: string
 
 		/** Initially selected option value */
@@ -1169,12 +1252,28 @@ declare module '@ampcode/plugin' {
 				/** Base64-encoded payload with no data: prefix. */
 				data: string
 		  }
+		| {
+				type: 'image'
+
+				/** MIME type, e.g. 'image/png', 'image/jpeg', or 'image/webp'. */
+				mimeType: string
+
+				/**
+				 * HTTPS URL of the image, typically obtained from {@link PluginAttachments.upload}.
+				 * The URL must be fetchable by Amp's inference providers and web/CLI clients.
+				 * Using a URL keeps large image payloads out of thread state.
+				 */
+				url: string
+		  }
 
 	/**
 	 * Result returned from a plugin tool.
 	 *
 	 * Returning a bare string keeps the existing text-only behavior. Returning an array
-	 * of content blocks lets a tool mix text and inline base64 image blocks.
+	 * of content blocks lets a tool mix text and image blocks. Image blocks carry either
+	 * an inline base64 payload (`data`) or a URL (`url`), never both. Prefer uploading
+	 * large images with {@link PluginAttachments.upload} and returning a URL block, and
+	 * fall back to an inline base64 block if the upload fails.
 	 */
 	export type PluginToolResult = string | PluginToolResultContentBlock[]
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ampcode/plugin",
-	"version": "0.0.0-20260727003132-g7dd9424",
+	"version": "0.0.0-20260729002615-g8a974c9",
 	"description": "Amp Plugin API",
 	"homepage": "https://ampcode.com/manual/plugin-api",
 	"author": {