@vellumai/plugin-api 0.10.11-dev.202607231339.c736cb7 → 0.10.11-dev.202607231450.b516b22

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;
@@ -1904,14 +1905,13 @@ declare interface ClientEntry extends BaseSubscriberEntry {
     actorPrincipalId?: string;
 }
 
-/** Sent by the daemon to update a client-side setting (e.g. activation key). */
-declare interface ClientSettingsUpdate {
-    type: "client_settings_update";
-    /** The setting key to update (e.g. "activationKey"). */
-    key: string;
-    /** The new value for the setting. */
-    value: string;
-}
+declare type ClientSettingsUpdateEvent = z.infer<typeof ClientSettingsUpdateEventSchema>;
+
+declare const ClientSettingsUpdateEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"client_settings_update">;
+    key: z.ZodString;
+    value: z.ZodString;
+}, z.core.$strip>;
 
 declare interface CliOptionHelp {
     /** Commander flag spec, e.g. `"--path <file>"` or `"-l, --limit <n>"`. */
@@ -1964,10 +1964,11 @@ declare const CompactionCircuitOpenEventSchema: z.ZodObject<{
 
 declare type _ComputerUseServerMessages = RecordingStartEvent | RecordingStopEvent | RecordingPauseEvent | RecordingResumeEvent;
 
-/** Sent by the daemon when workspace config.json changes on disk. */
-declare interface ConfigChanged {
-    type: "config_changed";
-}
+declare type ConfigChangedEvent = z.infer<typeof ConfigChangedEventSchema>;
+
+declare const ConfigChangedEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"config_changed">;
+}, z.core.$strip>;
 
 declare type ConfiguredProviderOptions = Pick<ResolveCallSiteOpts, "overrideProfile" | "forceOverrideProfile" | "selectionSeed">;
 
@@ -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,20 +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 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;
 
@@ -2545,13 +2512,15 @@ declare const DocumentCommentResolvedEventSchema: z.ZodObject<{
 
 declare type _DocumentCommentsServerMessages = DocumentCommentCreatedEvent | DocumentCommentResolvedEvent | DocumentCommentReopenedEvent | DocumentCommentDeletedEvent;
 
-declare interface DocumentEditorShow {
-    type: "document_editor_show";
-    conversationId: string;
-    surfaceId: string;
-    title: string;
-    initialContent: string;
-}
+declare type DocumentEditorShowEvent = z.infer<typeof DocumentEditorShowEventSchema>;
+
+declare const DocumentEditorShowEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"document_editor_show">;
+    conversationId: z.ZodString;
+    surfaceId: z.ZodString;
+    title: z.ZodString;
+    initialContent: z.ZodString;
+}, z.core.$strip>;
 
 declare type DocumentEditorUpdateEvent = z.infer<typeof DocumentEditorUpdateEventSchema>;
 
@@ -2563,31 +2532,6 @@ declare const DocumentEditorUpdateEventSchema: z.ZodObject<{
     mode: z.ZodString;
 }, z.core.$strip>;
 
-declare interface DocumentListResponse {
-    type: "document_list_response";
-    documents: Array<{
-        surfaceId: string;
-        conversationId: string;
-        title: string;
-        wordCount: number;
-        createdAt: number;
-        updatedAt: number;
-    }>;
-}
-
-declare interface DocumentLoadResponse {
-    type: "document_load_response";
-    surfaceId: string;
-    conversationId: string;
-    title: string;
-    content: string;
-    wordCount: number;
-    createdAt: number;
-    updatedAt: number;
-    success: boolean;
-    error?: string;
-}
-
 declare type DocumentPreviewSurfaceData = z.infer<typeof DocumentPreviewSurfaceDataSchema>;
 
 declare const DocumentPreviewSurfaceDataSchema: z.ZodObject<{
@@ -2598,14 +2542,7 @@ declare const DocumentPreviewSurfaceDataSchema: z.ZodObject<{
     mimeType: z.ZodCatch<z.ZodOptional<z.ZodString>>;
 }, z.core.$strip>;
 
-declare interface DocumentSaveResponse {
-    type: "document_save_response";
-    surfaceId: string;
-    success: boolean;
-    error?: string;
-}
-
-declare type _DocumentsServerMessages = DocumentEditorShow | DocumentEditorUpdateEvent | DocumentSaveResponse | DocumentLoadResponse | DocumentListResponse;
+declare type _DocumentsServerMessages = DocumentEditorShowEvent | DocumentEditorUpdateEvent;
 
 /**
  * Whether the given model or profile can process image input.
@@ -2789,15 +2726,6 @@ declare const FormSurfaceDataSchema: z.ZodObject<{
     }>>>;
 }, z.core.$strip>;
 
-/** Response to a generate_avatar request indicating success or failure. */
-declare interface GenerateAvatarResponse {
-    type: "generate_avatar_response";
-    /** Whether the avatar was generated successfully. */
-    success: boolean;
-    /** Error message when success is false. */
-    error?: string;
-}
-
 declare type GenerationCancelledEvent = z.infer<typeof GenerationCancelledEventSchema>;
 
 declare const GenerationCancelledEventSchema: z.ZodObject<{
@@ -2904,67 +2832,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>;
 
@@ -4452,6 +4319,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>;
 
@@ -5620,7 +5497,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 | _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";
@@ -5653,7 +5530,7 @@ declare const ServiceGroupUpdateStartingEventSchema: z.ZodObject<{
     expectedDowntimeSeconds: z.ZodNumber;
 }, z.core.$strip>;
 
-declare type _SettingsServerMessages = ClientSettingsUpdate | AvatarUpdatedEvent | ConfigChanged | SoundsConfigUpdated | GenerateAvatarResponse;
+declare type _SettingsServerMessages = ClientSettingsUpdateEvent | AvatarUpdatedEvent | ConfigChangedEvent | SoundsConfigUpdatedEvent;
 
 declare interface ShareAppCloudResponse {
     type: "share_app_cloud_response";
@@ -5874,10 +5751,11 @@ declare interface SlimSkillBase {
 
 declare type SlimSkillResponse = VellumSlimSkill | ClawhubSlimSkill | SkillsshSlimSkill | CustomSlimSkill | AssistantMemorySlimSkill;
 
-/** Sent by the daemon when sounds config or sound files change on disk. */
-declare interface SoundsConfigUpdated {
-    type: "sounds_config_updated";
-}
+declare type SoundsConfigUpdatedEvent = z.infer<typeof SoundsConfigUpdatedEventSchema>;
+
+declare const SoundsConfigUpdatedEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"sounds_config_updated">;
+}, z.core.$strip>;
 
 /**
  * The full `stop` context a hook receives — the dispatching call site's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/plugin-api",
-  "version": "0.10.11-dev.202607231339.c736cb7",
+  "version": "0.10.11-dev.202607231450.b516b22",
   "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"