@vellumai/plugin-api 0.10.5-dev.202607042025.8a04d0b → 0.10.5-staging.2

package/index.d.ts

@@ -533,30 +533,6 @@ 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;
@@ -1851,36 +1827,6 @@ 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*
@@ -1900,7 +1846,6 @@ declare const HookEventSchema: z.ZodObject<{
  *   - `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}
@@ -2721,7 +2666,6 @@ 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>;
@@ -2795,14 +2739,6 @@ 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
@@ -2817,12 +2753,12 @@ export declare interface PostCompactContext extends PostCompactInputContext, Bas
  * 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 `HookFunction`'s
+ * context with a replacement `history`) — see {@link 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.
  */
-declare interface PostCompactInputContext {
+export declare interface PostCompactContext {
     /**
      * 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
@@ -2861,28 +2797,6 @@ declare interface PostCompactInputContext {
     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:
@@ -2914,7 +2828,7 @@ export declare type PostModelCallDecision = "continue" | "stop";
  * the outcome is treated as `"stop"`). Multiple plugins' hooks chain in
  * registration order — each sees the previous hook's `decision` and mutations.
  */
-declare interface PostModelCallInputContext {
+export declare interface PostModelCallContext {
     /** Conversation ID the message belongs to. */
     readonly conversationId: string;
     /** The call site this message serves — `"mainAgent"` for the user-facing reply; `null` when untagged. */
@@ -2957,15 +2871,23 @@ declare interface PostModelCallInputContext {
      * actionable outcomes (see the interface docstring).
      */
     decision: PostModelCallDecision;
+    /** Logger scoped to the current turn (tag structured fields with `{ plugin }`). */
+    readonly logger: PluginLogger;
 }
 
 /**
- * The full `post-tool-use` context a hook receives — the dispatching call
- * site's {@link PostToolUseInputContext} plus the pipeline-stamped
- * {@link BaseHookContext} capabilities.
+ * 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 interface PostToolUseContext extends PostToolUseInputContext, BaseHookContext {
-}
+export declare type PostModelCallDecision = "continue" | "stop";
 
 /**
  * Context passed to the `post-tool-use` hook. Fires once per tool result —
@@ -2975,7 +2897,7 @@ export declare interface PostToolUseContext extends PostToolUseInputContext, Bas
  *
  * 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 `HookFunction`'s
+ * context with a fresh `toolResponse` — see {@link HookFunction}'s
  * polymorphic return shape. The daemon threads the final `toolResponse`
  * into the provider-bound history.
  *
@@ -2987,7 +2909,7 @@ export declare interface PostToolUseContext extends PostToolUseInputContext, Bas
  * can swap in a smarter strategy (e.g. a summarizer) or observe results for
  * side effects.
  */
-declare interface PostToolUseInputContext {
+export declare interface PostToolUseContext {
     /** Conversation ID the tool ran on. */
     readonly conversationId: string;
     /**
@@ -3047,14 +2969,12 @@ declare interface PostToolUseInputContext {
      * receiving a precomputed limit.
      */
     readonly maxInputTokens: number;
-}
-
-/**
- * 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 {
+    /**
+     * 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;
 }
 
 /**
@@ -3070,7 +2990,7 @@ export declare interface PreModelCallContext extends PreModelCallInputContext, B
  * Mutate the context in place or return a new one; throwing is contained by the
  * loop (the call proceeds with the original request).
  */
-declare interface PreModelCallInputContext {
+export declare interface PreModelCallContext {
     /** Conversation ID the call belongs to. */
     readonly conversationId: string;
     /**
@@ -3109,6 +3029,8 @@ declare interface PreModelCallInputContext {
      * 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 {
@@ -3412,14 +3334,6 @@ 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>;
@@ -3537,7 +3451,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 | HookEvent | 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 | SubagentEvent;
 
 export declare interface ServerToolUseContent {
     type: "server_tool_use";
@@ -3758,14 +3672,6 @@ 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.
  *
@@ -3786,7 +3692,7 @@ export declare interface StopContext extends StopInputContext, BaseHookContext {
  *
  * Multiple plugins' hooks chain in registration order over the same context.
  */
-declare interface StopInputContext {
+export declare interface StopContext {
     /** Conversation ID the run belongs to. */
     readonly conversationId: string;
     /**
@@ -3809,6 +3715,12 @@ declare interface StopInputContext {
      * 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 {
@@ -4915,14 +4827,6 @@ 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 /
@@ -4932,7 +4836,7 @@ export declare interface UserPromptSubmitContext extends UserPromptSubmitInputCo
  *
  * 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 `HookFunction`'s polymorphic
+ * a fresh `latestMessages` array — see {@link HookFunction}'s polymorphic
  * return shape. The daemon threads the final `latestMessages` value into
  * `agentLoop.run()` as the run-messages argument.
  *
@@ -4945,7 +4849,7 @@ export declare interface UserPromptSubmitContext extends UserPromptSubmitInputCo
  * hook sees the previous plugin's mutations (whether by reassignment or
  * in-place mutation).
  */
-declare interface UserPromptSubmitInputContext {
+export declare interface UserPromptSubmitContext {
     /** Conversation ID the user prompt was submitted on. */
     readonly conversationId: string;
     /**
@@ -4953,14 +4857,6 @@ declare interface UserPromptSubmitInputContext {
      * 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;
     /**
@@ -4968,10 +4864,6 @@ declare interface UserPromptSubmitInputContext {
      * 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;
     /**
@@ -5019,6 +4911,12 @@ declare interface UserPromptSubmitInputContext {
      * 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-dev.202607042025.8a04d0b",
+  "version": "0.10.5-staging.2",
   "description": "Public TypeScript authoring contract for Vellum assistant plugins.",
   "license": "MIT",
   "type": "module",