@ampcode/plugin 0.0.0-20260726003151-g56c26ca → 0.0.0-20260728002927-g60f34f5

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,34 @@ 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, when a modified plugin
+		 * is reloaded (the old instance's callbacks complete before the new instance
+		 * is activated), 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.
 		 *
@@ -136,6 +164,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.
 		 *
@@ -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.
 	 */
@@ -934,7 +1017,9 @@ declare module '@ampcode/plugin' {
 		 */
 		waitForResponse(options?: { timeoutMs?: number }): Promise<ThreadAssistantMessage>
 
-		/** Stop the agent's current turn in this thread, if one is running. */
+		/**
+		 * Stop the agent's current turn. During agent.start, prevents the turn from starting.
+		 */
 		cancel(): Promise<void>
 
 		/**
@@ -1011,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") */
@@ -1031,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 */
@@ -1167,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-20260726003151-g56c26ca",
+	"version": "0.0.0-20260728002927-g60f34f5",
 	"description": "Amp Plugin API",
 	"homepage": "https://ampcode.com/manual/plugin-api",
 	"author": {