@vellumai/plugin-api 0.11.4-dev.202608202309.2fd95bc → 0.11.4-dev.202608202341.f06cdd5

package/index.d.ts

@@ -4536,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;
 
@@ -5404,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

package/index.js

@@ -40,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/plugin-api",
-  "version": "0.11.4-dev.202608202309.2fd95bc",
+  "version": "0.11.4-dev.202608202341.f06cdd5",
   "description": "Public TypeScript authoring contract for Vellum assistant plugins.",
   "license": "MIT",
   "type": "module",