@vellumai/plugin-api 0.10.11-dev.202607231240.e03ec0b → 0.10.11-dev.202607231425.01b751a

package/app.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Ambient global types for the **app-side** Vellum bridge — `window.vellum`.
+ *
+ * A Vellum plugin app runs inside a sandboxed iframe, and the host injects a
+ * `window.vellum` object into it at load time (see the assistant's
+ * `sandbox-bridge` runtime). This file is the type-only counterpart to that
+ * injection: it teaches TypeScript the shape of `window.vellum` so an app can
+ * call `window.vellum.fetch(...)` without hand-declaring the global in every
+ * project.
+ *
+ * Only `fetch` is typed for now — the surface the vast majority of apps
+ * actually use. Other injected members are intentionally left undeclared until
+ * there's a concrete need.
+ *
+ * A plugin app that depends on `@vellumai/plugin-api` pulls this in via a
+ * one-line reference (recommended — no runtime import, which apps can't rely
+ * on inside the sandbox):
+ *
+ * ```ts
+ * /// <reference types="@vellumai/plugin-api/app" />
+ * ```
+ *
+ * or by adding `"@vellumai/plugin-api/app"` to `compilerOptions.types` in
+ * `tsconfig.json`. Either way the app no longer needs its own `vellum.d.ts`.
+ *
+ * The named types below are also exported, so app code that wants to annotate
+ * a variable can `import type { VellumAppBridge } from "@vellumai/plugin-api/app"`.
+ */
+
+/**
+ * Request init accepted by {@link VellumAppBridge.fetch}. A subset of the DOM
+ * `RequestInit`: the bridge serializes the request across `postMessage`, so
+ * `headers` must be a plain object and `body` a string (not a `Headers`
+ * instance, `FormData`, or a stream).
+ */
+export interface VellumAppFetchInit {
+  /** HTTP method. Defaults to `"GET"`. */
+  method?: string;
+  /** Request headers as a plain object. */
+  headers?: Record<string, string>;
+  /** Request body. Already-serialized string payloads only. */
+  body?: string | null;
+}
+
+/**
+ * Response returned by {@link VellumAppBridge.fetch}. A `fetch`-like subset,
+ * not a full DOM `Response`: the body is delivered as text across the bridge,
+ * so only `json()` and `text()` are available (no `blob()`, `body`, etc.).
+ */
+export interface VellumAppFetchResponse {
+  /** True when `status` is in the 2xx range. */
+  ok: boolean;
+  status: number;
+  statusText: string;
+  /** Response headers as a plain object. */
+  headers: Record<string, string>;
+  /** Parse the response body as JSON. */
+  json(): Promise<unknown>;
+  /** Read the response body as text. */
+  text(): Promise<string>;
+}
+
+/**
+ * The `window.vellum` bridge the host injects into a plugin app's sandboxed
+ * iframe. Mirrors the runtime built by the assistant's `sandbox-bridge`.
+ */
+export interface VellumAppBridge {
+  /**
+   * Authenticated `fetch` to the app's own custom routes under `/v1/x/` (a
+   * leading `/x/` is accepted and normalized). Proxied through the host so the
+   * assistant's session/auth is attached — use this instead of the bare
+   * global `fetch`, which fails from the sandboxed origin.
+   */
+  fetch(
+    path: string,
+    options?: VellumAppFetchInit,
+  ): Promise<VellumAppFetchResponse>;
+}
+
+declare global {
+  interface Window {
+    vellum: VellumAppBridge;
+  }
+}

package/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference path="./app.d.ts" />
 import { z } from 'zod';
 
 declare type _AcpServerMessages = AcpSessionSpawnedEvent | AcpSessionUpdateEvent | AcpSessionCompletedEvent | AcpSessionErrorEvent | AcpSessionUsageEvent;
@@ -1962,7 +1963,7 @@ declare const CompactionCircuitOpenEventSchema: z.ZodObject<{
     openUntil: z.ZodNumber;
 }, z.core.$strip>;
 
