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

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>;
 
@@ -919,9 +920,9 @@ declare interface ContextCompacted {
      * - `summaryCharCount`: length of the produced summary text.
      * - `summaryHeaderCount`: number of `## ` section headers in the summary.
      * - `summaryHadMemoryEcho`: `true` if the summary contains any runtime
-     *   injection tag (e.g. `<memory`, `<turn_context>`, `<workspace>`).
-     *   Should always be `false` — `true` indicates the compaction strip
-     *   logic failed to remove an injected block from the summarizer input.
+     *   injection tag (e.g. `<memory`, `<turn_context>`, `<workspace>`). The
+     *   durable summary should be clean prose, so `true` flags an echoed or
+     *   invented tag worth investigating.
      */
     summaryCharCount?: number;
     summaryHeaderCount?: number;
@@ -1728,7 +1729,7 @@ export declare const HOOKS: {
     readonly SHUTDOWN: "shutdown";
     /** Fires once per user turn, immediately before the agent loop receives `runMessages`. */
     readonly USER_PROMPT_SUBMIT: "user-prompt-submit";
-    /** Fires immediately before each provider call. A hook may edit the outbound request (e.g. the system prompt) and opt the turn into deferred output streaming. */
+    /** Fires immediately before each provider call. A hook may edit the outbound request (e.g. the system prompt), route the call to a different inference profile, and opt the turn into deferred output streaming. */
     readonly PRE_MODEL_CALL: "pre-model-call";
     /** Fires once per tool result, after the tool returns and before the result is sent to the provider. */
     readonly POST_TOOL_USE: "post-tool-use";
@@ -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[];
     /**
@@ -2915,8 +2929,9 @@ export declare interface PostToolUseContext {
  * and compaction work can share a conversation), hooks MUST self-gate on
  * {@link callSite} / {@link conversationId} before acting.
  *
- * A hook may edit the outbound request by replacing {@link systemPrompt}, and may
- * opt this turn into deferred output streaming via {@link deferAssistantOutput}.
+ * A hook may edit the outbound request by replacing {@link systemPrompt}, route
+ * the call to a different inference profile via {@link modelProfile}, and opt
+ * this turn into deferred output streaming via {@link deferAssistantOutput}.
  * Mutate the context in place or return a new one; throwing is contained by the
  * loop (the call proceeds with the original request).
  */
@@ -2933,6 +2948,24 @@ export declare interface PreModelCallContext {
      * append a section); the loop sends the resulting value.
      */
     systemPrompt: string | null;
+    /**
+     * Inference profile to route THIS provider call to, named by its key in the
+     * workspace `llm.profiles`. Seeded with the call's already-resolved override
+     * profile, or `null` when none applies. A hook may replace it to select a
+     * different profile per call — the lever a model router uses to map a
+     * classified message onto a profile (model + provider connection + sampling
+     * settings). For the user-facing `mainAgent` call the resolver layers the
+     * named profile at the top of precedence (above the workspace active
+     * profile), so the hook's choice wins; a key with no matching profile falls
+     * through unchanged (no throw). Honored only when {@link callSite} is set.
+     * Set to `null` to apply no override.
+     *
+     * Context-window sizing and overflow recovery for this call are computed from
+     * the profile resolved before the hook runs. Routing a near-budget
+     * conversation to a profile with a smaller context window relies on the loop's
+     * overflow recovery (compact and retry) rather than proactive compaction.
+     */
+    modelProfile: string | null;
     /**
      * Seeded `false`. When a hook sets it `true`, the loop suppresses this turn's
      * live assistant `text_delta` stream; a `post-model-call` hook is then
@@ -3162,7 +3195,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 +4382,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 +4565,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-staging.2",
+  "version": "0.9.0-dev.202606162156.4bad3e5",
   "description": "Public TypeScript authoring contract for Vellum assistant plugins.",
   "license": "MIT",
   "type": "module",