@vellumai/plugin-api 0.11.1 → 0.11.2-dev.202608042227.b54139c

package/index.d.ts

@@ -76,6 +76,37 @@ export declare type AgentLoopExitReason =
 /** An unhandled error ended the turn. */
 | "error";
 
+declare type AnsweredQuestion = z.infer<typeof AnsweredQuestionSchema>;
+
+declare const AnsweredQuestionSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    questions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        question: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        options: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        freeTextPlaceholder: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    responses: z.ZodArray<z.ZodObject<{
+        questionId: z.ZodString;
+        decision: z.ZodEnum<{
+            option: "option";
+            free_text: "free_text";
+            skipped: "skipped";
+        }>;
+        optionId: z.ZodOptional<z.ZodString>;
+        text: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    overall: z.ZodEnum<{
+        completed: "completed";
+        closed: "closed";
+    }>;
+}, z.core.$strip>;
+
 /**
  * How {@link listConversations} (and friends) treats archived rows.
  *
@@ -487,6 +518,7 @@ declare const AssistantConfigSchema: z.ZodObject<{
             timeThresholdMs: z.ZodDefault<z.ZodNumber>;
             messageThreshold: z.ZodDefault<z.ZodNumber>;
             minCooldownMs: z.ZodDefault<z.ZodNumber>;
+            requireUserActivity: z.ZodDefault<z.ZodBoolean>;
             sweepIntervalMs: z.ZodDefault<z.ZodNumber>;
             sweepLookbackMs: z.ZodDefault<z.ZodNumber>;
             keepSupersededRuns: z.ZodDefault<z.ZodBoolean>;
@@ -499,6 +531,9 @@ declare const AssistantConfigSchema: z.ZodObject<{
         ringBufferSize: z.ZodDefault<z.ZodNumber>;
         highMemThresholdRatio: z.ZodDefault<z.ZodNumber>;
         snapshotCooldownMs: z.ZodDefault<z.ZodNumber>;
+        fdPollIntervalMs: z.ZodDefault<z.ZodNumber>;
+        highFdThresholdRatio: z.ZodDefault<z.ZodNumber>;
+        fdWarnCooldownMs: z.ZodDefault<z.ZodNumber>;
         pluginSourceScanIntervalMs: z.ZodDefault<z.ZodNumber>;
         baselineSnapshotIntervalMs: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
@@ -944,6 +979,9 @@ declare const AssistantConfigSchema: z.ZodObject<{
         failureBackoffBaseMs: z.ZodDefault<z.ZodNumber>;
         failureBackoffMaxMs: z.ZodDefault<z.ZodNumber>;
         maxFileSizeBytes: z.ZodDefault<z.ZodNumber>;
+        historyCompaction: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
         interactiveGitTimeoutMs: z.ZodDefault<z.ZodNumber>;
         enrichmentQueueSize: z.ZodDefault<z.ZodNumber>;
         enrichmentConcurrency: z.ZodDefault<z.ZodNumber>;
@@ -1299,8 +1337,8 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         id: z.ZodString;
         conversationId: z.ZodString;
         status: z.ZodEnum<{
-            cancelled: "cancelled";
             completed: "completed";
+            cancelled: "cancelled";
             failed: "failed";
         }>;
         exitCode: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
@@ -1434,6 +1472,11 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         summaryCharCount: z.ZodOptional<z.ZodNumber>;
         summaryHeaderCount: z.ZodOptional<z.ZodNumber>;
         summaryHadMemoryEcho: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"context_window_usage">;
+        conversationId: z.ZodString;
+        tokens: z.ZodNumber;
+        maxTokens: z.ZodNumber;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"conversation_error">;
         conversationId: z.ZodString;
@@ -1967,9 +2010,15 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         title: z.ZodString;
         body: z.ZodString;
         deliveryId: z.ZodOptional<z.ZodString>;
+        correlationId: z.ZodOptional<z.ZodString>;
         deepLinkMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         targetGuardianPrincipalId: z.ZodOptional<z.ZodString>;
         silent: z.ZodOptional<z.ZodBoolean>;
+        remotePushDispatched: z.ZodOptional<z.ZodBoolean>;
+        remotePushPlatforms: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            ios: "ios";
+            android: "android";
+        }>>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"oauth_connect_result">;
         success: z.ZodBoolean;
@@ -2240,6 +2289,34 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
                 mayRequireJavaScript: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strip>>;
         }, z.core.$strip>>;
+        answeredQuestion: z.ZodOptional<z.ZodObject<{
+            requestId: z.ZodString;
+            questions: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                question: z.ZodString;
+                description: z.ZodOptional<z.ZodString>;
+                options: z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                    label: z.ZodString;
+                    description: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+                freeTextPlaceholder: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            responses: z.ZodArray<z.ZodObject<{
+                questionId: z.ZodString;
+                decision: z.ZodEnum<{
+                    option: "option";
+                    free_text: "free_text";
+                    skipped: "skipped";
+                }>;
+                optionId: z.ZodOptional<z.ZodString>;
+                text: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            overall: z.ZodEnum<{
+                completed: "completed";
+                closed: "closed";
+            }>;
+        }, z.core.$strip>>;
         errorCode: z.ZodOptional<z.ZodString>;
         completedAt: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>, z.ZodObject<{
@@ -2268,6 +2345,12 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         type: z.ZodLiteral<"ui_surface_dismiss">;
         conversationId: z.ZodString;
         surfaceId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"ui_surface_pending">;
+        conversationId: z.ZodString;
+        surfaceType: z.ZodLiteral<"visual">;
+        toolUseId: z.ZodString;
+        messageId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"ui_surface_show">;
         conversationId: z.ZodString;
@@ -2670,8 +2753,8 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     id: z.ZodString;
     conversationId: z.ZodString;
     status: z.ZodEnum<{
-        cancelled: "cancelled";
         completed: "completed";
+        cancelled: "cancelled";
         failed: "failed";
     }>;
     exitCode: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
@@ -2805,6 +2888,11 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     summaryCharCount: z.ZodOptional<z.ZodNumber>;
     summaryHeaderCount: z.ZodOptional<z.ZodNumber>;
     summaryHadMemoryEcho: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"context_window_usage">;
+    conversationId: z.ZodString;
+    tokens: z.ZodNumber;
+    maxTokens: z.ZodNumber;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"conversation_error">;
     conversationId: z.ZodString;
@@ -3338,9 +3426,15 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     title: z.ZodString;
     body: z.ZodString;
     deliveryId: z.ZodOptional<z.ZodString>;
+    correlationId: z.ZodOptional<z.ZodString>;
     deepLinkMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     targetGuardianPrincipalId: z.ZodOptional<z.ZodString>;
     silent: z.ZodOptional<z.ZodBoolean>;
+    remotePushDispatched: z.ZodOptional<z.ZodBoolean>;
+    remotePushPlatforms: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        ios: "ios";
+        android: "android";
+    }>>>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"oauth_connect_result">;
     success: z.ZodBoolean;
@@ -3611,6 +3705,34 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             mayRequireJavaScript: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
+    answeredQuestion: z.ZodOptional<z.ZodObject<{
+        requestId: z.ZodString;
+        questions: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            question: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            options: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                label: z.ZodString;
+                description: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            freeTextPlaceholder: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        responses: z.ZodArray<z.ZodObject<{
+            questionId: z.ZodString;
+            decision: z.ZodEnum<{
+                option: "option";
+                free_text: "free_text";
+                skipped: "skipped";
+            }>;
+            optionId: z.ZodOptional<z.ZodString>;
+            text: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        overall: z.ZodEnum<{
+            completed: "completed";
+            closed: "closed";
+        }>;
+    }, z.core.$strip>>;
     errorCode: z.ZodOptional<z.ZodString>;
     completedAt: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>, z.ZodObject<{
@@ -3639,6 +3761,12 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"ui_surface_dismiss">;
     conversationId: z.ZodString;
     surfaceId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ui_surface_pending">;
+    conversationId: z.ZodString;
+    surfaceType: z.ZodLiteral<"visual">;
+    toolUseId: z.ZodString;
+    messageId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"ui_surface_show">;
     conversationId: z.ZodString;
@@ -4482,10 +4610,42 @@ export declare function listConversations(limit?: number, conversationType?: Con
  */
 export declare function listInstalledSkills(): Promise<ResolvedSkillEntry[]>;
 
