@vellumai/plugin-api 0.12.2-dev.202609211713.ad8242b → 0.12.2-dev.202609211913.b0ee78c

package/index.d.ts

@@ -12342,6 +12342,13 @@ declare type InterfaceId = (typeof INTERFACE_IDS)[number];
  */
 export declare const INTERNAL_NUDGE_OUTPUT_SUPPRESSION = " This notice is internal: do not repeat, quote, describe, or acknowledge it, and do not narrate whether you will continue or whether the turn is done. Reply with only the content the user should see.";
 
+/**
+ * Failed-parse tool result for executors that validate their own input (the
+ * pre-execution gate in `ToolApprovalHandler` produces the same message, so
+ * the error reads identically whichever layer catches it first).
+ */
+export declare function invalidToolInputResult(toolName: string, error: z.ZodError): ToolExecutionResult;
+
 /** Whether the conversation currently has a turn in flight. */
 export declare function isConversationProcessing(id: string): Promise<boolean>;
 
@@ -18105,6 +18112,16 @@ generated: undefined;
 dialect: "sqlite";
 }>;
 
+/**
+ * Wrap an optional field's schema so an explicit `null` parses as "omitted"
+ * (`undefined`). Models routinely send `null` for optional fields they mean
+ * to skip, and executors read such fields via `input.x ?? fallback`, where
+ * null and absent are equivalent — validation must not reject null there.
+ * The derived JSON Schema is the inner schema's (the null-tolerance is
+ * runtime slack, not advertised contract).
+ */
+export declare function nullAsOmitted<T extends z.ZodType>(schema: T): z.ZodPipe<z.ZodTransform<{} | undefined, unknown>, z.ZodOptional<T>>;
+
 declare const oauthApps: SQLiteTableWithColumns<    {
 name: "oauth_apps";
 schema: undefined;
@@ -23524,11 +23541,59 @@ export declare interface ThinkingContent {
  */
 export declare function throwIfCancelled(context: CancellableToolContext): void;
 
-/** Discriminated container so future tools can add their own metadata. */
-declare interface ToolActivityMetadata {
-    webSearch?: WebSearchMetadata;
-    webFetch?: WebFetchMetadata;
-}
+declare type ToolActivityMetadata = z.infer<typeof ToolActivityMetadataSchema>;
+
+declare const ToolActivityMetadataSchema: z.ZodObject<{
+    webSearch: z.ZodOptional<z.ZodObject<{
+        query: z.ZodString;
+        provider: z.ZodEnum<{
+            "anthropic-native": "anthropic-native";
+            brave: "brave";
+            perplexity: "perplexity";
+            tavily: "tavily";
+            keenable: "keenable";
+            firecrawl: "firecrawl";
+            fastcrw: "fastcrw";
+            searxng: "searxng";
+            tinyfish: "tinyfish";
+        }>;
+        resultCount: z.ZodNumber;
+        durationMs: z.ZodNumber;
+        results: z.ZodArray<z.ZodObject<{
+            rank: z.ZodNumber;
+            title: z.ZodString;
+            url: z.ZodString;
+            domain: z.ZodString;
+            faviconUrl: z.ZodOptional<z.ZodString>;
+            snippet: z.ZodOptional<z.ZodString>;
+            age: z.ZodOptional<z.ZodString>;
+            score: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        errorMessage: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    webFetch: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        finalUrl: z.ZodString;
+        provider: z.ZodOptional<z.ZodEnum<{
+            default: "default";
+            firecrawl: "firecrawl";
+            fastcrw: "fastcrw";
+            tinyfish: "tinyfish";
+        }>>;
+        status: z.ZodNumber;
+        contentType: z.ZodOptional<z.ZodString>;
+        byteCount: z.ZodNumber;
+        charCount: z.ZodNumber;
+        truncated: z.ZodBoolean;
+        title: z.ZodOptional<z.ZodString>;
+        domain: z.ZodString;
+        faviconUrl: z.ZodOptional<z.ZodString>;
+        redirectCount: z.ZodNumber;
+        durationMs: z.ZodNumber;
+        errorMessage: z.ZodOptional<z.ZodString>;
+        mayRequireJavaScript: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 
 /**
  * Runtime context passed as the second argument to every tool's `execute`.
@@ -24321,14 +24386,45 @@ export declare interface ToolUseContent {
     };
 }
 
-declare type TrustClass = z.infer<typeof trustClassSchema>;
+/**
+ * Derive a tool's LLM-facing `input_schema` from its Zod input schema, so the
+ * schema the model sees and the validation the executor runs share one source
+ * and cannot drift (`TOOL_INPUT_SCHEMAS` in `../tool-input-schemas.ts` holds
+ * the executor-side half).
+ *
+ * Conversion uses Zod 4's native `z.toJSONSchema` (mirroring
+ * `workflows/leaf-runner.ts`), then adjusts the output for the tool-definition
+ * context:
+ *
+ * - The `$schema` marker is dropped — tool definitions don't carry one.
+ * - `additionalProperties` values of `false` / `{}` are dropped. They are
+ *   authoring artifacts of `z.object` / `z.looseObject`, not intentional
+ *   contract: runtime validation never rejects unknown keys (registry schemas
+ *   must tolerate injected fields like `activity`, see
+ *   `schema-transforms.ts`), so advertising `additionalProperties: false`
+ *   would claim a strictness the runtime doesn't enforce.
+ *
+ * `advertiseRequired` names fields to mark required in the advertised schema
+ * even though the Zod schema treats them as optional. This is the one
+ * sanctioned divergence, and only in the tolerant direction: the model is told
+ * to always send the field (e.g. `activity`, which drives status UX), but a
+ * call that omits it still executes rather than failing on a field the tool
+ * doesn't need. Naming `activity` there also records the schema as carrying
+ * the daemon's own status field (`declareDaemonActivityField`), so a surface
+ * that renders no activity text can drop it from the advertised copy.
+ */
+export declare function toToolInputSchema(schema: z.ZodType, opts?: {
+    advertiseRequired?: readonly string[];
+}): Record<string, unknown>;
 
-declare const trustClassSchema: z.ZodEnum<{
-    unknown: "unknown";
-    guardian: "guardian";
-    trusted_contact: "trusted_contact";
-    unverified_contact: "unverified_contact";
-}>;
+/**
+ * Trust classification of an inbound actor, ordered most- to least-trusted.
+ * The one declaration of the vocabulary: the gateway classifies with it and
+ * the daemon derives capabilities from it.
+ */
+declare const TRUST_CLASS_VALUES: readonly ["guardian", "trusted_contact", "unverified_contact", "unknown"];
+
+declare type TrustClass = (typeof TRUST_CLASS_VALUES)[number];
 
 export declare class TtsSynthesisError extends Error {
     readonly code: TtsSynthesisErrorCode;
@@ -25248,29 +25344,6 @@ generated: undefined;
 dialect: "sqlite";
 }>;
 
-declare interface WebFetchMetadata {
-    url: string;
-    finalUrl: string;
-    /** Provider that served the fetch. Defaults to the built-in fetcher. */
-    provider?: WebFetchProviderId;
-    status: number;
-    contentType?: string;
-    byteCount: number;
-    charCount: number;
-    truncated: boolean;
-    title?: string;
-    domain: string;
-    faviconUrl?: string;
-    redirectCount: number;
-    durationMs: number;
-    errorMessage?: string;
-    /** Set when extracted text is dramatically smaller than raw HTML — likely a JS-rendered SPA whose meaningful content the static fetcher missed. */
-    mayRequireJavaScript?: boolean;
-}
-
-/** Provider that backed a `web_fetch` call. `default` is the built-in fetcher. */
-declare type WebFetchProviderId = "default" | "firecrawl" | "fastcrw" | "tinyfish";
-
 /**
  * Public URL resolution for a plugin's own ingress route.
  *
@@ -25316,29 +25389,6 @@ declare interface WebPresenceReport {
     focusedConversationId: string | null;
 }
 
-declare interface WebSearchMetadata {
-    query: string;
-    provider: WebSearchProviderId;
-    resultCount: number;
-    durationMs: number;
-    results: WebSearchResultItem[];
-    /** Present when search itself failed; results[] will be empty. */
-    errorMessage?: string;
-}
-
-declare type WebSearchProviderId = "anthropic-native" | "brave" | "perplexity" | "tavily" | "keenable" | "firecrawl" | "fastcrw" | "searxng" | "tinyfish";
-
-declare interface WebSearchResultItem {
-    rank: number;
-    title: string;
-    url: string;
-    domain: string;
-    faviconUrl?: string;
-    snippet?: string;
-    age?: string;
-    score?: number;
-}
-
 export declare interface WebSearchToolResultContent {
     type: "web_search_tool_result";
     tool_use_id: string;

package/index.js

@@ -35,6 +35,7 @@ export const getRecordedConversationToolSurface = api.getRecordedConversationToo
 export const getWorkspaceDir = api.getWorkspaceDir;
 export const hasLexicalTokens = api.hasLexicalTokens;
 export const indexDocument = api.indexDocument;
+export const invalidToolInputResult = api.invalidToolInputResult;
 export const isConversationProcessing = api.isConversationProcessing;
 export const isMaxTokensStopReason = api.isMaxTokensStopReason;
 export const isToolResultMessage = api.isToolResultMessage;
@@ -44,6 +45,7 @@ export const listCatalogSkills = api.listCatalogSkills;
 export const listConversations = api.listConversations;
 export const listInstalledSkills = api.listInstalledSkills;
 export const mediaBlockAttachmentId = api.mediaBlockAttachmentId;
+export const nullAsOmitted = api.nullAsOmitted;
 export const openTranscriptionSession = api.openTranscriptionSession;
 export const parseMessageMetadata = api.parseMessageMetadata;
 export const parseSurfaceShowResultId = api.parseSurfaceShowResultId;
@@ -67,4 +69,5 @@ export const sweepOrphanedGraphNodePoints = api.sweepOrphanedGraphNodePoints;
 export const syncMessageToDisk = api.syncMessageToDisk;
 export const synthesizeText = api.synthesizeText;
 export const throwIfCancelled = api.throwIfCancelled;
+export const toToolInputSchema = api.toToolInputSchema;
 export const updateMessageMetadata = api.updateMessageMetadata;

package/package.json

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