@vellumai/plugin-api 0.10.11-dev.202607231339.c736cb7 → 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;
@@ -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;
 
@@ -2904,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>;
 
@@ -4452,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>;
 
@@ -5620,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 | _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.202607231339.c736cb7",
+  "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"