-declare const _LIVE_VOICE_SERVER_FRAME_TYPES: readonly ["ready", "busy", "speech_started", "utterance_end", "utterance_discarded", "stt_partial", "stt_final", "thinking", "assistant_text_delta", "tts_audio", "tts_done", "turn_cancelled", "minimize_room", "metrics", "archived", "error"];
+declare const _LIVE_VOICE_SERVER_FRAME_TYPES: readonly ["ready", "busy", "speech_started", "utterance_end", "utterance_discarded", "stt_partial", "stt_final", "thinking", "activity", "assistant_text_delta", "tts_audio", "tts_done", "turn_cancelled", "minimize_room", "metrics", "archived", "error"];
 
 declare const LIVE_VOICE_TURN_DETECTION_MODES: readonly ["manual", "server_vad"];
 
+/**
+ * What the assistant is doing inside a turn, as one short user-facing line.
+ *
+ * Exists because a live-voice turn can go silent for a long time while it
+ * works, and the surfaces that show the session (the iOS Live Activity, and
+ * the room) can otherwise only say "Thinking...". The label is composed here
+ * rather than by each surface for the same reason phase wording is composed
+ * once: the Live Activity has two independent drivers (this socket and an APNs
+ * push the daemon dispatches), they must carry identical content, and the only
+ * way to guarantee that is for both to be handed the same string.
+ *
+ * An empty `label` means "no current activity", which is what a turn's end
+ * sends. Emitted only on change, never per tool result.
+ */
+declare interface LiveVoiceActivityServerFrame extends LiveVoiceServerFrameBase {
+    readonly type: "activity";
+    readonly turnId: string;
+    readonly label: string;
+    /**
+     * The confirmation this turn is blocked on, when the label describes a wait
+     * rather than work in flight. Absent otherwise.
+     *
+     * It travels so that a surface outside the app — the Live Activity's
+     * Approve/Deny buttons — can answer the request it was drawn against rather
+     * than whatever is pending by the time the press lands. Content on a Lock
+     * Screen can be seconds old, and a decision is the one thing that must not
+     * be re-pointed when it is: the id lets a client drop a press aimed at a
+     * request already answered, timed out, or superseded.
+     */
+    readonly approvalRequestId?: string;
+}
+
 declare interface LiveVoiceArchivedServerFrame extends LiveVoiceServerFrameBase {
     readonly type: "archived";
     readonly conversationId: string;
@@ -4621,7 +4781,7 @@ declare interface LiveVoiceReadyServerFrame extends LiveVoiceServerFrameBase {
     readonly turnDetection?: LiveVoiceTurnDetectionMode;
 }
 
-export declare type LiveVoiceServerFrame = LiveVoiceReadyServerFrame | LiveVoiceBusyServerFrame | LiveVoiceSpeechStartedServerFrame | LiveVoiceUtteranceEndServerFrame | LiveVoiceUtteranceDiscardedServerFrame | LiveVoiceSttPartialServerFrame | LiveVoiceSttFinalServerFrame | LiveVoiceThinkingServerFrame | LiveVoiceAssistantTextDeltaServerFrame | LiveVoiceTtsAudioServerFrame | LiveVoiceTtsDoneServerFrame | LiveVoiceTurnCancelledServerFrame | LiveVoiceMinimizeRoomServerFrame | LiveVoiceMetricsServerFrame | LiveVoiceArchivedServerFrame | LiveVoiceErrorServerFrame;
+export declare type LiveVoiceServerFrame = LiveVoiceReadyServerFrame | LiveVoiceBusyServerFrame | LiveVoiceSpeechStartedServerFrame | LiveVoiceUtteranceEndServerFrame | LiveVoiceUtteranceDiscardedServerFrame | LiveVoiceSttPartialServerFrame | LiveVoiceSttFinalServerFrame | LiveVoiceThinkingServerFrame | LiveVoiceActivityServerFrame | LiveVoiceAssistantTextDeltaServerFrame | LiveVoiceTtsAudioServerFrame | LiveVoiceTtsDoneServerFrame | LiveVoiceTurnCancelledServerFrame | LiveVoiceMinimizeRoomServerFrame | LiveVoiceMetricsServerFrame | LiveVoiceArchivedServerFrame | LiveVoiceErrorServerFrame;
 
 declare interface LiveVoiceServerFrameBase {
     readonly type: LiveVoiceServerFrameType;
@@ -4849,7 +5009,10 @@ declare const messageMetadataSchema: z.ZodObject<{
     provenanceRequesterIdentifier: z.ZodOptional<z.ZodString>;
     automated: z.ZodOptional<z.ZodBoolean>;
     hidden: z.ZodOptional<z.ZodBoolean>;
+    voiceSessionTurn: z.ZodOptional<z.ZodBoolean>;
     messageKind: z.ZodOptional<z.ZodString>;
+    providerErrorCode: z.ZodOptional<z.ZodString>;
+    providerErrorCategory: z.ZodOptional<z.ZodString>;
     backgroundToolCompletion: z.ZodOptional<z.ZodObject<{
         id: z.ZodString;
         toolName: z.ZodString;
@@ -4857,8 +5020,8 @@ declare const messageMetadataSchema: z.ZodObject<{
         command: z.ZodString;
         startedAt: z.ZodNumber;
         status: z.ZodEnum<{
-            cancelled: "cancelled";
             completed: "completed";
+            cancelled: "cancelled";
             failed: "failed";
         }>;
         exitCode: z.ZodNullable<z.ZodNumber>;
@@ -5313,6 +5476,8 @@ declare interface ProcessEntry extends BaseSubscriberEntry {
 
 export declare interface Provider {
     name: string;
+    /** Connection route whose credentials this provider instance uses. */
+    routeAttribution?: ProviderRouteAttribution;
     /**
      * Provider key used by the local token estimator to select model-family
      * specific rules (e.g. Anthropic's `width * height / 750` image sizing).
@@ -5366,6 +5531,8 @@ export declare interface Provider {
     countInputTokens?(messages: Message[], systemPrompt: string, tools?: ToolDefinition_2[]): Promise<number>;
 }
 
+declare type ProviderCredentialSource = "byok" | "no-auth" | "oauth-subscription" | "vellum-managed";
+
 export declare type ProviderEvent = {
     type: "text_delta";
     text: string;
@@ -5436,6 +5603,18 @@ export declare interface ProviderResponse {
     rawResponse?: unknown;
 }
 
+declare interface ProviderRouteAttribution {
+    connectionName?: string;
+    profileName?: string;
+    isManagedRoute?: boolean;
+    /**
+     * Credential surface used for this request. Finer than `isManagedRoute`:
+     * it separates personal provider keys, keyless endpoints, and subscription
+     * logins from each other so error copy can name what the user must fix.
+     */
+    credentialSource?: ProviderCredentialSource;
+}
+
 /** Callback for proxy policy decisions requiring user confirmation. Returns true if approved. */
 declare type ProxyApprovalCallback = (request: ProxyApprovalRequest) => Promise<boolean>;
 
@@ -5532,7 +5711,7 @@ declare type ResolutionFallbackReason = "missing" | "disabled" | "incomplete";
  *   3. `llm.callSites[callSite].profile` (the call site's named profile)
  *   4. `CALL_SITE_DEFAULTS[callSite].profile` intent resolved through
  *      `llm.defaultProvider`
- *   5. balanced intent through `llm.defaultProvider` — the code-owned anchor
+ *   5. balanced intent through `llm.defaultProvider`: the code-owned anchor
  *      for profileless call sites, or when nothing above is usable
  *
  * A winner must carry its own `provider` AND `model`: the base layer's schema
@@ -6768,6 +6947,14 @@ export declare interface ToolExecutionResult {
     /** Structured activity metadata for client rendering (web search, web fetch, etc).
      *  Populated by daemon-internal tools; plugins must not set this. */
     activityMetadata?: ToolActivityMetadata;
+    /**
+     * Typed side channel from the `ask_question` executor to the agent loop: the
+     * questions asked and the answers the user gave. The loop forwards it on the
+     * `tool_result` event and persists it on the tool_use block, so the answered
+     * card renders live and survives a history reopen instead of the decision
+     * disappearing with the interactive prompt. Set only by `ask_question`.
+     */
+    answeredQuestion?: AnsweredQuestion;
 }
 
 export declare interface ToolResultContent {

package/package.json

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