@ampcode/plugin 0.0.0-20260717002806-g76909f1 → 0.0.0-20260719002729-g9e7d25b

package/index.d.ts

@@ -108,6 +108,31 @@ declare module '@ampcode/plugin' {
 		 */
 		registerTool(definition: PluginToolDefinition): Subscription
 
+		/**
+		 * Register a durable generic webhook for this plugin and the owning Orb thread.
+		 *
+		 * The key is stable within the plugin and thread. Re-registering the same key,
+		 * including after a plugin reload, returns the same capability URL. Treat the
+		 * URL as a credential.
+		 *
+		 * Handler side effects are delivered at least once. Use `event.id` as an
+		 * idempotency key because an executor can stop after the handler succeeds but
+		 * 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({
+		 *   key: 'deploy',
+		 *   handler: async (event, ctx) => {
+		 *     ctx.logger.log('Deployment received', event.id, event.payload)
+		 *   },
+		 * })
+		 * ```
+		 */
+		createWebhook(options: CreateWebhookOptions): Promise<WebhookRegistration>
+
 		/** AI helpers */
 		ai: PluginAI
 
@@ -452,7 +477,7 @@ declare module '@ampcode/plugin' {
 		| 'vertexai'
 		| 'xai'
 
-	/** Model identifier in `provider/model` format, such as `openai/gpt-5.5`. */
+	/** Model identifier in `provider/model` format, such as `openai/gpt-5.6-sol`. */
 	export type PluginAIModel = `${PluginAIModelProvider}/${string}`
 
 	export type PluginAIFieldSchema = {
@@ -1416,6 +1441,45 @@ declare module '@ampcode/plugin' {
 		thread: PluginThread
 	}
 
+	/** A provider-neutral webhook event delivered to a plugin handler. */
+	export interface WebhookEvent {
+		/** Stable server-owned event ID. Use this to make handler effects idempotent. */
+		id: string
+
+		/** JSON-compatible request payload accepted by the generic webhook endpoint. */
+		payload: unknown
+
+		/** Bounded string metadata recorded by the webhook ingress. */
+		metadata: Readonly<Record<string, string>>
+
+		/** ISO 8601 timestamp recorded when the server accepted the webhook. */
+		receivedAt: string
+	}
+
+	/** Context passed to webhook handlers for the owning thread. */
+	export interface WebhookHandlerContext extends PluginEventContextBase {
+		/** Thread that owns this webhook registration. */
+		thread: PluginThread
+
+		/** Aborted when the handler's execution deadline elapses. */
+		signal: AbortSignal
+	}
+
+	/** Options for registering a generic webhook handler. */
+	export interface CreateWebhookOptions {
+		/** Stable, non-whitespace-padded key within this plugin and thread (1-128 characters). */
+		key: string
+
+		/** At-least-once handler for matching durable webhook events. */
+		handler: (event: WebhookEvent, ctx: WebhookHandlerContext) => void | Promise<void>
+	}
+
+	/** Safe registration information returned to the plugin. */
+	export interface WebhookRegistration {
+		/** Capability URL for webhook POST requests. Treat this URL as a credential. */
+		url: string
+	}
+
 	/**
 	 * Options for registering a tool that the agent can call.
 	 */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ampcode/plugin",
-	"version": "0.0.0-20260717002806-g76909f1",
+	"version": "0.0.0-20260719002729-g9e7d25b",
 	"description": "Amp Plugin API",
 	"homepage": "https://ampcode.com/manual/plugin-api",
 	"author": {