@vellumai/plugin-api 0.8.12 → 0.9.0-staging.2

package/index.d.ts

@@ -463,14 +463,15 @@ declare const AssistantTextDeltaEventSchema: z.ZodObject<{
     conversationId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 
-declare interface AssistantThinkingDelta {
-    type: "assistant_thinking_delta";
-    thinking: string;
-    conversationId?: string;
-    /** Database ID of the assistant message this thinking delta belongs to.
-     *  Same semantics as `AssistantTextDeltaEvent.messageId`. */
-    messageId?: string;
-}
+declare type AssistantThinkingDeltaEvent = z.infer<typeof AssistantThinkingDeltaEventSchema>;
+
+declare const AssistantThinkingDeltaEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"assistant_thinking_delta">;
+    thinking: z.ZodString;
+    messageId: z.ZodOptional<z.ZodString>;
+    conversationId: z.ZodOptional<z.ZodString>;
+    timestampMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
 
 declare type AssistantTurnStartEvent = z.infer<typeof AssistantTurnStartEventSchema>;
 
@@ -2162,6 +2163,7 @@ declare const LLMCallSiteEnum: z.ZodEnum<{
     trustRuleSuggestion: "trustRuleSuggestion";
     homeGreeting: "homeGreeting";
     homeSuggestedPrompts: "homeSuggestedPrompts";
+    workflowLeaf: "workflowLeaf";
 }>;
 
 /**
@@ -2420,7 +2422,7 @@ declare const MessageRequestCompleteEventSchema: z.ZodObject<{
     runStillActive: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 
-declare type _MessagesServerMessages = UserMessageEchoEvent | AssistantTurnStartEvent | AssistantTextDeltaEvent | AssistantThinkingDelta | ToolUseStartEvent | ToolUsePreviewStartEvent | ToolOutputChunkEvent | ToolInputDelta | ToolResultEvent | ConfirmationRequestEvent | SecretRequestEvent | QuestionRequestEvent | MessageCompleteEvent | ErrorEvent_2 | MessageQueuedEvent | MessageDequeuedEvent | MessageRequestCompleteEvent | MessageQueuedDeletedEvent | MessageSteered | SuggestionResponse | TraceEvent | ConfirmationStateChanged | AssistantActivityStateEvent | TurnProfileAutoRoutedEvent | ConversationInferenceProfileUpdated | InteractionResolvedEvent;
+declare type _MessagesServerMessages = UserMessageEchoEvent | AssistantTurnStartEvent | AssistantTextDeltaEvent | AssistantThinkingDeltaEvent | ToolUseStartEvent | ToolUsePreviewStartEvent | ToolOutputChunkEvent | ToolInputDelta | ToolResultEvent | ConfirmationRequestEvent | SecretRequestEvent | QuestionRequestEvent | MessageCompleteEvent | ErrorEvent_2 | MessageQueuedEvent | MessageDequeuedEvent | MessageRequestCompleteEvent | MessageQueuedDeletedEvent | MessageSteered | SuggestionResponse | TraceEvent | ConfirmationStateChanged | AssistantActivityStateEvent | TurnProfileAutoRoutedEvent | ConversationInferenceProfileUpdated | InteractionResolvedEvent;
 
 declare interface MessageSteered {
     type: "message_steered";
@@ -2768,8 +2770,11 @@ export declare interface PostCompactContext {
  *   the hook's result as the persisted and streamed message), and
  *   {@link stopReason} carries the provider's stop reason. Fires once per model
  *   call, including tool-bearing turns (a reply can carry both text and
- *   `tool_use`), so a hook should transform only the blocks it owns and leave
- *   others — notably `tool_use` — intact.
+ *   `tool_use`). A hook should leave blocks it does not own untouched, but it
+ *   may **append a `tool_use` block** to invoke a tool as if the model had
+ *   called it — the loop executes whatever the finalized content carries (see
+ *   {@link content}). This is the supported way for a plugin to drive a tool
+ *   (e.g. render a surface via `ui_show`) deterministically after a turn.
  * - **Provider rejection.** The call threw before any reply existed.
  *   {@link error} holds the rejection, {@link content} is empty, and
  *   {@link stopReason} is `null`. A hook that recognizes the rejection may
@@ -2793,8 +2798,17 @@ export declare interface PostModelCallContext {
     /** The call site this message serves — `"mainAgent"` for the user-facing reply; `null` when untagged. */
     readonly callSite: LLMCallSite | null;
     /**
-     * The finalized message content. Mutable — transform the text blocks and leave
-     * `tool_use` (and other non-text blocks) intact. Empty on a provider rejection.
+     * The finalized message content. Mutable, and the source of truth for both
+     * persistence and execution: the loop derives the turn's executable tool
+     * calls from this array *after* the hook chain runs. A hook may transform the
+     * text blocks, **append a `tool_use` block** to invoke a tool as if the model
+     * had called it (executed through the normal tool path — trust rules apply,
+     * and its result/surface is appended after any already-streamed text without
+     * discarding it), or drop a `tool_use` block to suppress a call. The host
+     * assigns an id to any appended `tool_use` block whose `id` is empty or
+     * collides. Empty on a provider rejection. Appended `tool_use` blocks are
+     * dropped on a truncated (max-tokens) turn, which short-circuits before the
+     * executor runs and so cannot pair a tool call with a result.
      */
     content: ContentBlock[];
     /**
@@ -3162,7 +3176,7 @@ declare interface SensitiveOutputBinding {
 
 declare type SensitiveOutputKind = "invite_code";
 
-declare type ServerMessage = _ConversationsServerMessages | _MessagesServerMessages | _SurfacesServerMessages | _SkillsServerMessages | _AppsServerMessages | _IntegrationsServerMessages | _ComputerUseServerMessages | _ContactsServerMessages | _WorkItemsServerMessages | _SubagentsServerMessages | _DocumentsServerMessages | _DocumentCommentsServerMessages | _GuardianActionsServerMessages | _SyncInvalidationServerMessages | _HomeServerMessages | _HostAppControlServerMessages | _HostBashServerMessages | _HostBrowserServerMessages | _HostCuServerMessages | _HostFileServerMessages | _HostTransferServerMessages | _MeetServerMessages | _MemoryServerMessages | _WorkspaceServerMessages | _SchedulesServerMessages | _SettingsServerMessages | _DiagnosticsServerMessages | _InboxServerMessages | _NotificationsServerMessages | _UpgradesServerMessages | _AcpServerMessages | _BookmarksServerMessages | DiskPressureStatusChangedEvent | SubagentEvent;
+declare type ServerMessage = _ConversationsServerMessages | _MessagesServerMessages | _SurfacesServerMessages | _SkillsServerMessages | _AppsServerMessages | _IntegrationsServerMessages | _ComputerUseServerMessages | _ContactsServerMessages | _WorkItemsServerMessages | _SubagentsServerMessages | _DocumentsServerMessages | _DocumentCommentsServerMessages | _GuardianActionsServerMessages | _SyncInvalidationServerMessages | _HomeServerMessages | _HostAppControlServerMessages | _HostBashServerMessages | _HostBrowserServerMessages | _HostCuServerMessages | _HostFileServerMessages | _HostTransferServerMessages | _MeetServerMessages | _MemoryServerMessages | _WorkspaceServerMessages | _SchedulesServerMessages | _SettingsServerMessages | _DiagnosticsServerMessages | _InboxServerMessages | _NotificationsServerMessages | _UpgradesServerMessages | _AcpServerMessages | _BookmarksServerMessages | _WorkflowsServerMessages | DiskPressureStatusChangedEvent | SubagentEvent;
 
 export declare interface ServerToolUseContent {
     type: "server_tool_use";
@@ -4349,6 +4363,8 @@ declare const UsageUpdateEventSchema: z.ZodObject<{
     conversationId: z.ZodString;
     inputTokens: z.ZodNumber;
     outputTokens: z.ZodNumber;
+    cacheCreationInputTokens: z.ZodOptional<z.ZodNumber>;
+    cacheReadInputTokens: z.ZodOptional<z.ZodNumber>;
     totalInputTokens: z.ZodNumber;
     totalOutputTokens: z.ZodNumber;
     estimatedCost: z.ZodNumber;
@@ -4530,6 +4546,60 @@ export declare interface WebSearchToolResultContent {
     content: unknown;
 }
 
+/**
+ * Terminal push for a workflow run. Carries the final status, counts, token
+ * usage, and a human-readable result/error summary the originating
+ * conversation also receives via an agent wake.
+ */
+declare interface WorkflowCompleted {
+    type: "workflow_completed";
+    runId: string;
+    status: WorkflowRunStatus;
+    agentsSpawned: number;
+    inputTokens: number;
+    outputTokens: number;
+    /** Human-readable result-or-error summary. */
+    summary?: string;
+}
+
+/**
+ * Progress push for an in-flight workflow run. Maps the engine's
+ * `onProgress` (`phase`/`log`) callback plus the current usage snapshot into a
+ * single wire event. `phase` carries the latest `phase(title)`; `message`
+ * carries the latest `log(msg)`; only one is set per emission.
+ */
+declare interface WorkflowProgress {
+    type: "workflow_progress";
+    runId: string;
+    /** Latest phase title, when this emission came from a `phase(...)` call. */
+    phase?: string;
+    /** Run label (the workflow's `meta.name`), for client display. */
+    label?: string;
+    /** Live agent count at emission time. */
+    agentsSpawned: number;
+    /** Latest log line, when this emission came from a `log(...)` call. */
+    message?: string;
+}
+
+/**
+ * Typed persistence for the workflow orchestration engine.
+ *
+ * Two tables (created by migration 282):
+ *
+ * - `workflow_runs` — one row per orchestration run (a sandboxed script that
+ *   spawns parallel leaf agents), tracking lifecycle status and token usage.
+ * - `workflow_journal` — append-only `(run_id, seq)` log of every leaf call
+ *   (agent / host function / nested workflow). On resume after a daemon
+ *   restart, the engine replays cached results for the unchanged call prefix
+ *   instead of re-spawning agents.
+ *
+ * This module is pure persistence — no `workflows` feature-flag logic. Callers
+ * (the engine, a later PR) own gating.
+ */
+declare type WorkflowRunStatus = "running" | "completed" | "failed" | "aborted" | "cap_exceeded" | "interrupted";
+
+declare type _WorkflowsServerMessages = WorkflowProgress | WorkflowCompleted;
+
 declare interface WorkItemApprovePermissionsResponse {
     type: "work_item_approve_permissions_response";
     id: string;

package/package.json

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