@vellumai/plugin-api 0.10.4-staging.1 → 0.10.4

package/index.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-declare type _AcpServerMessages = AcpSessionSpawned | AcpSessionUpdate | AcpSessionCompleted | AcpSessionError;
+declare type _AcpServerMessages = AcpSessionSpawned | AcpSessionUpdate | AcpSessionCompleted | AcpSessionError | AcpSessionUsage;
 
 declare interface AcpSessionCompleted {
     type: "acp_session_completed";
@@ -19,6 +19,10 @@ declare interface AcpSessionSpawned {
     acpSessionId: string;
     agent: string;
     parentConversationId: string;
+    /** Tool-use id of the `acp_spawn` call that spawned this session. */
+    parentToolUseId?: string;
+    /** Objective text for the spawned session. */
+    task?: string;
 }
 
 declare interface AcpSessionUpdate {
@@ -30,6 +34,30 @@ declare interface AcpSessionUpdate {
     toolTitle?: string;
     toolKind?: string;
     toolStatus?: string;
+    /** Optional raw input parameters sent to the tool (ACP `rawInput`); shape is tool-specific. */
+    rawInput?: unknown;
+    /** Optional raw output returned by the tool (ACP `rawOutput`); shape is tool-specific. */
+    rawOutput?: unknown;
+    /** Files touched by this tool call (for the file-diff affordance). */
+    locations?: {
+        path: string;
+        line?: number;
+    }[];
+    /** Stable id for the message this chunk belongs to. */
+    messageId?: string;
+    /** Monotonic ordering hint within the session. */
+    seq?: number;
+}
+
+declare interface AcpSessionUsage {
+    type: "acp_session_usage";
+    acpSessionId: string;
+    usedTokens: number;
+    contextSize: number;
+    costAmount?: number;
+    costCurrency?: string;
+    inputTokens?: number;
+    outputTokens?: number;
 }
 
 /**
@@ -448,6 +476,15 @@ declare interface AssistantInboxEscalationResponse {
     };
 }
 
+/**
+ * Managed skill authored by the assistant's retrospective. Identical shape to a
+ * custom skill — it stays managed/deletable — but carries a distinct origin so
+ * the UI badges it as "Assistant's Memory" instead of "Custom".
+ */
+declare interface AssistantMemorySlimSkill extends SlimSkillBase {
+    origin: "assistant-memory";
+}
+
 declare interface AssistantStatusMessage {
     type: "assistant_status";
     version?: string;
@@ -2171,13 +2208,23 @@ declare interface IngressConfigResponse {
  * 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.
+ *
+ * For user-installed plugins, config is read from `<pluginDir>/config.json`
+ * and `pluginStorageDir` points at `<pluginDir>/data/`. For first-party
+ * default plugins and standalone workspace hooks, config comes from the
+ * global `config.plugins.<name>` block and `pluginStorageDir` points at
+ * `<workspaceDir>/plugins-data/<name>/`.
  */
 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). */
+    /**
+     * Absolute path to the per-plugin writable data directory. For user plugins
+     * this is `<pluginDir>/data/`; for defaults and workspace hooks it falls back
+     * to `<workspaceDir>/plugins-data/<plugin>/`. Created by bootstrap.
+     */
     pluginStorageDir: string;
     /**
      * Assistant semver. Plugins can compare against this for defensive
@@ -2232,6 +2279,23 @@ declare const INTERFACE_IDS: readonly ["macos", "ios", "cli", "telegram", "phone
 
 declare type InterfaceId = (typeof INTERFACE_IDS)[number];
 
+/**
+ * Provider stop-reason classification.
+ *
+ * Providers report an output-length cutoff under several normalized
+ * finish-reason strings; {@link isMaxTokensStopReason} folds them into a single
+ * "was this turn truncated at the token cap?" predicate.
+ *
+ * Kept dependency-free so it can be re-exported through `@vellumai/plugin-api`
+ * without pulling the agent loop (its other caller) into the plugin API's
+ * module graph.
+ */
+/**
+ * Whether a provider stop reason denotes output truncated at the token cap.
+ * Case- and whitespace-insensitive; a `null`/`undefined`/empty reason is false.
+ */
+export declare function isMaxTokensStopReason(stopReason: string | null | undefined): boolean;
+
 declare interface ListItem {
     id: string;
     title: string;
@@ -2840,13 +2904,10 @@ export declare interface PostCompactContext {
      */
     readonly isNonInteractive: boolean;
     /**
-     * Active inference profile key to surface in the re-injected context, or
-     * `null` when the profile is unchanged since the one last announced to the
-     * model. Mirrors {@link UserPromptSubmitContext.modelProfileKey}: hooks that
-     * emit the `model_profile` grounding line resolve the human-readable label
-     * from this key rather than receiving the rendered string.
+     * Effective inference profile identity for the model the compacted turn will
+     * keep using. Mirrors {@link UserPromptSubmitContext.modelProfileKey}.
      */
-    readonly modelProfileKey: string | null;
+    readonly modelProfileKey: string;
     /**
      * Volume of runtime injection to re-apply. `"full"` restores the complete
      * runtime context; `"minimal"` is the reduced volume overflow recovery's
@@ -3000,9 +3061,28 @@ export declare interface PostToolUseContext {
      * Model id reported by the provider for the assistant turn that issued
      * this tool call (e.g. `claude-opus-4-8`,
      * `accounts/fireworks/models/kimi-k2p6`). Hooks use it to vary coaching by
-     * model family — some models need earlier or firmer steering than others.
+     * model family — each plugin owns its own model policy (e.g. which families
+     * need firmer steering) and matches against this string directly.
      */
     readonly model: string;
+    /**
+     * The LLM call site driving this turn — `mainAgent` for a live user-facing
+     * turn, `subagentSpawn` for a subagent, or a background site (e.g.
+     * `heartbeatAgent`, `titleGenerate`). `null` when the run tagged none. A hook
+     * that should only act on a live user-facing turn gates on
+     * `callSite === "mainAgent"`; one that should skip subagents checks
+     * `callSite === "subagentSpawn"`.
+     */
+    readonly callSite: LLMCallSite | null;
+    /**
+     * Whether the connected client can render dynamic UI surfaces this turn —
+     * `true` unless the channel explicitly lacks the capability (SMS, phone,
+     * email, and most chat bridges). A fact about what the model can *do* this
+     * turn, not who is calling: a hook that prompts a surface tool (e.g. the
+     * `ui_show` progress card) gates on this so it does not coach the model
+     * toward a tool the channel filters out of the tool set.
+     */
+    readonly supportsDynamicUi: boolean;
     /**
      * The model's context-window size in tokens. Plugins derive their own
      * character budget from this (e.g. a share of the window) rather than
@@ -3693,7 +3773,7 @@ declare interface SlimSkillBase {
     owner?: OwnerInfo;
 }
 
-declare type SlimSkillResponse = VellumSlimSkill | ClawhubSlimSkill | SkillsshSlimSkill | CustomSlimSkill;
+declare type SlimSkillResponse = VellumSlimSkill | ClawhubSlimSkill | SkillsshSlimSkill | CustomSlimSkill | AssistantMemorySlimSkill;
 
 /** Sent by the daemon when sounds config or sound files change on disk. */
 declare interface SoundsConfigUpdated {
@@ -4038,6 +4118,17 @@ export declare interface ToolContext {
      * @legacy
      */
     executionChannel?: string;
+    /**
+     * Origin tag of the turn driving this tool invocation (the conversation's
+     * `TitleOrigin`, e.g. "memory_retrospective"). Set for background-job turns
+     * that pass `requestOrigin` to `runBackgroundJob`, and for the
+     * memory-retrospective wake (which pins it via {@link WakeToolContextPin}).
+     * `buildPolicyContext` copies it onto the `PolicyContext` so the permission
+     * checker can scope narrow non-interactive auto-grants (e.g. retrospective
+     * skill authoring) to a specific internal origin. Unset for normal
+     * interactive turns.
+     */
+    requestOrigin?: string;
     /**
      * Voice/call session ID, if the invocation originates from a call. Used for scoped grant consumption.
      * @legacy
@@ -4558,6 +4649,7 @@ declare const ToolUsePreviewStartEventSchema: z.ZodObject<{
     toolName: z.ZodString;
     conversationId: z.ZodOptional<z.ZodString>;
     messageId: z.ZodOptional<z.ZodString>;
+    previewStartedAt: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 
 declare type ToolUseStartEvent = z.infer<typeof ToolUseStartEventSchema>;
@@ -4570,6 +4662,7 @@ declare const ToolUseStartEventSchema: z.ZodObject<{
     messageId: z.ZodOptional<z.ZodString>;
     conversationId: z.ZodOptional<z.ZodString>;
     startedAt: z.ZodOptional<z.ZodNumber>;
+    previewStartedAt: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 
 declare type TraceEvent = z.infer<typeof TraceEventSchema>;
@@ -4880,14 +4973,13 @@ export declare interface UserPromptSubmitContext {
      */
     readonly requestId: string;
     /**
-     * Active inference profile key to surface in this turn's context, or `null`
-     * when the profile is unchanged since the one last announced to the model.
-     * Hooks that emit the `model_profile` grounding line resolve the
-     * human-readable label (and model id) from this key via the workspace LLM
-     * config rather than receiving the rendered string — the key is the minimal
-     * turn input the message arrays cannot carry.
+     * Effective inference profile identity for the model this turn will use.
+     * Named-profile configs receive a profile key; profileless configs receive
+     * the resolved model id. Hooks that need model capabilities should resolve
+     * them from this value rather than the workspace active profile, because a
+     * conversation can be pinned to a different profile.
      */
-    readonly modelProfileKey: string | null;
+    readonly modelProfileKey: string;
     /**
      * Whether the turn has no human present to answer clarification questions
      * (e.g. a scheduled, background, or headless run). Resolved once at turn

package/index.js

@@ -6,3 +6,4 @@ export const assistantEventHub = api.assistantEventHub;
 export const doesSupportVision = api.doesSupportVision;
 export const getConfiguredProvider = api.getConfiguredProvider;
 export const getModelProfiles = api.getModelProfiles;
+export const isMaxTokensStopReason = api.isMaxTokensStopReason;

package/package.json

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