@vellumai/plugin-api 0.9.0 → 0.9.1-staging.1

package/index.d.ts

@@ -524,8 +524,7 @@ declare type _BookmarksServerMessages = BookmarkCreated | BookmarkDeleted;
 
 /**
  * Wire-shape representation of a bookmark, joined with the bookmarked
- * message and its parent conversation. Mirrors
- * `clients/shared/Network/BookmarkSummary.swift` — dates are emitted as
+ * message and its parent conversation. Dates are emitted as
  * unix-millisecond integers, and the message preview is capped to keep
  * the list payload bounded.
  */
@@ -920,9 +919,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;
@@ -1471,6 +1470,19 @@ declare const GenerationHandoffEventSchema: z.ZodObject<{
     attachmentWarnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 
+/**
+ * List the workspace inference profiles a plugin can route to, in the order the
+ * `/model` picker presents them (`llm.profileOrder` first, then the rest
+ * alphabetically). Disabled profiles are included and flagged via
+ * {@link ModelProfileInfo.isDisabled}; weighted "mix" profiles are included and
+ * flagged via {@link ModelProfileInfo.isMix}, since a mix is itself a valid
+ * routing target (it resolves to one constituent per conversation).
+ *
+ * Reads the live in-memory config, so the result reflects the current profile
+ * set each time it is called.
+ */
+export declare function getModelProfiles(): ModelProfileInfo[];
+
 /**
  * Retrieve a secret from secure storage. Convenience wrapper over
  * `getSecureKeyResultAsync` that returns only the value.
@@ -1729,7 +1741,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";
@@ -2453,6 +2465,33 @@ declare interface ModelInfo {
     }>;
 }
 
+/**
+ * A workspace inference profile a plugin can route to. Returned by
+ * {@link getModelProfiles}; {@link key} is the value a `pre-model-call` hook
+ * assigns to `PreModelCallContext.modelProfile` to route a call. A model router
+ * reads this list (typically at `init`) to learn which profiles exist before
+ * mapping a classified message onto one.
+ */
+export declare interface ModelProfileInfo {
+    /** Profile key in `llm.profiles`; assignable to `PreModelCallContext.modelProfile`. */
+    readonly key: string;
+    /** Human-readable label, falling back to {@link key} when none is set. */
+    readonly label: string;
+    /** Author-supplied description, or `null` when none is set. */
+    readonly description: string | null;
+    /** Whether this is the workspace's active profile. */
+    readonly isActive: boolean;
+    /** Whether the profile is disabled; routing to it is rejected by the resolver. */
+    readonly isDisabled: boolean;
+    /**
+     * Whether this is a weighted "mix" profile — an A/B blend that resolves to one
+     * of its constituent profiles per conversation via a seeded weighted pick.
+     * Routing to its {@link key} is valid; it directs the call into the blend
+     * rather than at a single fixed model.
+     */
+    readonly isMix: boolean;
+}
+
 declare type NavigateSettingsEvent = z.infer<typeof NavigateSettingsEventSchema>;
 
 declare const NavigateSettingsEventSchema: z.ZodObject<{
@@ -2929,8 +2968,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).
  */
@@ -2947,6 +2987,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

package/index.js

@@ -3,4 +3,5 @@ const api = globalThis[Symbol.for("vellum.plugin-api")] ?? {};
 export const HOOKS = api.HOOKS;
 export const RiskLevel = api.RiskLevel;
 export const assistantEventHub = api.assistantEventHub;
+export const getModelProfiles = api.getModelProfiles;
 export const getSecureKeyAsync = api.getSecureKeyAsync;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/plugin-api",
-  "version": "0.9.0",
+  "version": "0.9.1-staging.1",
   "description": "Public TypeScript authoring contract for Vellum assistant plugins.",
   "license": "MIT",
   "type": "module",