@vellumai/plugin-api 0.12.2 → 0.12.3-staging.1

package/index.d.ts

@@ -101,6 +101,7 @@ declare const AnsweredQuestionSchema: z.ZodObject<{
             description: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         freeTextPlaceholder: z.ZodOptional<z.ZodString>;
+        presentation: z.ZodOptional<z.ZodLiteral<"virtual_desktop">>;
     }, z.core.$strip>>;
     responses: z.ZodArray<z.ZodObject<{
         questionId: z.ZodString;
@@ -601,6 +602,9 @@ declare const AssistantConfigSchema: z.ZodObject<{
                 bm25NormK: z.ZodDefault<z.ZodUnion<readonly [z.ZodNumber, z.ZodNull]>>;
                 bypassForCore: z.ZodDefault<z.ZodBoolean>;
             }, z.core.$strip>>;
+            poolLog: z.ZodDefault<z.ZodObject<{
+                captureInput: z.ZodDefault<z.ZodBoolean>;
+            }, z.core.$strip>>;
         }, z.core.$strip>>;
         retrospective: z.ZodDefault<z.ZodObject<{
             enabled: z.ZodDefault<z.ZodBoolean>;
@@ -1661,6 +1665,8 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         type: z.ZodLiteral<"conversation_title_updated">;
         conversationId: z.ZodString;
         title: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"desktop_activity_changed">;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"disk_pressure_status_changed">;
         status: z.ZodObject<{
@@ -1760,6 +1766,7 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
                 sandbox_file: "sandbox_file";
                 tool_block: "tool_block";
             }>>;
+            computerUseScreenshot: z.ZodOptional<z.ZodBoolean>;
             sizeBytes: z.ZodOptional<z.ZodNumber>;
             thumbnailData: z.ZodOptional<z.ZodString>;
             fileBacked: z.ZodOptional<z.ZodBoolean>;
@@ -2040,6 +2047,7 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
                 sandbox_file: "sandbox_file";
                 tool_block: "tool_block";
             }>>;
+            computerUseScreenshot: z.ZodOptional<z.ZodBoolean>;
             sizeBytes: z.ZodOptional<z.ZodNumber>;
             thumbnailData: z.ZodOptional<z.ZodString>;
             fileBacked: z.ZodOptional<z.ZodBoolean>;
@@ -2169,6 +2177,7 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
                 description: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>;
             freeTextPlaceholder: z.ZodOptional<z.ZodString>;
+            presentation: z.ZodOptional<z.ZodLiteral<"virtual_desktop">>;
         }, z.core.$strip>>;
         question: z.ZodString;
         description: z.ZodOptional<z.ZodString>;
@@ -2433,6 +2442,7 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
                     description: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>>;
                 freeTextPlaceholder: z.ZodOptional<z.ZodString>;
+                presentation: z.ZodOptional<z.ZodLiteral<"virtual_desktop">>;
             }, z.core.$strip>>;
             responses: z.ZodArray<z.ZodObject<{
                 questionId: z.ZodString;
@@ -3204,6 +3214,8 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"conversation_title_updated">;
     conversationId: z.ZodString;
     title: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"desktop_activity_changed">;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"disk_pressure_status_changed">;
     status: z.ZodObject<{
@@ -3303,6 +3315,7 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             sandbox_file: "sandbox_file";
             tool_block: "tool_block";
         }>>;
+        computerUseScreenshot: z.ZodOptional<z.ZodBoolean>;
         sizeBytes: z.ZodOptional<z.ZodNumber>;
         thumbnailData: z.ZodOptional<z.ZodString>;
         fileBacked: z.ZodOptional<z.ZodBoolean>;
@@ -3583,6 +3596,7 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             sandbox_file: "sandbox_file";
             tool_block: "tool_block";
         }>>;
+        computerUseScreenshot: z.ZodOptional<z.ZodBoolean>;
         sizeBytes: z.ZodOptional<z.ZodNumber>;
         thumbnailData: z.ZodOptional<z.ZodString>;
         fileBacked: z.ZodOptional<z.ZodBoolean>;
@@ -3712,6 +3726,7 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             description: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         freeTextPlaceholder: z.ZodOptional<z.ZodString>;
+        presentation: z.ZodOptional<z.ZodLiteral<"virtual_desktop">>;
     }, z.core.$strip>>;
     question: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
@@ -3976,6 +3991,7 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 description: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>;
             freeTextPlaceholder: z.ZodOptional<z.ZodString>;
