@vellumai/plugin-api 0.11.2-dev.202608061450.508112 → 0.11.2-dev.202608062308.5442cf1

package/index.d.ts

@@ -515,6 +515,11 @@ declare const AssistantConfigSchema: z.ZodObject<{
             }, z.core.$strip>>;
         }, z.core.$strip>>;
         retrospective: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            forkStrategy: z.ZodDefault<z.ZodEnum<{
+                cloning: "cloning";
+                reference: "reference";
+            }>>;
             timeThresholdMs: z.ZodDefault<z.ZodNumber>;
             messageThreshold: z.ZodDefault<z.ZodNumber>;
             minCooldownMs: z.ZodDefault<z.ZodNumber>;
@@ -1101,6 +1106,7 @@ declare const AssistantConfigSchema: z.ZodObject<{
         botId: z.ZodDefault<z.ZodString>;
         botUsername: z.ZodDefault<z.ZodString>;
         apiBaseUrl: z.ZodDefault<z.ZodString>;
+        registeredWebhookUrl: z.ZodOptional<z.ZodString>;
         deliverAuthBypass: z.ZodDefault<z.ZodBoolean>;
         timeoutMs: z.ZodDefault<z.ZodNumber>;
         maxRetries: z.ZodDefault<z.ZodNumber>;
@@ -4168,6 +4174,8 @@ export declare interface ConversationRow {
     originInterface: string | null;
     forkParentConversationId: string | null;
     forkParentMessageId: string | null;
+    /** `"reference"` on referential forks; `"cloning"` or null on copied ones. */
+    forkStrategy: string | null;
     isAutoTitle: number;
     scheduleJobId: string | null;
     lastMessageAt: number | null;
@@ -4764,6 +4772,19 @@ declare interface LiveVoiceErrorServerFrame extends LiveVoiceServerFrameBase {
     readonly type: "error";
     readonly code: LiveVoiceProtocolErrorCode;
     readonly message: string;
+    /**
+     * The client frame this error is about, when the failure was a parse or
+     * validation failure of a specific frame. Absent otherwise, and absent from
+     * daemons predating the field.
+     *
+     * It exists so an `unknown_type` is attributable. A client that sends more
+     * than one optional frame (today: `update_config` and `attach_image`) gets
+     * the same code for either, and without this has to assume which one was
+     * refused. The wrong assumption is silent in both directions: settings stop
+     * applying for a session, or a photo the user watched themselves take is
+     * dropped with nothing said.
+     */
+    readonly frameType?: string;
     /**
      * True when the session continues past the error (e.g. a transient
      * transcriber blip or one failed TTS segment). Absent (including on frames
@@ -5931,6 +5952,20 @@ export declare function resolveMediaSourceData(source: MediaSource_2): {
  */
 export declare function resolveUserName(workspaceDir: string): string | null;
 
+/**
+ * Resolve the public URL a third party should deliver to for `path`.
+ *
+ * On the managed branches this registers a callback route with the platform,
+ * which is idempotent and matches what `assistant webhooks register` does.
+ *
+ * @throws when the plugin cannot be determined, when `path` is not one the
+ *   gateway would serve, or when no ingress is configured and the assistant is
+ *   not connected to the platform. That last case has no URL that would work,
+ *   and a plausible one would produce a vendor registration that silently
+ *   receives nothing.
+ */
+export declare function resolveWebhookUrl(options: WebhookUrlOptions): Promise<string>;
+
 export declare enum RiskLevel {
     Low = "low",
     Medium = "medium",
@@ -7300,6 +7335,38 @@ declare interface WebFetchMetadata {
 /** Provider that backed a `web_fetch` call. `default` is the built-in fetcher. */
 declare type WebFetchProviderId = "default" | "firecrawl";
 
+/**
+ * Public URL resolution for a plugin's own ingress route.
+ *
+ * A plugin that receives third-party webhooks has to tell the vendor where to
+ * deliver. Which URL is correct depends on how the assistant is reachable:
+ * a platform pod and a platform-connected assistant are served through a
+ * managed callback route, while a self-hosted deployment is served through its
+ * configured public ingress. `ingress.publicBaseUrl` alone does not decide it,
+ * because on a platform-connected assistant that value holds the Velay tunnel
+ * address, which is not where plugin routes are served.
+ *
+ * `resolveCallbackUrl` owns that decision for every caller in the codebase
+ * (`webhooks register`, the Telegram webhook manager). This exposes it to
+ * plugins so there is one implementation rather than one per plugin.
+ */
+export declare interface WebhookUrlOptions {
+    /**
+     * Route path within the plugin's namespace, such as `"events-photon"`.
+     * Relative, with no leading slash.
+     */
+    path: string;
+    /**
+     * Plugin whose namespace the route belongs to.
+     *
+     * Defaults to the plugin in context, which covers hooks and tools. Supply it
+     * explicitly from a plugin route handler, where no context is established.
+     */
+    plugin?: string;
+    /** Human-readable label for the platform's admin display. */
+    sourceIdentifier?: string;
+}
+
 declare interface WebSearchMetadata {
     query: string;
     provider: WebSearchProviderId;

package/index.js

@@ -45,6 +45,7 @@ export const removeDocument = api.removeDocument;
 export const resolveCredential = api.resolveCredential;
 export const resolveMediaSourceData = api.resolveMediaSourceData;
 export const resolveUserName = api.resolveUserName;
+export const resolveWebhookUrl = api.resolveWebhookUrl;
 export const runConversationTurn = api.runConversationTurn;
 export const searchMessageIdsLexical = api.searchMessageIdsLexical;
 export const selectedBackendSupportsMultimodal = api.selectedBackendSupportsMultimodal;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/plugin-api",
-  "version": "0.11.2-dev.202608061450.0508112",
+  "version": "0.11.2-dev.202608062308.5442cf1",
   "description": "Public TypeScript authoring contract for Vellum assistant plugins.",
   "license": "MIT",
   "type": "module",