@vellumai/plugin-api 0.10.5-dev.202607031734.f263495 → 0.10.5-dev.202607031834.d3e3143

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;
@@ -1827,6 +1851,20 @@ 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`.
+ */
+declare type HookBroadcast = (detail: Record<string, unknown>) => void;
+
 declare type HookEvent = z.infer<typeof HookEventSchema>;
 
 declare const HookEventSchema: z.ZodObject<{
@@ -1862,6 +1900,7 @@ 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}
@@ -2756,6 +2795,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
@@ -2770,12 +2817,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
@@ -2814,6 +2861,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:
@@ -2845,7 +2914,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. */
@@ -2888,23 +2957,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 —
@@ -2914,7 +2975,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.
  *
@@ -2926,7 +2987,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;
     /**
@@ -2986,12 +3047,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 {
 }
 
 /**
@@ -3007,7 +3070,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;
     /**
@@ -3046,8 +3109,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 {
@@ -3697,6 +3758,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.
  *
@@ -3717,7 +3786,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;
     /**
@@ -3740,12 +3809,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 {
@@ -4852,6 +4915,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 /
@@ -4861,7 +4932,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.
  *
@@ -4874,7 +4945,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;
     /**
@@ -4948,25 +5019,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;
-    /**
-     * Emit a transient `hook_event` to any UI watching this conversation —
-     * e.g. progress while the hook does work the user can feel (memory
-     * selection). The daemon stamps the conversation, this hook's name, and
-     * the owning plugin; 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, is
-     * not persisted (a client joining mid-turn will not replay it), and cannot
-     * emit any other event type or target another conversation — the emit
-     * surface is bound to this turn.
-     */
-    readonly broadcast: (detail: Record<string, unknown>) => void;
 }
 
 declare interface VellumSlimSkill extends SlimSkillBase {

package/package.json

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