@vellumai/plugin-api 0.10.5 → 0.10.6-dev.202607062043.72bc40b

package/index.d.ts

@@ -533,6 +533,30 @@ declare interface BaseAssistantEvent<TMessage = unknown> {
     message: TMessage;
 }
 
+/**
+ * Capabilities shared by every chain-hook context (`user-prompt-submit`,
+ * `post-compact`, `post-tool-use`, `stop`, `pre-model-call`,
+ * `post-model-call`).
+ *
+ * Both are stamped onto each hook's draft by the pipeline (`runHook`) before
+ * the hook runs, bound to that hook's identity — dispatching call sites
+ * construct the `XInputContext` shapes and never supply these.
+ */
+declare interface BaseHookContext {
+    /**
+     * Logger bound to the emitting hook — pre-tagged with the hook name and
+     * owning plugin (plus `conversationId` / `requestId` when the dispatching
+     * context carries them), so hook log lines are attributed without manual
+     * tagging.
+     */
+    readonly logger: PluginLogger;
+    /**
+     * Per-hook `hook_event` emitter, bound to this hook's owner — see
+     * {@link HookBroadcast}.
+     */
+    readonly broadcast: HookBroadcast;
+}
+
 declare interface BaseSubscriberEntry {
     filter: AssistantEventFilter;
     callback: AssistantEventCallback;
@@ -987,6 +1011,33 @@ declare interface ContextCompacted {
     summaryHadMemoryEcho?: boolean;
 }
 
+/**
+ * The full `conversation-deleted` context a hook receives — the dispatching
+ * call site's {@link ConversationDeletedInputContext} plus the
+ * pipeline-stamped {@link BaseHookContext} capabilities.
+ */
+export declare interface ConversationDeletedContext extends ConversationDeletedInputContext, BaseHookContext {
+}
+
+/**
+ * Context passed to the `conversation-deleted` hook. Fires once per deleted
+ * conversation — from the shared delete primitives, so every delete caller
+ * (route, retrospective cleanup, GC) dispatches it — after the conversation's
+ * rows are removed.
+ *
+ * The dispatch is fire-and-forget: the delete primitives are synchronous and
+ * do not wait for the chain, so hooks run concurrently with whatever the
+ * caller does after the delete and must not assume any ordering relative to
+ * it. By the time a hook runs, the conversation's rows (messages, segments,
+ * attachments, the conversation itself) are gone — a hook can only key its
+ * cleanup on the id. The default memory plugin contributes a hook here that
+ * fails its own still-pending background jobs referencing the conversation.
+ */
+declare interface ConversationDeletedInputContext {
+    /** ID of the conversation that was deleted. */
+    readonly conversationId: string;
+}
+
 declare type ConversationErrorEvent = z.infer<typeof ConversationErrorEventSchema>;
 
 declare const ConversationErrorEventSchema: z.ZodObject<{
@@ -1827,6 +1878,36 @@ declare const HomeFeedUpdatedEventSchema: z.ZodObject<{
 
 declare type _HomeServerMessages = RelationshipStateUpdatedEvent | HomeFeedUpdatedEvent;
 
+/**
+ * Emit a `hook_event` to any UI watching the conversation the hook runs in —
+ * e.g. progress while the hook does work the user can feel (memory
+ * selection). The daemon stamps the conversation, the hook name, and the
+ * emitting hook's owner; the hook supplies only `detail`, an arbitrary
+ * JSON-serializable record whose shape it and its client renderer agree on.
+ *
+ * Best-effort and fire-and-forget: it never blocks or fails the turn, and
+ * cannot emit any other event type or target another conversation — the emit
+ * surface is bound to the turn. Contexts without a `conversationId` emit an
+ * unscoped `hook_event`.
+ */
+export declare type HookBroadcast = (detail: Record<string, unknown>) => void;
+
+declare type HookEvent = z.infer<typeof HookEventSchema>;
+
+declare const HookEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"hook_event">;
+    conversationId: z.ZodOptional<z.ZodString>;
+    hookName: z.ZodString;
+    owner: z.ZodObject<{
+        kind: z.ZodEnum<{
+            plugin: "plugin";
+            workspace: "workspace";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strip>;
+    detail: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+
 /**
  * A plugin lifecycle hook. Receives a per-lifecycle context shape and may
  * either mutate `ctx` in place (returning `void`) or return a *partial*
@@ -1846,10 +1927,12 @@ declare type _HomeServerMessages = RelationshipStateUpdatedEvent | HomeFeedUpdat
  *   - `init` — {@link InitContext}
  *   - `shutdown` — {@link ShutdownContext}
  *   - `user-prompt-submit` — {@link UserPromptSubmitContext}
+ *   - `post-compact` — {@link PostCompactContext}
  *   - `pre-model-call` — {@link PreModelCallContext}
  *   - `post-tool-use` — {@link PostToolUseContext}
  *   - `stop` — {@link StopContext}
  *   - `post-model-call` — {@link PostModelCallContext}
+ *   - `conversation-deleted` — {@link ConversationDeletedContext}
  */
 export declare type HookFunction<TCtx = unknown> = (ctx: TCtx) => Promise<Partial<TCtx> | void>;
 
@@ -1887,6 +1970,8 @@ export declare const HOOKS: {
     readonly POST_MODEL_CALL: "post-model-call";
     /** Fires after the loop successfully compacts a conversation mid-turn. */
     readonly POST_COMPACT: "post-compact";
+    /** Fires once per deleted conversation, after its rows are removed. Fire-and-forget cleanup signal — hooks run async with no ordering guarantee relative to the caller. */
+    readonly CONVERSATION_DELETED: "conversation-deleted";
 };
 
 declare interface HostAppControlCancel {
@@ -2666,6 +2751,7 @@ declare const OpenPanelEventSchema: z.ZodObject<{
     panelType: z.ZodString;
     data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     conversationId: z.ZodOptional<z.ZodString>;
+    surfaceId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 
 declare type OpenUrlEvent = z.infer<typeof OpenUrlEventSchema>;
@@ -2739,6 +2825,14 @@ declare interface PongMessage {
     type: "pong";
 }
 
+/**
+ * The full `post-compact` context a hook receives — the dispatching call
+ * site's {@link PostCompactInputContext} plus the pipeline-stamped
+ * {@link BaseHookContext} capabilities.
+ */
+export declare interface PostCompactContext extends PostCompactInputContext, BaseHookContext {
+}
+
 /**
  * Context passed to the `post-compact` hook. Fires after the agent loop
  * compacts a conversation mid-turn — once the running history has been
@@ -2753,12 +2847,12 @@ declare interface PongMessage {
  * their own injected context the same way.
  *
  * The hook re-injects by mutating `history` in place (or returning a new
- * context with a replacement `history`) — see {@link HookFunction}'s
+ * context with a replacement `history`) — see `HookFunction`'s
  * polymorphic return shape. The agent loop reads the settled `history` back off
  * the context and resumes the turn from it. Multiple plugins' hooks chain in
  * registration order, each seeing the previous plugin's edits.
  */
-export declare interface PostCompactContext {
+declare interface PostCompactInputContext {
     /**
      * The compacted message history to re-inject onto. Hooks mutate this in
      * place (or return a new context with a replacement) to re-apply context
@@ -2797,6 +2891,28 @@ export declare interface PostCompactContext {
     readonly injectionMode?: "full" | "minimal";
 }
 
+/**
+ * The full `post-model-call` context a hook receives — the dispatching call
+ * site's {@link PostModelCallInputContext} plus the pipeline-stamped
+ * {@link BaseHookContext} capabilities.
+ */
+export declare interface PostModelCallContext extends PostModelCallInputContext, BaseHookContext {
+}
+
+/**
+ * Binary outcome of the `post-model-call` hook. The agent loop seeds it to
+ * `"stop"` and acts on the value the chain settles on:
+ *
+ * - `"stop"`     — accept the model-call outcome. On a finalized reply the loop
+ *                  keeps the (possibly transformed) message; on a rejection it
+ *                  surfaces the error. This is the default.
+ * - `"continue"` — re-query the model. The hook is responsible for leaving
+ *                  {@link PostModelCallContext.messages} as the history the next
+ *                  iteration should send (append a follow-up turn, or replace
+ *                  the array with a repaired one).
+ */
+export declare type PostModelCallDecision = "continue" | "stop";
+
 /**
  * Context passed to the `post-model-call` hook. Fires at every model-call
  * outcome — the seam where the loop reacts to what the provider returned:
@@ -2828,7 +2944,7 @@ export declare interface PostCompactContext {
  * the outcome is treated as `"stop"`). Multiple plugins' hooks chain in
  * registration order — each sees the previous hook's `decision` and mutations.
  */
-export declare interface PostModelCallContext {
+declare interface PostModelCallInputContext {
     /** Conversation ID the message belongs to. */
     readonly conversationId: string;
     /** The call site this message serves — `"mainAgent"` for the user-facing reply; `null` when untagged. */
@@ -2871,23 +2987,15 @@ export declare interface PostModelCallContext {
      * actionable outcomes (see the interface docstring).
      */
     decision: PostModelCallDecision;
-    /** Logger scoped to the current turn (tag structured fields with `{ plugin }`). */
-    readonly logger: PluginLogger;
 }
 
 /**
- * Binary outcome of the `post-model-call` hook. The agent loop seeds it to
- * `"stop"` and acts on the value the chain settles on:
- *
- * - `"stop"`     — accept the model-call outcome. On a finalized reply the loop
- *                  keeps the (possibly transformed) message; on a rejection it
- *                  surfaces the error. This is the default.
- * - `"continue"` — re-query the model. The hook is responsible for leaving
- *                  {@link PostModelCallContext.messages} as the history the next
- *                  iteration should send (append a follow-up turn, or replace
- *                  the array with a repaired one).
+ * The full `post-tool-use` context a hook receives — the dispatching call
+ * site's {@link PostToolUseInputContext} plus the pipeline-stamped
+ * {@link BaseHookContext} capabilities.
  */
-export declare type PostModelCallDecision = "continue" | "stop";
+export declare interface PostToolUseContext extends PostToolUseInputContext, BaseHookContext {
+}
 
 /**
  * Context passed to the `post-tool-use` hook. Fires once per tool result —
@@ -2897,7 +3005,7 @@ export declare type PostModelCallDecision = "continue" | "stop";
  *
  * The hook may transform the result either by mutating `toolResponse` in
  * place (e.g. reassigning `toolResponse.content`) or by returning a new
- * context with a fresh `toolResponse` — see {@link HookFunction}'s
+ * context with a fresh `toolResponse` — see `HookFunction`'s
  * polymorphic return shape. The daemon threads the final `toolResponse`
  * into the provider-bound history.
  *
@@ -2909,7 +3017,7 @@ export declare type PostModelCallDecision = "continue" | "stop";
  * can swap in a smarter strategy (e.g. a summarizer) or observe results for
  * side effects.
  */
-export declare interface PostToolUseContext {
+declare interface PostToolUseInputContext {
     /** Conversation ID the tool ran on. */
     readonly conversationId: string;
     /**
@@ -2969,12 +3077,14 @@ export declare interface PostToolUseContext {
      * receiving a precomputed limit.
      */
     readonly maxInputTokens: number;
-    /**
-     * Logger scoped to the current turn. The same instance is shared by
-     * every hook in the chain, so plugins should tag their structured log
-     * fields (e.g. `{ plugin: "<name>" }`) for attribution.
-     */
-    readonly logger: PluginLogger;
+}
+
+/**
+ * The full `pre-model-call` context a hook receives — the dispatching call
+ * site's {@link PreModelCallInputContext} plus the pipeline-stamped
+ * {@link BaseHookContext} capabilities.
+ */
+export declare interface PreModelCallContext extends PreModelCallInputContext, BaseHookContext {
 }
 
 /**
@@ -2990,7 +3100,7 @@ export declare interface PostToolUseContext {
  * Mutate the context in place or return a new one; throwing is contained by the
  * loop (the call proceeds with the original request).
  */
-export declare interface PreModelCallContext {
+declare interface PreModelCallInputContext {
     /** Conversation ID the call belongs to. */
     readonly conversationId: string;
     /**
@@ -3029,8 +3139,6 @@ export declare interface PreModelCallContext {
      * redaction that needs the full message — instead of leaking the raw stream.
      */
     deferAssistantOutput: boolean;
-    /** Logger scoped to the current turn (tag structured fields with `{ plugin }`). */
-    readonly logger: PluginLogger;
 }
 
 declare interface ProcessEntry extends BaseSubscriberEntry {
@@ -3334,6 +3442,14 @@ declare interface SecretPromptResult {
     delivery: SecretDelivery;
     /** When set, the prompt could not be delivered and the value is null due to a delivery failure (not user cancellation). */
     error?: "unsupported_channel";
+    /**
+     * Why `value` is null. `"cancelled"` = the user explicitly dismissed the
+     * prompt (a valid flow, not a failure); `"timed_out"` = no response within
+     * the permission-timeout window. Only meaningful when `value` is null and
+     * `error` is unset. Lets callers distinguish a deliberate cancel from a
+     * genuine failure instead of treating both as an error.
+     */
+    reason?: "cancelled" | "timed_out";
 }
 
 declare type SecretRequestEvent = z.infer<typeof SecretRequestEventSchema>;
@@ -3451,7 +3567,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 | _MemoryServerMessages | _WorkspaceServerMessages | _SchedulesServerMessages | _SettingsServerMessages | _DiagnosticsServerMessages | _InboxServerMessages | _NotificationsServerMessages | _UpgradesServerMessages | _AcpServerMessages | _BackgroundToolsServerMessages | _BookmarksServerMessages | _WorkflowsServerMessages | 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 | _MemoryServerMessages | _WorkspaceServerMessages | _SchedulesServerMessages | _SettingsServerMessages | _DiagnosticsServerMessages | _InboxServerMessages | _NotificationsServerMessages | _UpgradesServerMessages | _AcpServerMessages | _BackgroundToolsServerMessages | _BookmarksServerMessages | _WorkflowsServerMessages | DiskPressureStatusChangedEvent | HookEvent | SubagentEvent;
 
 export declare interface ServerToolUseContent {
     type: "server_tool_use";
@@ -3551,8 +3667,11 @@ export declare interface ShutdownContext {
  * - `uninstall` — the plugin's directory was removed at runtime.
  * - `disable` — the plugin was disabled at runtime (e.g. a `.disabled`
  *   sentinel was added, or a feature flag turned it off).
+ * - `reload` — a source file inside the plugin directory changed and the
+ *   plugin is being redeployed in place; the old version's `shutdown` runs
+ *   before the new version is imported and its `init` fires.
  */
-declare type ShutdownReason = "shutdown" | "uninstall" | "disable";
+declare type ShutdownReason = "shutdown" | "uninstall" | "disable" | "reload";
 
 declare interface SignBundlePayloadRequest {
     type: "sign_bundle_payload";
@@ -3672,6 +3791,14 @@ declare interface SoundsConfigUpdated {
     type: "sounds_config_updated";
 }
 
+/**
+ * The full `stop` context a hook receives — the dispatching call site's
+ * {@link StopInputContext} plus the pipeline-stamped {@link BaseHookContext}
+ * capabilities.
+ */
+export declare interface StopContext extends StopInputContext, BaseHookContext {
+}
+
 /**
  * Context passed to the `stop` hook — the loop's definitive terminal hook.
  *
@@ -3692,7 +3819,7 @@ declare interface SoundsConfigUpdated {
  *
  * Multiple plugins' hooks chain in registration order over the same context.
  */
-export declare interface StopContext {
+declare interface StopInputContext {
     /** Conversation ID the run belongs to. */
     readonly conversationId: string;
     /**
@@ -3715,12 +3842,6 @@ export declare interface StopContext {
      * control transfer that re-enters the loop and so never reaches this hook.
      */
     readonly exitReason: AgentLoopExitReason;
-    /**
-     * Logger scoped to the current turn. The same instance is shared by
-     * every hook in the chain, so plugins should tag their structured log
-     * fields (e.g. `{ plugin: "<name>" }`) for attribution.
-     */
-    readonly logger: PluginLogger;
 }
 
 declare interface SubagentDetailResponse {
@@ -3943,6 +4064,13 @@ export declare interface ToolContext {
      * @legacy
      */
     allowedToolNames?: Set<string>;
+    /**
+     * When the conversation runs as a subagent, the parent-imposed tool
+     * allowlist (see `SubagentRoleConfig.allowedTools`). Carried so
+     * availability errors can name the allowlist as the gate instead of
+     * suggesting a skill load that cannot widen it.
+     */
+    subagentAllowedTools?: ReadonlySet<string>;
     /**
      * True when this turn is restricted to storage cleanup-safe tools.
      * @legacy
@@ -4827,6 +4955,14 @@ declare const UserMessageEchoEventSchema: z.ZodObject<{
     clientMessageId: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 
+/**
+ * The full `user-prompt-submit` context a hook receives — the dispatching
+ * call site's {@link UserPromptSubmitInputContext} plus the pipeline-stamped
+ * {@link BaseHookContext} capabilities.
+ */
+export declare interface UserPromptSubmitContext extends UserPromptSubmitInputContext, BaseHookContext {
+}
+
 /**
  * Context passed to the `user-prompt-submit` hook. Fires once per user
  * turn, after the agent loop has prepared the message list (PKB / NOW /
@@ -4836,7 +4972,7 @@ declare const UserMessageEchoEventSchema: z.ZodObject<{
  *
  * The hook may transform `latestMessages` either by mutating it in place
  * (`push` / `splice` / `length = 0`) or by returning a new context with
- * a fresh `latestMessages` array — see {@link HookFunction}'s polymorphic
+ * a fresh `latestMessages` array — see `HookFunction`'s polymorphic
  * return shape. The daemon threads the final `latestMessages` value into
  * `agentLoop.run()` as the run-messages argument.
  *
@@ -4849,7 +4985,7 @@ declare const UserMessageEchoEventSchema: z.ZodObject<{
  * hook sees the previous plugin's mutations (whether by reassignment or
  * in-place mutation).
  */
-export declare interface UserPromptSubmitContext {
+declare interface UserPromptSubmitInputContext {
     /** Conversation ID the user prompt was submitted on. */
     readonly conversationId: string;
     /**
@@ -4857,6 +4993,14 @@ export declare interface UserPromptSubmitContext {
      * attach turn-scoped metadata to the originating message (e.g. recording an
      * injected memory block so it survives a conversation reload) key off this
      * row id rather than the in-memory message arrays, whose entries carry no id.
+     *
+     * @deprecated This field is always identical to {@link requestId}; use
+     *   `requestId` instead. Every path that starts an agent loop persists the
+     *   triggering user message under the turn's request ID before running, so
+     *   the message row id and the request's correlation ID are the same UUID.
+     *   This holds for the standard submit, queue-drain, subagent, voice, wake,
+     *   and conversation-analysis paths alike. This field will be removed in a
+     *   future API version.
      */
     readonly userMessageId: string;
     /**
@@ -4864,6 +5008,10 @@ export declare interface UserPromptSubmitContext {
      * runtime injection forward it onto the injector turn context so the
      * assembled blocks are attributed to the originating request; it is fixed
      * for the turn and cannot be recovered from the message arrays.
+     *
+     * As of the requestId/userMessageId merge, this value is also the
+     * persisted row ID of the user message, so hooks that previously
+     * keyed off {@link userMessageId} can use `requestId` directly.
      */
     readonly requestId: string;
     /**
@@ -4911,12 +5059,6 @@ export declare interface UserPromptSubmitContext {
      * may mutate this in place or replace it by returning a new context.
      */
     latestMessages: Message[];
-    /**
-     * Logger scoped to the current turn. The same instance is shared by
-     * every hook in the chain, so plugins should tag their structured log
-     * fields (e.g. `{ plugin: "<name>" }`) for attribution.
-     */
-    readonly logger: PluginLogger;
 }
 
 declare interface VellumSlimSkill extends SlimSkillBase {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/plugin-api",
-  "version": "0.10.5",
+  "version": "0.10.6-dev.202607062043.72bc40b",
   "description": "Public TypeScript authoring contract for Vellum assistant plugins.",
   "license": "MIT",
   "type": "module",