@vellumai/plugin-api 0.10.9-staging.1 → 0.10.9-staging.2

package/index.d.ts

@@ -245,15 +245,15 @@ declare const AssistantActivityStateEventSchema: z.ZodObject<{
     reason: z.ZodEnum<{
         thinking_delta: "thinking_delta";
         generation_cancelled: "generation_cancelled";
+        tool_use_start: "tool_use_start";
+        message_complete: "message_complete";
         message_dequeued: "message_dequeued";
         first_text_delta: "first_text_delta";
-        tool_use_start: "tool_use_start";
         preview_start: "preview_start";
         tool_result_received: "tool_result_received";
         confirmation_requested: "confirmation_requested";
         confirmation_resolved: "confirmation_resolved";
         context_compacting: "context_compacting";
-        message_complete: "message_complete";
         error_terminal: "error_terminal";
     }>;
     requestId: z.ZodOptional<z.ZodString>;
@@ -4910,6 +4910,63 @@ export declare enum RiskLevel {
  */
 declare type RiskLevel_2 = "safe" | "low" | "medium" | "high" | "critical" | "unknown";
 
+/**
+ * Run a full conversation agent-loop turn: persist the user message, execute
+ * the agent loop (history, tools, compaction, injections), and return the
+ * assistant's full content-block response.
+ *
+ * When `conversationId` is omitted, a new conversation is created and its ID
+ * is returned in the result.
+ *
+ * Events are fanned out to SSE/event-hub subscribers via `broadcastMessage`
+ * (the same path the daemon's HTTP message route uses) while also being
+ * collected internally so the caller receives the final response content.
+ * For streaming use cases, subscribe to the conversation's events via the
+ * host event hub (`assistantEventHub`).
+ *
+ * If the conversation is currently processing another turn, the message is
+ * queued via `enqueueMessage` and the result carries `queued: true` with
+ * empty content -- the queued turn will execute automatically when the
+ * current turn finishes.
+ */
+export declare function runConversationTurn(options: RunConversationTurnOptions): Promise<RunConversationTurnResult>;
+
+export declare interface RunConversationTurnOptions {
+    /**
+     * Conversation to run the turn in. If omitted, a new conversation is
+     * created (its ID is generated with `uuidv7` and returned in the result).
+     */
+    conversationId?: string;
+    /**
+     * User message content blocks for this turn. Text blocks become the
+     * user message body; image/file blocks are resolved to inline
+     * attachments. Other block types (tool_use, tool_result, thinking) are
+     * ignored as they are not valid user input.
+     */
+    content: ContentBlock[];
+    /**
+     * LLM call-site for inference profile resolution. Defaults to
+     * `"mainAgent"` inside the agent loop when omitted.
+     */
+    callSite?: LLMCallSite;
+    /**
+     * Abort signal. When aborted, the conversation's internal abort
+     * controller fires, terminating the in-flight agent loop.
+     */
+    signal?: AbortSignal;
+}
+
+export declare interface RunConversationTurnResult {
+    /** The assistant's full content blocks for this turn (text, tool_use, etc.). */
+    content: ContentBlock[];
+    /** The user message row ID assigned by the persistence layer. */
+    userMessageId: string;
+    /** The conversation this turn ran in. */
+    conversationId: string;
+    /** True when the message was queued because the conversation was busy. */
+    queued?: boolean;
+}
+
 /**
  * Emitted when the compaction circuit breaker trips. After three consecutive
  * summary-LLM failures (with local fallback covering each), auto-compaction is

package/index.js

@@ -26,6 +26,7 @@ export const listInstalledSkills = api.listInstalledSkills;
 export const parseMessageMetadata = api.parseMessageMetadata;
 export const resolveMediaSourceData = api.resolveMediaSourceData;
 export const resolveUserName = api.resolveUserName;
+export const runConversationTurn = api.runConversationTurn;
 export const searchMessageIdsLexical = api.searchMessageIdsLexical;
 export const selectedBackendSupportsMultimodal = api.selectedBackendSupportsMultimodal;
 export const stringifyMessageContent = api.stringifyMessageContent;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/plugin-api",
-  "version": "0.10.9-staging.1",
+  "version": "0.10.9-staging.2",
   "description": "Public TypeScript authoring contract for Vellum assistant plugins.",
   "license": "MIT",
   "type": "module",