+            presentation: z.ZodOptional<z.ZodLiteral<"virtual_desktop">>;
         }, z.core.$strip>>;
         responses: z.ZodArray<z.ZodObject<{
             questionId: z.ZodString;
@@ -4560,6 +4576,34 @@ export declare interface ConversationRow {
  */
 export declare type ConversationsClearedContext = BaseHookContext;
 
+/**
+ * Per-conversation record of what the most recent live turn sent to the
+ * provider that a fork wake cannot re-derive (`conversation_tool_surfaces`).
+ *
+ * The provider prompt cache is a byte-exact prefix match over
+ * `tools -> system -> messages`, so a background wake that forks a
+ * conversation can only reuse the source's cached prefix by sending the SAME
+ * tools array under the SAME system prompt. Re-deriving either on the fork
+ * cannot guarantee that: the fork may run in another process (a different
+ * tool registry), with no connected clients (different host-tool gates),
+ * under a presence the persisted message stamps do not encode, or under a
+ * wake scope that cannot spawn subagents where the source could (the system
+ * prompt's delegation section). Recording the resolved values and replaying
+ * them verbatim can.
+ */
+/** What a live turn sent that a replaying fork reproduces verbatim. */
+export declare interface ConversationToolSurface {
+    /** The tool definitions the turn sent, exactly as resolved. */
+    tools: ToolDefinition_2[];
+    /**
+     * Whether the turn's system prompt rendered the parallel-delegation
+     * section (`01-parallel-tasks`), which the prompt derives from the same
+     * resolved tool surface plus the turn's channel. `null` when unknown: the
+     * turn ran on a system-prompt override, or the row predates the column.
+     */
+    delegateIndependentTasks: boolean | null;
+}
+
 /** Read-side alias of {@link ConversationCreateType}. */
 declare type ConversationType = ConversationCreateType;
 
@@ -4767,6 +4811,15 @@ export declare function getConversationDirPath(id: string, createdAtMs: number):
  */
 export declare function getConversationProcessingStartedAt(id: string): Promise<number | null>;
 
+/**
+ * The tool definitions the conversation's most recent live turn sent to the
+ * provider, or `null` when none has been recorded. A projection of
+ * {@link getRecordedConversationToolSurface}: a fork replaying the source's
+ * request needs the whole record, whose delegation-section state the system
+ * prompt tier of the provider cache prefix depends on.
+ */
+export declare function getConversationToolSurface(conversationId: string): Promise<ToolDefinition_2[] | null>;
+
 /** Fetch one document from the calling plugin's index, or null. */
 export declare function getDocument(documentId: string): Promise<IndexedDocument | null>;
 
@@ -4788,6 +4841,14 @@ export declare function getMessages(conversationId: string): Promise<MessageRow[
  */
 export declare function getModelProfiles(): ModelProfileInfo[];
 
+/**
+ * What the conversation's most recent live turn sent to the provider that a
+ * replaying fork reproduces verbatim (its tool definitions and the
+ * delegation-section state of its system prompt), or `null` when none has
+ * been recorded.
+ */
+export declare function getRecordedConversationToolSurface(conversationId: string): Promise<ConversationToolSurface | null>;
+
 /**
  * Returns the workspace root for user-facing state.
  *
@@ -5705,6 +5766,7 @@ declare const messageMetadataSchema: z.ZodObject<{
     automated: z.ZodOptional<z.ZodBoolean>;
     hidden: z.ZodOptional<z.ZodBoolean>;
     voiceSessionTurn: z.ZodOptional<z.ZodBoolean>;
+    computerUseScreenshotAttachmentIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
     messageKind: z.ZodOptional<z.ZodString>;
     assistantTextVisibility: z.ZodOptional<z.ZodString>;
     providerErrorCode: z.ZodOptional<z.ZodString>;
@@ -5896,6 +5958,11 @@ export declare interface PluginLogger {
     debug(obj: Record<string, unknown>, msg?: string): void;
 }
 
+export declare class PluginTurnNotAdmittedError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+
 /**
  * The full `post-compact` context a hook receives — the dispatching call
  * site's {@link PostCompactInputContext} plus the pipeline-stamped
@@ -6780,6 +6847,23 @@ export declare interface RunConversationTurnResult {
     queued?: boolean;
 }
 
+/**
+ * Slice a string like `String.prototype.slice`, but never cut a UTF-16
+ * surrogate pair in half.
+ *
+ * If the character at `end - 1` is a high surrogate *and* there is more of
+ * the string beyond `end` (so cutting would actually orphan it), `end` is
+ * decremented by one.
+ *
+ * If the character at `start` is a low surrogate *and* `start > 0` (so we
+ * would be starting mid-pair), `start` is incremented by one.
+ *
+ * When `end === str.length` we do not touch a trailing high surrogate: if it
+ * was already orphaned upstream, repairing it here would silently mutate
+ * content. That is the sanitizer's job, not this function's.
+ */
+export declare function safeStringSlice(str: string, start?: number, end?: number): string;
+
 /** Sparse lexical search over stored message text; ranked message-id hits. */
 export declare function searchMessageIdsLexical(query: string, limit: number, opts?: {
     conversationId?: string;

package/index.js

@@ -5,6 +5,7 @@ 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 PluginTurnNotAdmittedError = api.PluginTurnNotAdmittedError;
 export const REFUSAL_FALLBACK_TEXT = api.REFUSAL_FALLBACK_TEXT;
 export const RiskLevel = api.RiskLevel;
 export const TtsSynthesisError = api.TtsSynthesisError;
@@ -25,9 +26,11 @@ export const getConfiguredProvider = api.getConfiguredProvider;
 export const getConversation = api.getConversation;
 export const getConversationDirPath = api.getConversationDirPath;
 export const getConversationProcessingStartedAt = api.getConversationProcessingStartedAt;
+export const getConversationToolSurface = api.getConversationToolSurface;
 export const getDocument = api.getDocument;
 export const getMessages = api.getMessages;
 export const getModelProfiles = api.getModelProfiles;
+export const getRecordedConversationToolSurface = api.getRecordedConversationToolSurface;
 export const getWorkspaceDir = api.getWorkspaceDir;
 export const hasLexicalTokens = api.hasLexicalTokens;
 export const indexDocument = api.indexDocument;
@@ -54,6 +57,7 @@ export const resolveOauthCallbackUrl = api.resolveOauthCallbackUrl;
 export const resolveUserName = api.resolveUserName;
 export const resolveWebhookUrl = api.resolveWebhookUrl;
 export const runConversationTurn = api.runConversationTurn;
+export const safeStringSlice = api.safeStringSlice;
 export const searchMessageIdsLexical = api.searchMessageIdsLexical;
 export const selectedBackendSupportsMultimodal = api.selectedBackendSupportsMultimodal;
 export const storeCredential = api.storeCredential;

package/package.json

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