@vellumai/plugin-api 0.11.11-staging.2 → 0.11.11-staging.4

package/index.d.ts

@@ -1375,6 +1375,7 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         reason: z.ZodEnum<{
             thinking_delta: "thinking_delta";
             message_dequeued: "message_dequeued";
+            message_interrupted: "message_interrupted";
             first_text_delta: "first_text_delta";
             tool_use_start: "tool_use_start";
             preview_start: "preview_start";
@@ -2049,6 +2050,10 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
             filePath: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
         attachmentWarnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        assistantTextVisibility: z.ZodOptional<z.ZodEnum<{
+            private: "private";
+            visible: "visible";
+        }>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"message_dequeued">;
         conversationId: z.ZodString;
@@ -2898,6 +2903,7 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     reason: z.ZodEnum<{
         thinking_delta: "thinking_delta";
         message_dequeued: "message_dequeued";
+        message_interrupted: "message_interrupted";
         first_text_delta: "first_text_delta";
         tool_use_start: "tool_use_start";
         preview_start: "preview_start";
@@ -3572,6 +3578,10 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         filePath: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
     attachmentWarnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    assistantTextVisibility: z.ZodOptional<z.ZodEnum<{
+        private: "private";
+        visible: "visible";
+    }>>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"message_dequeued">;
     conversationId: z.ZodString;
@@ -4238,6 +4248,18 @@ declare interface BaseSubscriberEntry {
  */
 export declare function buildMessageExcerpt(rawContent: string, query: string): Promise<string>;
 
+/**
+ * The turn-cancellation guard every side-effecting tool calls, host tools and
+ * plugin tools alike. It lives on the plugin API surface because that is the
+ * only module a plugin may import from, and the guard must be one
+ * implementation rather than a copy per side of the boundary.
+ */
+/** The slice of a tool's context this guard reads. */
+export declare interface CancellableToolContext {
+    /** Cooperative cancellation signal for the turn, when the caller supplies one. */
+    signal?: AbortSignal;
+}
+
 /**
  * Conversation-type axis within an adapter (the "channel-type" cascade
  * level): direct message, private channel/group, public channel. Adapters
@@ -5611,6 +5633,7 @@ declare const messageMetadataSchema: z.ZodObject<{
     hidden: z.ZodOptional<z.ZodBoolean>;
     voiceSessionTurn: z.ZodOptional<z.ZodBoolean>;
     messageKind: z.ZodOptional<z.ZodString>;
+    assistantTextVisibility: z.ZodOptional<z.ZodString>;
     providerErrorCode: z.ZodOptional<z.ZodString>;
     providerErrorCategory: z.ZodOptional<z.ZodString>;
     backgroundToolCompletion: z.ZodOptional<z.ZodObject<{
@@ -5631,6 +5654,7 @@ declare const messageMetadataSchema: z.ZodObject<{
     forkSourceMessageId: z.ZodOptional<z.ZodString>;
     imageSourcePaths: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     attachmentStoredPaths: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    interruptedPriorTurn: z.ZodOptional<z.ZodBoolean>;
     memoryInjectedBlock: z.ZodOptional<z.ZodString>;
     memoryV3InjectedBlock: z.ZodOptional<z.ZodString>;
     memoryV3InjectedBlockFormat: z.ZodOptional<z.ZodNumber>;
@@ -5731,6 +5755,17 @@ export declare function parseMessageMetadata(metadataJson: string | null): Promi
  */
 declare function parseMessageMetadata_2(metadataJson: string | null): MessageMetadata_2 | undefined;
 
+/**
+ * Read the `surfaceId` out of a `ui_show` tool result, or `undefined` when the
+ * content is not a surface envelope.
+ *
+ * Trailing prose after the JSON object is tolerated: guidance belongs in a
+ * `note` field, but a caller that appends it instead must not silently cost
+ * the reader its `surfaceId`: losing the id makes a live progress surface
+ * invisible to the completion nudge, and the user watches it spin forever.
+ */
+export declare function parseSurfaceShowResultId(content: string): string | undefined;
+
 /**
  * Plugin-facing facade over the host's system-card writer: a daemon-authored
  * transcript notice, persisted as an assistant row stamped
@@ -5936,6 +5971,28 @@ declare interface PostModelCallInputContext {
     messages: Message[];
     /** Provider-reported stop reason for the turn; `null` when not reported. */
     readonly stopReason: string | null;
+    /**
+     * True when this run's plain assistant text does not reach the user: the
+     * turn routes its reply through the `send_user_message` tool instead, and
+     * {@link content}'s text blocks are private working notes. A hook that
+     * decides whether the user was answered must read this rather than assume
+     * visible text was delivered. Absent or false on every ordinary run, so a
+     * hook reads it as `=== true`.
+     */
+    readonly assistantTextSuppressed?: boolean;
+    /**
+     * Whether the user has already been told the OUTCOME of this run's work,
+     * decided by the host so a hook cannot reach a different answer than the
+     * loop does.
+     *
+     * True when the last response that called any tool reported on the work
+     * before it: every one of its tool calls delivered a message to the user. A
+     * response that sends a message alongside other tool calls is a progress
+     * update, and a call the executor rejects (blank or non-string message)
+     * delivers nothing, so neither counts. Absent on a host that does not
+     * compute it, so a hook reads it as `=== true`.
+     */
+    readonly userToldOutcome?: boolean;
     /**
      * The provider rejection that ended the call, on a rejection outcome. Absent
      * on a finalized reply. A hook that recovers from a specific rejection class
@@ -7399,6 +7456,22 @@ export declare interface ThinkingContent {
     signature: string;
 }
 
+/**
+ * Stop a side-effecting tool whose turn was cancelled before it acted.
+ *
+ * Call this immediately before the step that changes something the user would
+ * notice: a write, a create/update/delete, a message send, a process spawn, a
+ * paid provider call. The agent loop tells the model an aborted batch was
+ * cancelled, so anything that lands after the abort is work the model believes
+ * never happened.
+ *
+ * Throws the signal's own reason, which is the daemon's tagged abort reason
+ * for a conversation abort and a `DOMException` named `AbortError` for a plain
+ * one. The tool executor recognizes both and reports the call as an expected
+ * cancellation rather than a tool failure.
+ */
+export declare function throwIfCancelled(context: CancellableToolContext): void;
+
 /** Discriminated container so future tools can add their own metadata. */
 declare interface ToolActivityMetadata {
     webSearch?: WebSearchMetadata;
@@ -7491,6 +7564,12 @@ export declare interface ToolContext {
      * @legacy
      */
     diskPressureCleanupModeActive?: boolean;
+    /**
+     * Whether this turn routes its user-facing text through `send_user_message`.
+     * Read by the cleanup-mode gate, which keeps that tool callable on a gated
+     * turn: the wire offers it, so the executor must not refuse it.
+     */
+    sendUserMessageActive?: boolean;
     /**
      * Prompt the user for a secret value via native SecureField UI.
      * @legacy

package/index.js

@@ -42,6 +42,7 @@ export const listInstalledSkills = api.listInstalledSkills;
 export const mediaBlockAttachmentId = api.mediaBlockAttachmentId;
 export const openTranscriptionSession = api.openTranscriptionSession;
 export const parseMessageMetadata = api.parseMessageMetadata;
+export const parseSurfaceShowResultId = api.parseSurfaceShowResultId;
 export const persistSystemCard = api.persistSystemCard;
 export const publishEvent = api.publishEvent;
 export const quarantineRefusedExchanges = api.quarantineRefusedExchanges;
@@ -60,4 +61,5 @@ export const stringifyMessageContent = api.stringifyMessageContent;
 export const sweepOrphanedGraphNodePoints = api.sweepOrphanedGraphNodePoints;
 export const syncMessageToDisk = api.syncMessageToDisk;
 export const synthesizeText = api.synthesizeText;
+export const throwIfCancelled = api.throwIfCancelled;
 export const updateMessageMetadata = api.updateMessageMetadata;

package/package.json

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