-declare type _ComputerUseServerMessages = RecordingStart | RecordingStop | RecordingPause | RecordingResume;
+declare type _ComputerUseServerMessages = RecordingStartEvent | RecordingStopEvent | RecordingPauseEvent | RecordingResumeEvent;
 
 /** Sent by the daemon when workspace config.json changes on disk. */
 declare interface ConfigChanged {
@@ -2051,33 +2052,6 @@ declare const ConfirmationSurfaceDataSchema: z.ZodObject<{
     destructive: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
 }, z.core.$strip>;
 
-declare interface ContactChannelPayload {
-    id: string;
-    type: string;
-    address: string;
-    isPrimary: boolean;
-    status: string;
-    policy: string;
-    verifiedAt?: number;
-    verifiedVia?: string;
-    lastSeenAt?: number;
-    interactionCount?: number;
-    lastInteraction?: number;
-    revokedReason?: string;
-    blockedReason?: string;
-}
-
-declare interface ContactPayload {
-    id: string;
-    displayName: string;
-    role: "guardian" | "contact";
-    notes?: string;
-    contactType?: string;
-    lastInteraction?: number;
-    interactionCount: number;
-    channels: ContactChannelPayload[];
-}
-
 declare type ContactRequestEvent = z.infer<typeof ContactRequestEventSchema>;
 
 declare const ContactRequestEventSchema: z.ZodObject<{
@@ -2090,51 +2064,13 @@ declare const ContactRequestEventSchema: z.ZodObject<{
     role: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 
-/** Server push — lightweight invalidation signal: the contacts table has been mutated, refetch your list. */
-declare interface ContactsChanged {
-    type: "contacts_changed";
-}
+declare type ContactsChangedEvent = z.infer<typeof ContactsChangedEventSchema>;
 
-declare interface ContactsInviteResponse {
-    type: "contacts_invite_response";
-    success: boolean;
-    error?: string;
-    /** Single invite (returned on create/revoke). Token field is only present on create. */
-    invite?: {
-        id: string;
-        sourceChannel: string;
-        token?: string;
-        tokenHash: string;
-        maxUses: number;
-        useCount: number;
-        expiresAt: number | null;
-        status: string;
-        note?: string;
-        createdAt: number;
-    };
-    /** List of invites (returned on list). */
-    invites?: Array<{
-        id: string;
-        sourceChannel: string;
-        tokenHash: string;
-        maxUses: number;
-        useCount: number;
-        expiresAt: number | null;
-        status: string;
-        note?: string;
-        createdAt: number;
-    }>;
-}
-
-declare interface ContactsResponse {
-    type: "contacts_response";
-    success: boolean;
-    error?: string;
-    contact?: ContactPayload;
-    contacts?: ContactPayload[];
-}
+declare const ContactsChangedEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"contacts_changed">;
+}, z.core.$strip>;
 
-declare type _ContactsServerMessages = ContactsResponse | ContactsChanged | ContactRequestEvent;
+declare type _ContactsServerMessages = ContactsChangedEvent | ContactRequestEvent;
 
 export declare type ContentBlock = TextContent | ThinkingContent | RedactedThinkingContent | ImageContent | FileContent | ToolUseContent | ToolResultContent | ServerToolUseContent | WebSearchToolResultContent;
 
@@ -2484,17 +2420,6 @@ declare interface CustomSlimSkill extends SlimSkillBase {
  */
 export declare function deleteConversation(id: string): Promise<void>;
 
-declare type _DiagnosticsServerMessages = EnvVarsResponse | DictationResponse;
-
-declare interface DictationResponse {
-    type: "dictation_response";
-    text: string;
-    mode: "dictation" | "command" | "action";
-    actionPlan?: string;
-    resolvedProfileId?: string;
-    profileSource?: "request" | "app_mapping" | "default" | "fallback";
-}
-
 declare interface DiffInfo {
     filePath: string;
     oldContent: string;
@@ -2707,11 +2632,6 @@ declare type EmbeddingInput = string | MultimodalEmbeddingInput;
  */
 declare type EmbeddingTargetType = Parameters<embedAndUpsert_2>[1];
 
-declare interface EnvVarsResponse {
-    type: "env_vars_response";
-    vars: Record<string, string>;
-}
-
 declare type ErrorEvent_2 = z.infer<typeof ErrorEventSchema>;
 
 declare const ErrorEventSchema: z.ZodObject<{
@@ -2951,67 +2871,6 @@ declare interface GraphNodeSweepResult {
     deleted: number;
 }
 
-declare interface GuardianActionDecisionResponse {
-    type: "guardian_action_decision_response";
-    applied: boolean;
-    reason?: string;
-    resolverFailureReason?: string;
-    requestId?: string;
-    userText?: string;
-    /** Resolver reply text for the guardian (e.g. verification code for access requests). */
-    replyText?: string;
-}
-
-declare interface GuardianActionsPendingResponse {
-    type: "guardian_actions_pending_response";
-    conversationId: string;
-    prompts: GuardianDecisionPrompt[];
-}
-
-declare type _GuardianActionsServerMessages = GuardianActionsPendingResponse | GuardianActionDecisionResponse;
-
-declare interface GuardianDecisionAction {
-    /** Canonical action identifier. */
-    action: string;
-    /** Human-readable label for the action. */
-    label: string;
-    /** Short explanation shown in rich-UI legends (Telegram, Slack). */
-    description?: string;
-}
-
-/**
- * Shared types and render helpers for guardian decision prompts: the prompt
- * model shown to guardians, the canonical action constants, and the
- * legend/fallback builders used to present them on rich and plain-text channels.
- */
-/** Structured model for prompts shown to guardians. */
-declare interface GuardianDecisionPrompt {
-    requestId: string;
-    /** Short human-readable code for the request. */
-    requestCode: string;
-    state: "pending" | "followup_awaiting_choice" | "expired_superseded_with_active_call";
-    questionText: string;
-    toolName: string | null;
-    actions: GuardianDecisionAction[];
-    expiresAt: number;
-    conversationId: string;
-    callSessionId: string | null;
-    /**
-     * Guardian request kind (e.g. 'tool_approval', 'pending_question').
-     * Present when the prompt originates from the guardian request
-     * store. Absent for legacy-only prompts.
-     */
-    kind?: string;
-    /** Human-readable preview of the command being approved (e.g. shell command). */
-    commandPreview?: string;
-    /** Risk level label for the request (e.g. 'low', 'medium', 'high'). */
-    riskLevel?: string;
-    /** Short activity description for richer prompt display. */
-    activityText?: string;
-    /** Where the tool will execute — sandbox or host. */
-    executionTarget?: "sandbox" | "host";
-}
-
 /** Whether the text tokenizes to at least one lexical search token. */
 export declare function hasLexicalTokens(text: string): Promise<boolean>;
 
@@ -3599,8 +3458,6 @@ declare interface ImageEmbeddingInput {
     mimeType: string;
 }
 
-declare type _InboxServerMessages = ContactsInviteResponse;
-
 declare interface IngressConfigResponse {
     type: "ingress_config_response";
     enabled: boolean;
@@ -4401,37 +4258,18 @@ declare const NavigateSettingsEventSchema: z.ZodObject<{
     tab: z.ZodString;
 }, z.core.$strip>;
 
-/** Server push — broadcast when a notification creates a new vellum conversation. */
-declare interface NotificationConversationCreated {
-    type: "notification_conversation_created";
-    conversationId: string;
-    title: string;
-    sourceEventName: string;
-    /**
-     * When set, this conversation was created for a guardian-sensitive notification
-     * and should only be surfaced by clients bound to this guardian identity.
-     */
-    targetGuardianPrincipalId?: string;
-    /**
-     * Conversation group identifier propagated from the signal producer.
-     * Clients use this to place the conversation in the correct sidebar folder
-     * (e.g. "system:scheduled" for schedule completion threads).
-     */
-    groupId?: string;
-    /**
-     * Semantic source of the conversation (e.g. "schedule", "reminder").
-     * Allows clients to override the default "notification" source so the
-     * conversation is attributed correctly.
-     */
-    source?: string;
-    /**
-     * Mirrors `NotificationIntent.silent`. When true the client must not
-     * post a fallback OS banner for this conversation — the sidebar entry
-     * still appears, but the always-on inbox is the only surfaced channel.
-     * Derived from the originating signal's `attentionHints.urgency`.
-     */
-    silent?: boolean;
-}
+declare type NotificationConversationCreatedEvent = z.infer<typeof NotificationConversationCreatedEventSchema>;
+
+declare const NotificationConversationCreatedEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"notification_conversation_created">;
+    conversationId: z.ZodString;
+    title: z.ZodString;
+    sourceEventName: z.ZodString;
+    targetGuardianPrincipalId: z.ZodOptional<z.ZodString>;
+    groupId: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodString>;
+    silent: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
 
 declare type NotificationIntentEvent = z.infer<typeof NotificationIntentEventSchema>;
 
@@ -4446,7 +4284,7 @@ declare const NotificationIntentEventSchema: z.ZodObject<{
     silent: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 
-declare type _NotificationsServerMessages = NotificationIntentEvent | NotificationConversationCreated;
+declare type _NotificationsServerMessages = NotificationIntentEvent | NotificationConversationCreatedEvent;
 
 declare interface OAuthConnectResultResponse {
     type: "oauth_connect_result";
@@ -4520,6 +4358,16 @@ declare const OpenPanelEventSchema: z.ZodObject<{
  * `start` / `sendAudio` / `stop`, or `null` when no streaming session can be
  * opened — the provider is unknown, has no streaming adapter, or is missing
  * credentials.
+ *
+ * The STT resolver is imported lazily at call time, mirroring
+ * `runConversationTurn`: plugin-api facades must not statically pull deep
+ * daemon subsystems into the barrel's module graph. The static import here
+ * dragged ~75 provider/STT modules into `plugin-api/index.ts` evaluation,
+ * and in the compiled binary that surfaced as a TDZ `ReferenceError`
+ * ("Cannot access 'openTranscriptionSession' before initialization") when a
+ * plugin touched the binding through the workspace shim. With the lazy
+ * import this module has no static value imports at all, so the barrel
+ * binding initializes trivially and the daemon graph loads on first use.
  */
 export declare function openTranscriptionSession(): Promise<StreamingTranscriber | null>;
 
@@ -5125,43 +4973,46 @@ declare const QuestionRequestEventSchema: z.ZodObject<{
     toolUseId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 
-/** Recording options shared across standalone and CU recording flows. */
-declare interface RecordingOptions {
-    captureScope?: "display" | "window";
-    displayId?: string;
-    windowId?: number;
-    includeAudio?: boolean;
-    includeMicrophone?: boolean;
-    promptForSource?: boolean;
-}
+declare type RecordingPauseEvent = z.infer<typeof RecordingPauseEventSchema>;
 
-/** Server → Client: pause the active recording. */
-declare interface RecordingPause {
-    type: "recording_pause";
-    recordingId: string;
-}
+declare const RecordingPauseEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"recording_pause">;
+    recordingId: z.ZodString;
+}, z.core.$strip>;
 
-/** Server → Client: resume a paused recording. */
-declare interface RecordingResume {
-    type: "recording_resume";
-    recordingId: string;
-}
+declare type RecordingResumeEvent = z.infer<typeof RecordingResumeEventSchema>;
 
-/** Server → Client: start a recording. */
-declare interface RecordingStart {
-    type: "recording_start";
-    recordingId: string;
-    attachToConversationId?: string;
-    options?: RecordingOptions;
-    /** Operation token for restart race hardening — stale completions with mismatched tokens are rejected. */
-    operationToken?: string;
-}
+declare const RecordingResumeEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"recording_resume">;
+    recordingId: z.ZodString;
+}, z.core.$strip>;
 
-/** Server → Client: stop a recording. */
-declare interface RecordingStop {
-    type: "recording_stop";
-    recordingId: string;
-}
+declare type RecordingStartEvent = z.infer<typeof RecordingStartEventSchema>;
+
+declare const RecordingStartEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"recording_start">;
+    recordingId: z.ZodString;
+    attachToConversationId: z.ZodOptional<z.ZodString>;
+    options: z.ZodOptional<z.ZodObject<{
+        captureScope: z.ZodOptional<z.ZodEnum<{
+            display: "display";
+            window: "window";
+        }>>;
+        displayId: z.ZodOptional<z.ZodString>;
+        windowId: z.ZodOptional<z.ZodNumber>;
+        includeAudio: z.ZodOptional<z.ZodBoolean>;
+        includeMicrophone: z.ZodOptional<z.ZodBoolean>;
+        promptForSource: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    operationToken: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+
+declare type RecordingStopEvent = z.infer<typeof RecordingStopEventSchema>;
+
+declare const RecordingStopEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"recording_stop">;
+    recordingId: z.ZodString;
+}, z.core.$strip>;
 
 export declare interface RedactedThinkingContent {
     type: "redacted_thinking";
@@ -5685,7 +5536,7 @@ declare interface SensitiveOutputBinding {
 
 declare type SensitiveOutputKind = "invite_code";
 
-declare type ServerMessage = _ConversationsServerMessages | _MessagesServerMessages | _SurfacesServerMessages | _SkillsServerMessages | _AppsServerMessages | _IntegrationsServerMessages | _ComputerUseServerMessages | _ContactsServerMessages | _SubagentsServerMessages | _DocumentsServerMessages | _DocumentCommentsServerMessages | _GuardianActionsServerMessages | _SyncInvalidationServerMessages | _HomeServerMessages | _HostAppControlServerMessages | _HostBashServerMessages | _HostBrowserServerMessages | _HostCuServerMessages | _HostFileServerMessages | _HostTransferServerMessages | _HostUiSnapshotServerMessages | _MemoryServerMessages | _WorkspaceServerMessages | _SchedulesServerMessages | _SettingsServerMessages | _DiagnosticsServerMessages | _InboxServerMessages | _NotificationsServerMessages | _UpgradesServerMessages | _AcpServerMessages | _BackgroundToolsServerMessages | _BookmarksServerMessages | _WorkflowsServerMessages | DiskPressureStatusChangedEvent | HookEvent | SubagentEvent;
+declare type ServerMessage = _ConversationsServerMessages | _MessagesServerMessages | _SurfacesServerMessages | _SkillsServerMessages | _AppsServerMessages | _IntegrationsServerMessages | _ComputerUseServerMessages | _ContactsServerMessages | _SubagentsServerMessages | _DocumentsServerMessages | _DocumentCommentsServerMessages | _SyncInvalidationServerMessages | _HomeServerMessages | _HostAppControlServerMessages | _HostBashServerMessages | _HostBrowserServerMessages | _HostCuServerMessages | _HostFileServerMessages | _HostTransferServerMessages | _HostUiSnapshotServerMessages | _MemoryServerMessages | _WorkspaceServerMessages | _SchedulesServerMessages | _SettingsServerMessages | _NotificationsServerMessages | _UpgradesServerMessages | _AcpServerMessages | _BackgroundToolsServerMessages | _BookmarksServerMessages | _WorkflowsServerMessages | DiskPressureStatusChangedEvent | HookEvent | SubagentEvent;
 
 export declare interface ServerToolUseContent {
     type: "server_tool_use";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/plugin-api",
-  "version": "0.10.11-dev.202607231240.e03ec0b",
+  "version": "0.10.11-dev.202607231425.01b751a",
   "description": "Public TypeScript authoring contract for Vellum assistant plugins.",
   "license": "MIT",
   "type": "module",
@@ -11,11 +11,15 @@
       "types": "./index.d.ts",
       "import": "./index.js",
       "default": "./index.js"
+    },
+    "./app": {
+      "types": "./app.d.ts"
     }
   },
   "files": [
     "index.js",
-    "index.d.ts"
+    "index.d.ts",
+    "app.d.ts"
   ],
   "dependencies": {
     "zod": "4.3.6"