@vellumai/plugin-api 0.10.2-dev.202606251104.36cd100 → 0.10.2-dev.202606251348.a66ca6e

package/index.d.ts

@@ -1789,6 +1789,32 @@ declare const HomeFeedUpdatedEventSchema: z.ZodObject<{
 
 declare type _HomeServerMessages = RelationshipStateUpdatedEvent | HomeFeedUpdatedEvent;
 
+/**
+ * A plugin lifecycle hook. Receives a per-lifecycle context shape and may
+ * either mutate `ctx` in place (returning `void`) or return a *partial*
+ * context whose fields are merged onto the threaded context — only the keys
+ * it returns are overwritten, every other field is preserved. Returning a
+ * partial lets a hook edit just the subset of fields it cares about without
+ * having to re-specify the rest. The merged context is threaded to the next
+ * hook in the chain (e.g. `user-prompt-submit`).
+ *
+ * Because an omitted key means "keep the existing value", every field on a
+ * context shape is required (no `?`-optional or `| undefined` members): a
+ * present key always carries a concrete value, so "absent from the returned
+ * partial" is never ambiguous with "explicitly cleared". Fields that can be
+ * empty model that with `| null`, not `| undefined`.
+ *
+ * Each known hook key has a documented context shape:
+ *   - `init` — {@link InitContext}
+ *   - `shutdown` — {@link ShutdownContext}
+ *   - `user-prompt-submit` — {@link UserPromptSubmitContext}
+ *   - `pre-model-call` — {@link PreModelCallContext}
+ *   - `post-tool-use` — {@link PostToolUseContext}
+ *   - `stop` — {@link StopContext}
+ *   - `post-model-call` — {@link PostModelCallContext}
+ */
+export declare type HookFunction<TCtx = unknown> = (ctx: TCtx) => Promise<Partial<TCtx> | void>;
+
 /** Union of every hook name declared in {@link HOOKS}. */
 export declare type HookName = (typeof HOOKS)[keyof typeof HOOKS];
 
@@ -2139,6 +2165,27 @@ declare interface IngressConfigResponse {
     error?: string;
 }
 
+/**
+ * Context passed to `Plugin.init()` during bootstrap. Carries the resolved
+ * config, a pino-compatible logger scoped to the plugin, a per-plugin
+ * writable data directory, and the assistant's version metadata.
+ */
+export declare interface InitContext {
+    /** Parsed config for this plugin (may be `unknown` until the manifest validates). */
+    config: unknown;
+    /** Pino-compatible child logger bound to `{ plugin: <name> }`. */
+    logger: PluginLogger;
+    /** Absolute path to `<workspaceDir>/plugins-data/<plugin>/` (created by bootstrap). */
+    pluginStorageDir: string;
+    /**
+     * Assistant semver. Plugins can compare against this for defensive
+     * runtime checks — but the canonical compat contract is the host
+     * version against the plugin's `peerDependencies["@vellumai/plugin-api"]`
+     * semver range, enforced at load time by the external-plugin loader.
+     */
+    assistantVersion: string;
+}
+
 declare interface IntegrationConnectResult {
     type: "integration_connect_result";
     integrationId: string;
@@ -2724,53 +2771,6 @@ declare interface PlatformDisconnected {
     type: "platform_disconnected";
 }
 
-/**
- * A plugin lifecycle hook. Receives a per-lifecycle context shape and may
- * either mutate `ctx` in place (returning `void`) or return a *partial*
- * context whose fields are merged onto the threaded context — only the keys
- * it returns are overwritten, every other field is preserved. Returning a
- * partial lets a hook edit just the subset of fields it cares about without
- * having to re-specify the rest. The merged context is threaded to the next
- * hook in the chain (e.g. `user-prompt-submit`).
- *
- * Because an omitted key means "keep the existing value", every field on a
- * context shape is required (no `?`-optional or `| undefined` members): a
- * present key always carries a concrete value, so "absent from the returned
- * partial" is never ambiguous with "explicitly cleared". Fields that can be
- * empty model that with `| null`, not `| undefined`.
- *
- * Each known hook key has a documented context shape:
- *   - `init` — {@link PluginInitContext}
- *   - `shutdown` — {@link PluginShutdownContext}
- *   - `user-prompt-submit` — {@link UserPromptSubmitContext}
- *   - `pre-model-call` — {@link PreModelCallContext}
- *   - `post-tool-use` — {@link PostToolUseContext}
- *   - `stop` — {@link StopContext}
- *   - `post-model-call` — {@link PostModelCallContext}
- */
-export declare type PluginHookFn<TCtx = unknown> = (ctx: TCtx) => Promise<Partial<TCtx> | void>;
-
-/**
- * Context passed to `Plugin.init()` during bootstrap. Carries the resolved
- * config, a pino-compatible logger scoped to the plugin, a per-plugin
- * writable data directory, and the assistant's version metadata.
- */
-export declare interface PluginInitContext {
-    /** Parsed config for this plugin (may be `unknown` until the manifest validates). */
-    config: unknown;
-    /** Pino-compatible child logger bound to `{ plugin: <name> }`. */
-    logger: PluginLogger;
-    /** Absolute path to `<workspaceDir>/plugins-data/<plugin>/` (created by bootstrap). */
-    pluginStorageDir: string;
-    /**
-     * Assistant semver. Plugins can compare against this for defensive
-     * runtime checks — but the canonical compat contract is the host
-     * version against the plugin's `peerDependencies["@vellumai/plugin-api"]`
-     * semver range, enforced at load time by the external-plugin loader.
-     */
-    assistantVersion: string;
-}
-
 /**
  * Minimal pino-compatible logger surface handed to plugin hooks. The host
  * supplies a pino child logger bound to `{ plugin: <name> }`; this
@@ -2790,23 +2790,6 @@ export declare interface PluginLogger {
     debug(obj: Record<string, unknown>, msg?: string): void;
 }
 
-/**
- * Context passed to the `shutdown` hook during daemon teardown. Kept
- * intentionally narrower than {@link PluginInitContext} — most teardown
- * paths only need to know which assistant version they're shutting
- * down against (e.g. for version-conditional cleanup of state files
- * written by a previous boot).
- *
- * Additional fields may be added as concrete plugin needs surface; the
- * `assistantVersion` field mirrors the init context's so plugins that
- * stash a version stamp at init can compare against the same name on
- * tear-down without keeping their own copy.
- */
-export declare interface PluginShutdownContext {
-    /** Assistant semver for compatibility checks inside the plugin. */
-    assistantVersion: string;
-}
-
 declare interface PongMessage {
     type: "pong";
 }
@@ -2825,7 +2808,7 @@ 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 PluginHookFn}'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.
@@ -2972,7 +2955,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 PluginHookFn}'s
+ * context with a fresh `toolResponse` — see {@link HookFunction}'s
  * polymorphic return shape. The daemon threads the final `toolResponse`
  * into the provider-bound history.
  *
