@vellumai/plugin-api 0.11.4-staging.4 → 0.11.5-staging.1

package/index.d.ts

@@ -127,9 +127,9 @@ declare const AssistantConfigSchema: z.ZodObject<{
         inference: z.ZodDefault<z.ZodObject<{}, z.core.$strip>>;
         "image-generation": z.ZodDefault<z.ZodObject<{
             provider: z.ZodDefault<z.ZodEnum<{
+                vellum: "vellum";
                 openai: "openai";
                 gemini: "gemini";
-                vellum: "vellum";
             }>>;
             model: z.ZodDefault<z.ZodString>;
         }, z.core.$strip>>;
@@ -601,9 +601,9 @@ declare const AssistantConfigSchema: z.ZodObject<{
                 low: "low";
                 medium: "medium";
                 high: "high";
+                none: "none";
                 xhigh: "xhigh";
                 max: "max";
-                none: "none";
             }>>;
             speed: z.ZodOptional<z.ZodEnum<{
                 standard: "standard";
@@ -723,9 +723,9 @@ declare const AssistantConfigSchema: z.ZodObject<{
                 low: "low";
                 medium: "medium";
                 high: "high";
+                none: "none";
                 xhigh: "xhigh";
                 max: "max";
-                none: "none";
             }>>;
             speed: z.ZodOptional<z.ZodEnum<{
                 standard: "standard";
@@ -1171,8 +1171,8 @@ declare const AssistantConfigSchema: z.ZodObject<{
     plugins: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     pluginUpdates: z.ZodDefault<z.ZodObject<{
         mode: z.ZodDefault<z.ZodEnum<{
-            auto: "auto";
             manual: "manual";
+            auto: "auto";
         }>>;
         strategy: z.ZodDefault<z.ZodEnum<{
             theirs: "theirs";
@@ -1240,12 +1240,12 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         type: z.ZodLiteral<"acp_session_update">;
         acpSessionId: z.ZodString;
         updateType: z.ZodEnum<{
+            plan: "plan";
             agent_message_chunk: "agent_message_chunk";
             agent_thought_chunk: "agent_thought_chunk";
             user_message_chunk: "user_message_chunk";
             tool_call: "tool_call";
             tool_call_update: "tool_call_update";
-            plan: "plan";
         }>;
         content: z.ZodOptional<z.ZodString>;
         toolCallId: z.ZodOptional<z.ZodString>;
@@ -1331,8 +1331,8 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         id: z.ZodString;
         conversationId: z.ZodString;
         status: z.ZodEnum<{
-            completed: "completed";
             cancelled: "cancelled";
+            completed: "completed";
             failed: "failed";
         }>;
         exitCode: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
@@ -1424,18 +1424,18 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         conversationId: z.ZodString;
         requestId: z.ZodString;
         state: z.ZodEnum<{
-            timed_out: "timed_out";
             pending: "pending";
             approved: "approved";
             denied: "denied";
+            timed_out: "timed_out";
             resolved_stale: "resolved_stale";
         }>;
         source: z.ZodEnum<{
+            timeout: "timeout";
             system: "system";
             button: "button";
             inline_nl: "inline_nl";
             auto_deny: "auto_deny";
-            timeout: "timeout";
         }>;
         causedByRequestId: z.ZodOptional<z.ZodString>;
         decisionText: z.ZodOptional<z.ZodString>;
@@ -1510,9 +1510,9 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"conversation_list_invalidated">;
         reason: z.ZodEnum<{
+            deleted: "deleted";
             created: "created";
             renamed: "renamed";
-            deleted: "deleted";
             reordered: "reordered";
             seen_changed: "seen_changed";
         }>;
@@ -1555,9 +1555,9 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
             enabled: z.ZodBoolean;
             state: z.ZodEnum<{
                 unknown: "unknown";
+                ok: "ok";
                 disabled: "disabled";
                 critical: "critical";
-                ok: "ok";
                 warning: "warning";
             }>;
             locked: z.ZodBoolean;
@@ -1672,8 +1672,8 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         hookName: z.ZodString;
         owner: z.ZodObject<{
             kind: z.ZodEnum<{
-                plugin: "plugin";
                 workspace: "workspace";
+                plugin: "plugin";
             }>;
             id: z.ZodString;
         }, z.core.$strip>;
@@ -1865,9 +1865,9 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         requestId: z.ZodString;
         conversationId: z.ZodString;
         state: z.ZodEnum<{
+            approved: "approved";
             cancelled: "cancelled";
             superseded: "superseded";
-            approved: "approved";
             rejected: "rejected";
             answered: "answered";
         }>;
@@ -2091,6 +2091,25 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"relationship_state_updated">;
         updatedAt: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"resource_pressure_status_changed">;
+        status: z.ZodObject<{
+            enabled: z.ZodBoolean;
+            state: z.ZodEnum<{
+                unknown: "unknown";
+                ok: "ok";
+                disabled: "disabled";
+                elevated: "elevated";
+            }>;
+            cpuPercent: z.ZodNullable<z.ZodNumber>;
+            memoryPercent: z.ZodNullable<z.ZodNumber>;
+            cpuElevated: z.ZodBoolean;
+            memoryElevated: z.ZodBoolean;
+            cpuThresholdPercent: z.ZodNumber;
+            memoryThresholdPercent: z.ZodNumber;
+            lastCheckedAt: z.ZodNullable<z.ZodString>;
+            error: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"schedule_conversation_created">;
         conversationId: z.ZodString;
@@ -2160,9 +2179,9 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         type: z.ZodLiteral<"subagent_status_changed">;
         subagentId: z.ZodString;
         status: z.ZodEnum<{
+            pending: "pending";
             completed: "completed";
             failed: "failed";
-            pending: "pending";
             running: "running";
             awaiting_input: "awaiting_input";
             aborted: "aborted";
@@ -2605,6 +2624,12 @@ export declare class AssistantEventHub {
      * matched.
      */
     setClientPresence(clientId: string, state: DesktopPresenceState): boolean;
+    /**
+     * Record the web tab visibility/focused-conversation reported by a client.
+     * `reportedAt` always advances. Returns true when at least one active
+     * client entry matched.
+     */
+    setClientWebPresence(clientId: string, report: WebPresenceReport): boolean;
     /**
      * Force-disconnect a client by disposing all subscribers for the given
      * `clientId`. Returns the number of disposed entries.
@@ -2636,15 +2661,16 @@ declare const AssistantEventPublishOptionsSchema: z.ZodObject<{
     }>>;
     targetClientId: z.ZodOptional<z.ZodString>;
     targetInterfaceId: z.ZodOptional<z.ZodEnum<{
-        plugin: "plugin";
-        telegram: "telegram";
         phone: "phone";
+        a2a: "a2a";
         whatsapp: "whatsapp";
+        discord: "discord";
+        telegram: "telegram";
         slack: "slack";
         email: "email";
-        a2a: "a2a";
-        discord: "discord";
+        plugin: "plugin";
         macos: "macos";
+        windows: "windows";
         ios: "ios";
         cli: "cli";
         web: "web";
@@ -2698,12 +2724,12 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"acp_session_update">;
     acpSessionId: z.ZodString;
     updateType: z.ZodEnum<{
+        plan: "plan";
         agent_message_chunk: "agent_message_chunk";
         agent_thought_chunk: "agent_thought_chunk";
         user_message_chunk: "user_message_chunk";
         tool_call: "tool_call";
         tool_call_update: "tool_call_update";
-        plan: "plan";
     }>;
     content: z.ZodOptional<z.ZodString>;
     toolCallId: z.ZodOptional<z.ZodString>;
@@ -2789,8 +2815,8 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     id: z.ZodString;
     conversationId: z.ZodString;
     status: z.ZodEnum<{
-        completed: "completed";
         cancelled: "cancelled";
+        completed: "completed";
         failed: "failed";
     }>;
     exitCode: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
@@ -2882,18 +2908,18 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     conversationId: z.ZodString;
     requestId: z.ZodString;
     state: z.ZodEnum<{
-        timed_out: "timed_out";
         pending: "pending";
         approved: "approved";
         denied: "denied";
+        timed_out: "timed_out";
         resolved_stale: "resolved_stale";
     }>;
     source: z.ZodEnum<{
+        timeout: "timeout";
         system: "system";
         button: "button";
         inline_nl: "inline_nl";
         auto_deny: "auto_deny";
-        timeout: "timeout";
     }>;
     causedByRequestId: z.ZodOptional<z.ZodString>;
     decisionText: z.ZodOptional<z.ZodString>;
@@ -2968,9 +2994,9 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"conversation_list_invalidated">;
     reason: z.ZodEnum<{
+        deleted: "deleted";
         created: "created";
         renamed: "renamed";
-        deleted: "deleted";
         reordered: "reordered";
         seen_changed: "seen_changed";
     }>;
@@ -3013,9 +3039,9 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         enabled: z.ZodBoolean;
         state: z.ZodEnum<{
             unknown: "unknown";
+            ok: "ok";
             disabled: "disabled";
             critical: "critical";
-            ok: "ok";
             warning: "warning";
         }>;
         locked: z.ZodBoolean;
@@ -3130,8 +3156,8 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     hookName: z.ZodString;
     owner: z.ZodObject<{
         kind: z.ZodEnum<{
-            plugin: "plugin";
             workspace: "workspace";
+            plugin: "plugin";
         }>;
         id: z.ZodString;
     }, z.core.$strip>;
@@ -3323,9 +3349,9 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     requestId: z.ZodString;
     conversationId: z.ZodString;
     state: z.ZodEnum<{
+        approved: "approved";
         cancelled: "cancelled";
         superseded: "superseded";
-        approved: "approved";
         rejected: "rejected";
         answered: "answered";
     }>;
@@ -3549,6 +3575,25 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"relationship_state_updated">;
     updatedAt: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"resource_pressure_status_changed">;
+    status: z.ZodObject<{
+        enabled: z.ZodBoolean;
+        state: z.ZodEnum<{
+            unknown: "unknown";
+            ok: "ok";
+            disabled: "disabled";
+            elevated: "elevated";
+        }>;
+        cpuPercent: z.ZodNullable<z.ZodNumber>;
+        memoryPercent: z.ZodNullable<z.ZodNumber>;
+        cpuElevated: z.ZodBoolean;
+        memoryElevated: z.ZodBoolean;
+        cpuThresholdPercent: z.ZodNumber;
+        memoryThresholdPercent: z.ZodNumber;
+        lastCheckedAt: z.ZodNullable<z.ZodString>;
+        error: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"schedule_conversation_created">;
     conversationId: z.ZodString;
@@ -3618,9 +3663,9 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"subagent_status_changed">;
     subagentId: z.ZodString;
     status: z.ZodEnum<{
+        pending: "pending";
         completed: "completed";
         failed: "failed";
-        pending: "pending";
         running: "running";
         awaiting_input: "awaiting_input";
         aborted: "aborted";
@@ -4107,6 +4152,11 @@ declare interface ClientEntry extends BaseSubscriberEntry {
      * In-memory only, so consumers must fail open when it is absent.
      */
     presence?: ClientPresence;
+    /**
+     * Last web tab visibility/focus reported by this client, for clients that
+     * report it. In-memory only, so consumers must fail open when it is absent.
+     */
+    webPresence?: ClientWebPresence;
 }
 
 declare interface ClientPresence {
@@ -4115,6 +4165,11 @@ declare interface ClientPresence {
     reportedAt: Date;
 }
 
+declare interface ClientWebPresence extends WebPresenceReport {
+    /** When the daemon last heard from the client. Drives staleness. */
+    reportedAt: Date;
+}
+
 declare interface CliOptionHelp {
     /** Commander flag spec, e.g. `"--path <file>"` or `"-l, --limit <n>"`. */
     flags: string;
@@ -4284,13 +4339,14 @@ export declare function createLiveVoiceConnection(options: {
  *
  * ## Plugin scoping
  *
- * When a plugin is in context — its hook or tool is executing, tracked by
- * {@link ../plugins/plugin-execution-context.getCurrentPluginName} — resolution
- * is restricted: the plugin may only resolve credentials whose `field` equals
- * the plugin's own manifest name. A plugin named `acme` can therefore read
- * `openai/acme` or `stripe/acme` but not `openai/api_key`. Outside any plugin
- * context (host-internal callers, CLI, tests) the resolver is unscoped and
- * behaves like a direct reveal.
+ * When a plugin is in context (its hook, tool, or one of its own
+ * `/x/plugins/<name>/` routes is executing, tracked by
+ * {@link ../plugins/plugin-execution-context.getCurrentPluginName}), resolution
+ * is restricted: the plugin may only resolve credentials whose `service`
+ * equals its manifest name (`imessage/api_key` for plugin `imessage`). It
+ * cannot read another service (`openai/api_key`, `openai/imessage`). Outside
+ * any plugin context (host-internal callers, CLI, tests) the resolver is
+ * unscoped and behaves like a direct reveal.
  */
 /**
  * Raised when a credential cannot be resolved: the reference does not match a
@@ -4301,6 +4357,45 @@ export declare class CredentialResolutionError extends Error {
     constructor(message: string);
 }
 
+/**
+ * Plugin-facing credential storage.
+ *
+ * {@link storeCredential} writes a credential's plaintext to the secure store,
+ * the same write `assistant credentials set` performs, naming it either by an
+ * existing credential's UUID or by a `"service/field"` string, the same
+ * vocabulary {@link ./resolve-credential.resolveCredential} reads back. A
+ * plugin that obtains a token for itself (an OAuth exchange it drives, a key a
+ * user hands it through its own route) persists it here instead of inventing
+ * its own on-disk secret file.
+ *
+ * ## Plugin scoping
+ *
+ * A plugin may only write credentials whose `service` equals its manifest
+ * name (`imessage/api_key` for plugin `imessage`). It cannot write another
+ * service (`openai/api_key`, `openai/imessage`). The name comes from the
+ * execution context
+ * ({@link ../plugins/plugin-execution-context.getCurrentPluginName}), which the
+ * host establishes around a plugin's hook, tool, and route invocations.
+ *
+ * Unlike the read path, this **fails closed**: with no plugin in context there
+ * is nobody to scope the write to, so it is refused rather than treated as an
+ * unscoped host write. A plugin's module body is evaluated by the loader
+ * outside any context, and an unscoped branch there would let top-level code
+ * overwrite the user's own credentials. Host-internal callers that legitimately
+ * write unscoped (the `credentials/set` route, the CLI behind it) compose
+ * {@link ../tools/credentials/store.storeCredentialValue} directly. This
+ * matches the plugin-owned index (`indexDocument`), which likewise requires a
+ * context because a write with no owner has nothing to attribute.
+ */
+/**
+ * Raised when a credential cannot be stored: the reference is malformed, the
+ * value is empty or invalid for its service, the secure backend rejected the
+ * write, or the calling plugin is not permitted to write the credential.
+ */
+export declare class CredentialStoreError extends Error {
+    constructor(message: string);
+}
+
 /**
  * Delete a conversation, yielding the event loop between row batches, and
  * enqueue vector-store cleanup for the memory segments and summaries the
@@ -4441,6 +4536,9 @@ export declare function getModelProfiles(): ModelProfileInfo[];
  * When the VELLUM_WORKSPACE_DIR env var is set, returns that value (used in
  * containerized deployments where the workspace is a separate volume).
  * Otherwise falls back to ~/.vellum/workspace.
+ *
+ * In test processes the resolved directory must live under `os.tmpdir()`
+ * (see the live-workspace guard above); anything else throws.
  */
 export declare function getWorkspaceDir(): string;
 
@@ -4550,9 +4648,9 @@ export declare const HOOKS: {
 };
 
 /**
- * Host proxy capabilities that an interface can support. The macOS client
- * supports all of them; the chrome-extension interface only supports
- * host_browser (via the Chrome DevTools Protocol proxy).
+ * Host proxy capabilities that an interface can support. macOS supports all
+ * of them, Windows withholds app control, and chrome-extension supports only
+ * host_browser through the Chrome DevTools Protocol proxy.
  */
 declare const HOST_PROXY_CAPABILITIES: readonly ["host_bash", "host_file", "host_cu", "host_browser", "host_app_control", "host_ui_snapshot"];
 
@@ -4657,7 +4755,7 @@ declare interface InsertedMessage {
     deduplicated: boolean;
 }
 
-declare const INTERFACE_IDS: readonly ["macos", "ios", "cli", "telegram", "phone", "web", "whatsapp", "slack", "email", "chrome-extension", "a2a", "discord", "route", "plugin"];
+declare const INTERFACE_IDS: readonly ["macos", "windows", "ios", "cli", "telegram", "phone", "web", "whatsapp", "slack", "email", "chrome-extension", "a2a", "discord", "route", "plugin"];
 
 declare type InterfaceId = (typeof INTERFACE_IDS)[number];
 
@@ -5121,32 +5219,33 @@ declare type MessageMetadata = ReturnType<parseMessageMetadata_2>;
 declare type MessageMetadata_2 = z.infer<typeof messageMetadataSchema>;
 
 declare const messageMetadataSchema: z.ZodObject<{
+    sentAt: z.ZodOptional<z.ZodNumber>;
     userMessageChannel: z.ZodOptional<z.ZodEnum<{
-        plugin: "plugin";
-        vellum: "vellum";
-        platform: "platform";
-        telegram: "telegram";
         phone: "phone";
+        platform: "platform";
+        a2a: "a2a";
+        vellum: "vellum";
         whatsapp: "whatsapp";
+        discord: "discord";
+        telegram: "telegram";
         slack: "slack";
         email: "email";
-        a2a: "a2a";
-        discord: "discord";
+        plugin: "plugin";
     }>>;
     assistantMessageChannel: z.ZodOptional<z.ZodEnum<{
-        plugin: "plugin";
-        vellum: "vellum";
-        platform: "platform";
-        telegram: "telegram";
         phone: "phone";
+        platform: "platform";
+        a2a: "a2a";
+        vellum: "vellum";
         whatsapp: "whatsapp";
+        discord: "discord";
+        telegram: "telegram";
         slack: "slack";
         email: "email";
-        a2a: "a2a";
-        discord: "discord";
+        plugin: "plugin";
     }>>;
-    userMessageInterface: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<"plugin" | "telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route" | null, string>> & z.ZodType<"plugin" | "telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route", string, z.core.$ZodTypeInternals<"plugin" | "telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route", string>>>;
-    assistantMessageInterface: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<"plugin" | "telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route" | null, string>> & z.ZodType<"plugin" | "telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route", string, z.core.$ZodTypeInternals<"plugin" | "telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route", string>>>;
+    userMessageInterface: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<"phone" | "a2a" | "whatsapp" | "discord" | "telegram" | "slack" | "email" | "plugin" | "macos" | "windows" | "ios" | "cli" | "web" | "chrome-extension" | "route" | null, string>> & z.ZodType<"phone" | "a2a" | "whatsapp" | "discord" | "telegram" | "slack" | "email" | "plugin" | "macos" | "windows" | "ios" | "cli" | "web" | "chrome-extension" | "route", string, z.core.$ZodTypeInternals<"phone" | "a2a" | "whatsapp" | "discord" | "telegram" | "slack" | "email" | "plugin" | "macos" | "windows" | "ios" | "cli" | "web" | "chrome-extension" | "route", string>>>;
+    assistantMessageInterface: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<"phone" | "a2a" | "whatsapp" | "discord" | "telegram" | "slack" | "email" | "plugin" | "macos" | "windows" | "ios" | "cli" | "web" | "chrome-extension" | "route" | null, string>> & z.ZodType<"phone" | "a2a" | "whatsapp" | "discord" | "telegram" | "slack" | "email" | "plugin" | "macos" | "windows" | "ios" | "cli" | "web" | "chrome-extension" | "route", string, z.core.$ZodTypeInternals<"phone" | "a2a" | "whatsapp" | "discord" | "telegram" | "slack" | "email" | "plugin" | "macos" | "windows" | "ios" | "cli" | "web" | "chrome-extension" | "route", string>>>;
     client: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     clientOsFromRequest: z.ZodOptional<z.ZodBoolean>;
     subagentNotification: z.ZodOptional<z.ZodObject<{
@@ -5174,16 +5273,16 @@ declare const messageMetadataSchema: z.ZodObject<{
     }>>;
     model: z.ZodOptional<z.ZodString>;
     provenanceSourceChannel: z.ZodOptional<z.ZodEnum<{
-        plugin: "plugin";
-        vellum: "vellum";
-        platform: "platform";
-        telegram: "telegram";
         phone: "phone";
+        platform: "platform";
+        a2a: "a2a";
+        vellum: "vellum";
         whatsapp: "whatsapp";
+        discord: "discord";
+        telegram: "telegram";
         slack: "slack";
         email: "email";
-        a2a: "a2a";
-        discord: "discord";
+        plugin: "plugin";
     }>>;
     provenanceGuardianExternalUserId: z.ZodOptional<z.ZodString>;
     provenanceRequesterIdentifier: z.ZodOptional<z.ZodString>;
@@ -5200,8 +5299,8 @@ declare const messageMetadataSchema: z.ZodObject<{
         command: z.ZodString;
         startedAt: z.ZodNumber;
         status: z.ZodEnum<{
-            completed: "completed";
             cancelled: "cancelled";
+            completed: "completed";
             failed: "failed";
         }>;
         exitCode: z.ZodNullable<z.ZodNumber>;
@@ -5308,6 +5407,37 @@ export declare function parseMessageMetadata(metadataJson: string | null): Promi
  */
 declare function parseMessageMetadata_2(metadataJson: string | null): MessageMetadata_2 | undefined;
 
+/**
+ * Plugin-facing facade over the host's system-card writer: a daemon-authored
+ * transcript notice, persisted as an assistant row stamped
+ * `messageKind: "system_card"` so clients render it as a standalone system
+ * notice rather than assistant-persona speech. Plugins use it to tell the user
+ * about something the turn did to their input that the model's own reply
+ * cannot explain (e.g. an attachment the turn could not send).
+ *
+ * The writer is loaded through a dynamic `import()` inside the wrapper, for the
+ * same reason `persistence/conversation-plugin-facade.ts` does: it carries the
+ * DB/drizzle import graph, whose named exports must not be forced to resolve
+ * merely because a plugin imported `@vellumai/plugin-api`. Suites that
+ * partial-mock a module in that graph would otherwise fail to instantiate.
+ */
+/**
+ * Persist a system card in a conversation's transcript and announce it to
+ * connected clients through the sync invalidation that drives a refetch.
+ * Returns the persisted message id.
+ *
+ * A plugin card is non-terminal: it never emits `message_complete`, so a card
+ * written from a hook that runs inside a turn leaves that turn's streaming and
+ * processing state untouched. It is also not appended to the conversation's
+ * in-memory working history, so it cannot leave a trailing assistant message
+ * for the turn's next provider call to continue from.
+ */
+export declare function persistSystemCard(opts: {
+    conversationId: string;
+    text: string;
+    metadata: Record<string, unknown>;
+}): Promise<string>;
+
 /**
  * The subset of {@link AssistantEventHub} workspace plugins may use. Picking
  * method signatures off the class keeps the facade in sync with the hub while
@@ -6083,6 +6213,23 @@ export declare function resolveUserName(workspaceDir: string): string | null;
  */
 export declare function resolveWebhookUrl(options: WebhookUrlOptions): Promise<string>;
 
+declare type RiskAllowlistOption = z.infer<typeof RiskAllowlistOptionSchema>;
+
+/** Minimatch ladder for the "always allow" prompt option (what a rule matches). */
+declare const RiskAllowlistOptionSchema: z.ZodObject<{
+    label: z.ZodString;
+    description: z.ZodString;
+    pattern: z.ZodString;
+}, z.core.$strip>;
+
+declare type RiskDirectoryScopeOption = z.infer<typeof RiskDirectoryScopeOptionSchema>;
+
+/** Directory ladder for filesystem operations; `scope` is a path glob or `everywhere`. */
+declare const RiskDirectoryScopeOptionSchema: z.ZodObject<{
+    scope: z.ZodString;
+    label: z.ZodString;
+}, z.core.$strip>;
+
 export declare enum RiskLevel {
     Low = "low",
     Medium = "medium",
@@ -6510,6 +6657,43 @@ declare interface StopInputContext {
     readonly exitReason: AgentLoopExitReason;
 }
 
+/**
+ * Store a credential's plaintext value, creating it or replacing the value of
+ * an existing one.
+ *
+ * @param ref A credential UUID (an existing credential) or a `"service/field"`
+ *   string (created when no such credential exists).
+ * @param value The plaintext value. Edge whitespace is trimmed.
+ * @returns The identity of the stored credential, which
+ *   {@link ./resolve-credential.resolveCredential} accepts as a ref.
+ * @throws {CredentialStoreError} when no plugin is in context, the ref is
+ *   malformed or names no credential, the value is empty or invalid for its
+ *   service, the store rejects the write, or the calling plugin is not scoped
+ *   to the credential.
+ */
+export declare function storeCredential(ref: string, value: string, options?: StoreCredentialOptions): Promise<StoredCredentialRef>;
+
+export declare interface StoreCredentialOptions {
+    /** Human-friendly alias shown in credential listings. */
+    label?: string;
+    /** What the credential is for, surfaced to the agent. */
+    description?: string;
+    /**
+     * Skip the retroactive sweep that removes the value from recent transcripts.
+     * The sweep exists because a secret is often pasted into chat before it is
+     * stored; pass `true` only for a value that provably never transited a
+     * conversation, such as a token minted by an OAuth refresh.
+     */
+    skipTranscriptScrub?: boolean;
+}
+
+/** Identity of the credential that was written. */
+export declare interface StoredCredentialRef {
+    credentialId: string;
+    service: string;
+    field: string;
+}
+
 /**
  * Daemon-hosted streaming transcriber contract.
  *
@@ -7288,16 +7472,9 @@ export declare interface ToolExecutionResult {
      * wildcards) — what the gateway actually matches against. Mirrors
      * the `allowlistOptions` field on `ConfirmationRequest` SSE events.
      */
-    riskAllowlistOptions?: Array<{
-        label: string;
-        description: string;
-        pattern: string;
-    }>;
+    riskAllowlistOptions?: RiskAllowlistOption[];
     /** Directory scope ladder for the rule editor (narrowest to broadest). */
-    riskDirectoryScopeOptions?: Array<{
-        scope: string;
-        label: string;
-    }>;
+    riskDirectoryScopeOptions?: RiskDirectoryScopeOption[];
     /** Structured activity metadata for client rendering (web search, web fetch, etc).
      *  Populated by daemon-internal tools; plugins must not set this. */
     activityMetadata?: ToolActivityMetadata;
@@ -7597,6 +7774,19 @@ export declare interface WebhookUrlOptions {
     sourceIdentifier?: string;
 }
 
+/**
+ * Web tab visibility and conversation focus, as reported by a `web`-interface
+ * client (a browser tab or the Electron renderer). Distinct from
+ * {@link ClientPresence}: scoped to a single conversation rather than app-wide
+ * attendance, and reported by the shared web renderer rather than the macOS
+ * host-proxy bridge. See `runtime/web-presence.ts` for the read-side policy.
+ */
+declare interface WebPresenceReport {
+    visible: boolean;
+    /** The conversation currently focused (chat composer on screen), or `null`. */
+    focusedConversationId: string | null;
+}
+
 declare interface WebSearchMetadata {
     query: string;
     provider: WebSearchProviderId;

package/index.js

@@ -2,6 +2,7 @@
 const api = globalThis[Symbol.for("vellum.plugin-api")] ?? {};
 export const CLI_COMMAND_HELP = api.CLI_COMMAND_HELP;
 export const CredentialResolutionError = api.CredentialResolutionError;
+export const CredentialStoreError = api.CredentialStoreError;
 export const HOOKS = api.HOOKS;
 export const INTERNAL_NUDGE_OUTPUT_SUPPRESSION = api.INTERNAL_NUDGE_OUTPUT_SUPPRESSION;
 export const REFUSAL_FALLBACK_TEXT = api.REFUSAL_FALLBACK_TEXT;
@@ -39,6 +40,7 @@ export const listConversations = api.listConversations;
 export const listInstalledSkills = api.listInstalledSkills;
 export const openTranscriptionSession = api.openTranscriptionSession;
 export const parseMessageMetadata = api.parseMessageMetadata;
+export const persistSystemCard = api.persistSystemCard;
 export const publishEvent = api.publishEvent;
 export const quarantineRefusedExchanges = api.quarantineRefusedExchanges;
 export const queryIndex = api.queryIndex;
@@ -51,6 +53,7 @@ export const resolveWebhookUrl = api.resolveWebhookUrl;
 export const runConversationTurn = api.runConversationTurn;
 export const searchMessageIdsLexical = api.searchMessageIdsLexical;
 export const selectedBackendSupportsMultimodal = api.selectedBackendSupportsMultimodal;
+export const storeCredential = api.storeCredential;
 export const stringifyMessageContent = api.stringifyMessageContent;
 export const sweepOrphanedGraphNodePoints = api.sweepOrphanedGraphNodePoints;
 export const syncMessageToDisk = api.syncMessageToDisk;

package/package.json

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