@@ -3568,6 +3551,23 @@ declare interface ShowPlatformLogin {
     type: "show_platform_login";
 }
 
+/**
+ * Context passed to the `shutdown` hook during daemon teardown. Kept
+ * intentionally narrower than {@link InitContext} — most teardown
+ * paths only need to know which assistant version they're shutting
+ * down against (e.g. for version-conditional cleanup of state files
+ * written by a previous boot).
+ *
+ * Additional fields may be added as concrete plugin needs surface; the
+ * `assistantVersion` field mirrors the init context's so plugins that
+ * stash a version stamp at init can compare against the same name on
+ * tear-down without keeping their own copy.
+ */
+export declare interface ShutdownContext {
+    /** Assistant semver for compatibility checks inside the plugin. */
+    assistantVersion: string;
+}
+
 declare interface SignBundlePayloadRequest {
     type: "sign_bundle_payload";
     requestId: string;
@@ -3895,6 +3895,26 @@ declare interface ToolActivityMetadata {
     webFetch?: WebFetchMetadata;
 }
 
+/**
+ * Runtime context passed as the second argument to every tool's `execute`.
+ *
+ * The fields fall into two groups:
+ *
+ * - A small, stable core that we are comfortable exposing to any tool —
+ *   including workspace- and plugin-authored tools via `@vellumai/plugin-api`:
+ *   `conversationId`, `workingDir`, `requestId`, `signal`, `onOutput`,
+ *   `assistantId`, `isInteractive`.
+ * - Everything tagged `@legacy` below: host-internal routing, permission,
+ *   trust, requester-identity, proxy, and telemetry metadata that historically
+ *   accreted on this single context. These are NOT a surface we want third-party
+ *   tools to depend on; we are triaging them post-launch with the goal of
+ *   moving them off the public context (or removing them) over time. Grep for
+ *   `@legacy` to enumerate the set. Do not add new fields here — extend the
+ *   stable core only when a field is genuinely safe and stable to expose.
+ *
+ * The daemon constructs and passes the full object to every tool at runtime; a
+ * tool that only reads the stable core is unaffected by the eventual cleanup.
+ */
 export declare interface ToolContext {
     /** Identifier of the conversation this tool invocation belongs to. */
     conversationId: string;
@@ -3908,23 +3928,44 @@ export declare interface ToolContext {
     onOutput?: (chunk: string) => void;
     /** Logical assistant scope for multi-assistant routing. */
     assistantId?: string;
-    /** When set, the tool execution is part of a task run. Used to retrieve ephemeral permission rules. */
+    /** True when an interactive client is connected (not just a no-op callback). */
+    isInteractive?: boolean;
+    /**
+     * When set, the tool execution is part of a task run. Used to retrieve ephemeral permission rules.
+     * @legacy
+     */
     taskRunId?: string;
     /**
      * Model attribution snapshot for the conversation at invocation time
      * (provider/model/profile that issued this tool call). Used by tool
      * telemetry; never sent to the tool itself.
+     * @legacy
      */
     attribution?: UsageAttributionSnapshot | null;
-    /** Optional callback for tool lifecycle events (start/prompt/deny/execute/error). */
+    /**
+     * Optional callback for tool lifecycle events (start/prompt/deny/execute/error).
+     * @legacy
+     */
     onToolLifecycleEvent?: ToolLifecycleEventHandler;
-    /** Optional resolver for proxy tools - delegates execution to an external client. */
+    /**
+     * Optional resolver for proxy tools - delegates execution to an external client.
+     * @legacy
+     */
     proxyToolResolver?: ProxyToolResolver;
-    /** When set, only tools in this set may execute. Tools outside the set are blocked with an error. */
+    /**
+     * When set, only tools in this set may execute. Tools outside the set are blocked with an error.
+     * @legacy
+     */
     allowedToolNames?: Set<string>;
-    /** True when this turn is restricted to storage cleanup-safe tools. */
+    /**
+     * True when this turn is restricted to storage cleanup-safe tools.
+     * @legacy
+     */
     diskPressureCleanupModeActive?: boolean;
-    /** Prompt the user for a secret value via native SecureField UI. */
+    /**
+     * Prompt the user for a secret value via native SecureField UI.
+     * @legacy
+     */
     requestSecret?: (params: {
         service: string;
         field: string;
@@ -3935,14 +3976,18 @@ export declare interface ToolContext {
         allowedTools?: string[];
         allowedDomains?: string[];
     }) => Promise<SecretPromptResult>;
-    /** Optional callback to send a message to the connected client (e.g. open_url). */
+    /**
+     * Optional callback to send a message to the connected client (e.g. open_url).
+     * @legacy
+     */
     sendToClient?: (msg: {
         type: string;
         [key: string]: unknown;
     }) => void;
-    /** True when an interactive client is connected (not just a no-op callback). */
-    isInteractive?: boolean;
-    /** When true, tools with side effects should always prompt for confirmation. */
+    /**
+     * When true, tools with side effects should always prompt for confirmation.
+     * @legacy
+     */
     forcePromptSideEffects?: boolean;
     /**
      * When true, the tool requires a fresh interactive approval for every
@@ -3953,26 +3998,46 @@ export declare interface ToolContext {
      * temporary override options in the prompt UI. Used by
      * `manage_secure_command_tool` to ensure a human reviews each secure
      * bundle installation.
+     * @legacy
      */
     requireFreshApproval?: boolean;
-    /** Approval callback for proxy policy decisions that require user confirmation. */
+    /**
+     * Approval callback for proxy policy decisions that require user confirmation.
+     * @legacy
+     */
     proxyApprovalCallback?: ProxyApprovalCallback;
-    /** Optional principal identifier propagated to sub-tool confirmation flows. */
+    /**
+     * Optional principal identifier propagated to sub-tool confirmation flows.
+     * @legacy
+     */
     principal?: string;
     /**
      * Trust classification of the actor who initiated this tool invocation.
      * Determines permission level: guardians self-approve, trusted contacts
      * may escalate to guardian for approval, unknown actors are fail-closed.
      * See {@link TrustClass} in actor-trust-resolver.ts for value semantics.
+     * @legacy
      */
     trustClass: TrustClass;
-    /** Channel through which the tool invocation originates (e.g. 'telegram', 'phone'). Used for scoped grant consumption. */
+    /**
+     * Channel through which the tool invocation originates (e.g. 'telegram', 'phone'). Used for scoped grant consumption.
+     * @legacy
+     */
     executionChannel?: string;
-    /** Voice/call session ID, if the invocation originates from a call. Used for scoped grant consumption. */
+    /**
+     * Voice/call session ID, if the invocation originates from a call. Used for scoped grant consumption.
+     * @legacy
+     */
     callSessionId?: string;
-    /** True when the tool invocation was triggered by a user clicking a surface action button (not a regular message). */
+    /**
+     * True when the tool invocation was triggered by a user clicking a surface action button (not a regular message).
+     * @legacy
+     */
     triggeredBySurfaceAction?: boolean;
-    /** True when the user explicitly approved this tool invocation via the interactive permission prompt (not auto-approved by trust rules or temporary overrides). */
+    /**
+     * True when the user explicitly approved this tool invocation via the interactive permission prompt (not auto-approved by trust rules or temporary overrides).
+     * @legacy
+     */
     approvedViaPrompt?: boolean;
     /**
      * True when the invocation is inside a scheduled task run whose
@@ -3980,21 +4045,43 @@ export declare interface ToolContext {
      * Tools that normally require a surface-action click (e.g. bulk archive,
      * unsubscribe) may treat this as equivalent consent, since the user
      * already reviewed the tool list when the task was saved.
+     * @legacy
      */
     batchAuthorizedByTask?: boolean;
-    /** External user ID of the requester (non-guardian actor). Used for scoped grant consumption. */
+    /**
+     * External user ID of the requester (non-guardian actor). Used for scoped grant consumption.
+     * @legacy
+     */
     requesterExternalUserId?: string;
-    /** Chat ID of the requester (non-guardian actor). Used for tool grant request escalation notifications. */
+    /**
+     * Chat ID of the requester (non-guardian actor). Used for tool grant request escalation notifications.
+     * @legacy
+     */
     requesterChatId?: string;
-    /** Human-readable identifier for the requester (e.g., @username). */
+    /**
+     * Human-readable identifier for the requester (e.g., @username).
+     * @legacy
+     */
     requesterIdentifier?: string;
-    /** Preferred display name for the requester. */
+    /**
+     * Preferred display name for the requester.
+     * @legacy
+     */
     requesterDisplayName?: string;
-    /** Slack channel ID for channel-scoped permission enforcement. When set, tools are checked against the channel's permission profile. */
+    /**
+     * Slack channel ID for channel-scoped permission enforcement. When set, tools are checked against the channel's permission profile.
+     * @legacy
+     */
     channelPermissionChannelId?: string;
-    /** The tool_use block ID from the LLM response, used to correlate confirmation prompts with specific tool invocations. */
+    /**
+     * The tool_use block ID from the LLM response, used to correlate confirmation prompts with specific tool invocations.
+     * @legacy
+     */
     toolUseId?: string;
-    /** True when the assistant is running as a platform-managed remote instance. Used to auto-approve sandboxed bash tools. */
+    /**
+     * True when the assistant is running as a platform-managed remote instance. Used to auto-approve sandboxed bash tools.
+     * @legacy
+     */
     isPlatformHosted?: boolean;
     /**
      * The interface ID of the connected client driving the current turn (e.g.
@@ -4002,6 +4089,7 @@ export declare interface ToolContext {
      * transport preference — for example, macOS-originated turns prefer the
      * user's real Chrome session via the paired extension before falling back
      * to cdp-inspect or local Playwright.
+     * @legacy
      */
     transportInterface?: InterfaceId;
     /**
@@ -4012,6 +4100,7 @@ export declare interface ToolContext {
      * has `inferenceProfile` set — the override only flows through the
      * in-memory `SubagentConfig.overrideProfile` chain. See
      * `executeSubagentSpawn` in tools/subagent/spawn.ts.
+     * @legacy
      */
     overrideProfile?: string;
     /**
@@ -4020,6 +4109,7 @@ export declare interface ToolContext {
      * default a spawned subagent's inference profile to the profile the invoking
      * turn resolved to, so subagents match whatever agent invoked them rather
      * than always falling back to the static `subagentSpawn` call-site default.
+     * @legacy
      */
     invokingCallSite?: LLMCallSite;
     /**
@@ -4028,6 +4118,7 @@ export declare interface ToolContext {
      * Used by host proxies to bind cross-client targeted execution to the same
      * authenticated user identity. May be undefined for legacy/internal flows
      * with no resolved actor identity.
+     * @legacy
      */
     sourceActorPrincipalId?: string;
 }
@@ -4744,7 +4835,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 PluginHookFn}'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.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/plugin-api",
-  "version": "0.10.2-dev.202606251104.36cd100",
+  "version": "0.10.2-dev.202606251348.a66ca6e",
   "description": "Public TypeScript authoring contract for Vellum assistant plugins.",
   "license": "MIT",
   "type": "module",