@yaklabs-ai/plugin-sdk 0.26.3 → 0.27.0

package/README.md

@@ -13,7 +13,7 @@ it under the name your plugin code actually imports:
 ```json
 {
   "dependencies": {
-    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.26.3"
+    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.27.0"
   }
 }
 ```
@@ -62,7 +62,7 @@ Every tool the entrypoint registers is declared in the manifest too:
   "description": "Greets people by name.",
   "version": "0.1.0",
   "namespace": "widgets",
-  "compatibility": { "sdk": "^0.26.3" },
+  "compatibility": { "sdk": "^0.27.0" },
   "targets": {
     "kay": {
       "agent": {

package/THIRD-PARTY-INVENTORY.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@yaklabs-ai/plugin-sdk",
-  "version": "0.26.3",
+  "version": "0.27.0",
   "target": "npm",
   "firstPartyLicense": "MIT",
   "bundled": [

package/dist/canonical-transcript.js

@@ -1113,7 +1113,7 @@ function mergeMessageContent(item, event, status) {
     // The terminal merge (message_end) stamps completion; `startedAt` was
     // stamped at message_start and is never overwritten by later events.
     ...status === "streaming" || item.completedAt !== void 0 ? {} : stringField("completedAt", getTimestamp(event)),
-    ...messageMetadata(event, textPhaseFor(event, effectiveParts), effectiveParts)
+    ...messageMetadata(event, textPhaseFor(event, effectiveParts, item.parts), effectiveParts)
   };
 }
 function mergeMessageDelta(item, event) {
@@ -1263,12 +1263,12 @@ function messageFailureReason(event) {
     ...errorText === void 0 ? {} : { failureText: readableFailureText(errorText) }
   };
 }
-function textPhaseFor(event, parts) {
+function textPhaseFor(event, parts, streamedParts = []) {
   if (event.type !== "message_end")
     return "provisional";
+  const isCall = (part) => part.type === "tool_call";
+  const callsTool = parts.some(isCall) || streamedParts.some(isCall);
   switch (finishReasonFor(event, parts)) {
-    case "tool_use":
-      return "narration";
     case "complete":
       return "final";
     case "interrupted":
@@ -1276,8 +1276,11 @@ function textPhaseFor(event, parts) {
       return "interrupted";
     case "error":
       return "error";
+    // Text is narration only beside a call it leads into. A provider can report `tool_use`
+    // with no call in the message; that text is the reply, as a stop's would be.
+    case "tool_use":
     case "unknown":
-      return parts.some((part) => part.type === "tool_call") ? "narration" : "final";
+      return callsTool ? "narration" : "final";
     case void 0:
       return "final";
   }

package/dist/disclosure.d.ts

@@ -2306,8 +2306,14 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * registers the named function on any such scheme, its own client's included, and the SDK refuses a
  * plugin whose lookup and manifest disagree. An own-client (`pkce`) scheme may carry the
  * `clientSecret` that goes with its `clientId`. A plugin with an `oauth2` sign-in declares ^0.26.3.
+ *
+ * 0.27.0 makes a message approval card manifest data (#14574). `approvalTypes` declares the card's
+ * facts and forms, and Bonsai draws it with the module's `describeOperation` and sends it with its
+ * `write`. `app.approvals`, its `prepare`, `finalize` and `resolveResource` are gone, and a write can
+ * refuse in the person's words with `UriProviderError.refusalMessage`. No plugin outside this repo
+ * declared a card, so 0.26.3 stays served. A plugin that declares a card declares ^0.27.0.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.26.3";
+declare const KAY_PLUGIN_SDK_VERSION: "0.27.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 

package/dist/kay-agent-testing.d.ts

@@ -2360,8 +2360,14 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * registers the named function on any such scheme, its own client's included, and the SDK refuses a
  * plugin whose lookup and manifest disagree. An own-client (`pkce`) scheme may carry the
  * `clientSecret` that goes with its `clientId`. A plugin with an `oauth2` sign-in declares ^0.26.3.
+ *
+ * 0.27.0 makes a message approval card manifest data (#14574). `approvalTypes` declares the card's
+ * facts and forms, and Bonsai draws it with the module's `describeOperation` and sends it with its
+ * `write`. `app.approvals`, its `prepare`, `finalize` and `resolveResource` are gone, and a write can
+ * refuse in the person's words with `UriProviderError.refusalMessage`. No plugin outside this repo
+ * declared a card, so 0.26.3 stays served. A plugin that declares a card declares ^0.27.0.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.26.3";
+declare const KAY_PLUGIN_SDK_VERSION: "0.27.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -4703,9 +4709,9 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
             endpoint: "endpoint";
             storage: "storage";
             command: "command";
+            uriModule: "uriModule";
             authService: "authService";
             app: "app";
-            uriModule: "uriModule";
             configSection: "configSection";
             skill: "skill";
             converter: "converter";
@@ -5419,14 +5425,80 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
         toolName: z.ZodString;
     }, z.core.$strict>>>;
     kayAppApprovalTypes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kind: z.ZodLiteral<"message">;
         localId: z.ZodString;
+        provider: z.ZodString;
+        unknownMessage: z.ZodString;
+        fields: z.ZodObject<{
+            body: z.ZodObject<{
+                key: z.ZodString;
+                max: z.ZodNumber;
+            }, z.core.$strict>;
+            subject: z.ZodOptional<z.ZodObject<{
+                key: z.ZodString;
+                max: z.ZodNumber;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+        presentation: z.ZodObject<{
+            showAccount: z.ZodBoolean;
+            recipient: z.ZodEnum<{
+                target: "target";
+                person: "person";
+            }>;
+        }, z.core.$strict>;
+        forms: z.ZodObject<{
+            inline: z.ZodOptional<z.ZodObject<{
+                uri: z.ZodUnion<readonly [z.ZodObject<{
+                    fixed: z.ZodString;
+                }, z.core.$strict>, z.ZodObject<{
+                    value: z.ZodString;
+                }, z.core.$strict>]>;
+                requestFields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                payload: z.ZodRecord<z.ZodString, z.ZodString>;
+                fixed: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>>>;
+            }, z.core.$strict>>;
+            saved: z.ZodOptional<z.ZodObject<{
+                uri: z.ZodUnion<readonly [z.ZodObject<{
+                    fixed: z.ZodString;
+                }, z.core.$strict>, z.ZodObject<{
+                    value: z.ZodString;
+                }, z.core.$strict>]>;
+                requestFields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                payload: z.ZodRecord<z.ZodString, z.ZodString>;
+                fixed: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>>>;
+            }, z.core.$strict>>;
+            stored: z.ZodOptional<z.ZodObject<{
+                uri: z.ZodUnion<readonly [z.ZodObject<{
+                    fixed: z.ZodString;
+                }, z.core.$strict>, z.ZodObject<{
+                    value: z.ZodString;
+                }, z.core.$strict>]>;
+                requestFields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                payload: z.ZodRecord<z.ZodString, z.ZodString>;
+                fixed: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>>>;
+                read: z.ZodObject<{
+                    revision: z.ZodString;
+                    body: z.ZodString;
+                    subject: z.ZodOptional<z.ZodString>;
+                    to: z.ZodOptional<z.ZodString>;
+                    cc: z.ZodOptional<z.ZodString>;
+                    bcc: z.ZodOptional<z.ZodString>;
+                    attachments: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+        display: z.ZodOptional<z.ZodObject<{
+            bodyFormat: z.ZodOptional<z.ZodLiteral<"mrkdwn">>;
+            replyField: z.ZodOptional<z.ZodString>;
+            replyLabel: z.ZodOptional<z.ZodString>;
+            facts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                field: z.ZodString;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>>;
         globalId: z.ZodString;
-        kind: z.ZodEnum<{
-            message: "message";
-            change: "change";
-            action: "action";
-            access: "access";
-        }>;
+        moduleId: z.ZodString;
+        authService: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>>;
     kayAppDataSources: z.ZodOptional<z.ZodArray<z.ZodObject<{
         localId: z.ZodString;

package/dist/kay-agent.d.ts

@@ -2635,8 +2635,14 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * registers the named function on any such scheme, its own client's included, and the SDK refuses a
  * plugin whose lookup and manifest disagree. An own-client (`pkce`) scheme may carry the
  * `clientSecret` that goes with its `clientId`. A plugin with an `oauth2` sign-in declares ^0.26.3.
+ *
+ * 0.27.0 makes a message approval card manifest data (#14574). `approvalTypes` declares the card's
+ * facts and forms, and Bonsai draws it with the module's `describeOperation` and sends it with its
+ * `write`. `app.approvals`, its `prepare`, `finalize` and `resolveResource` are gone, and a write can
+ * refuse in the person's words with `UriProviderError.refusalMessage`. No plugin outside this repo
+ * declared a card, so 0.26.3 stays served. A plugin that declares a card declares ^0.27.0.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.26.3";
+declare const KAY_PLUGIN_SDK_VERSION: "0.27.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -11198,6 +11204,8 @@ export declare class UriProviderError extends UriError {
     readonly retryAfterMs?: number;
     /** See {@link UriProviderErrorOptions.effect}. */
     readonly effect?: "none";
+    /** See {@link UriProviderErrorOptions.refusalMessage}. */
+    readonly refusalMessage?: string;
     constructor(options: UriProviderErrorOptions);
 }
 
@@ -11220,6 +11228,11 @@ export declare interface UriProviderErrorOptions {
      * earlier request may have changed something.
      */
     readonly effect?: "none";
+    /**
+     * What to tell the person when a write they approved was refused, in their words. Only with
+     * `effect: "none"`: it is the plugin saying nothing happened and why.
+     */
+    readonly refusalMessage?: string;
 }
 
 export declare interface UriResolveContext {

package/dist/kay-agent.js

@@ -388,6 +388,8 @@ var UriProviderError = class extends UriError {
   retryAfterMs;
   /** See {@link UriProviderErrorOptions.effect}. */
   effect;
+  /** See {@link UriProviderErrorOptions.refusalMessage}. */
+  refusalMessage;
   constructor(options) {
     super(options.message);
     this.name = "UriProviderError";
@@ -408,6 +410,12 @@ var UriProviderError = class extends UriError {
     }
     if (options.effect !== void 0)
       this.effect = options.effect;
+    if (options.refusalMessage !== void 0) {
+      if (options.effect !== "none") {
+        throw new TypeError('refusalMessage requires effect: "none".');
+      }
+      this.refusalMessage = options.refusalMessage;
+    }
   }
 };
 var UriNotFoundError = class extends UriError {

package/dist/kay-app.d.ts

@@ -2,6 +2,10 @@ import { pathToFileURL } from 'node:url';
 import type { StatementSync } from 'node:sqlite';
 import { z } from 'zod';
 
+export declare interface AccessApprovalContext {
+    readonly signal: AbortSignal;
+}
+
 export declare interface AccessApprovalInput {
     readonly uri: string;
     readonly content: Record<string, unknown>;
@@ -27,7 +31,7 @@ export declare interface AccessApprovalTypeDefinition {
     readonly prepare: (input: AccessApprovalInput) => PreparedAccessApproval | undefined;
     readonly finalize: (input: {
         readonly prepared: PreparedAccessApproval;
-    }, ctx: ApprovalTypeContext) => Promise<FinalizedAccessApproval>;
+    }, ctx: AccessApprovalContext) => Promise<FinalizedAccessApproval>;
 }
 
 declare const AdapterPlacement: z.ZodEnum<{
@@ -142,9 +146,6 @@ declare const AnthropicMessagesCompatSchema: Type.TObject<{
 /** Creates a Any type. */
 declare function Any(options?: TSchemaOptions): TAny;
 
-/** Every approval type kind, for registration and storage boundaries. */
-export declare type AnyApprovalTypeDefinition = MessageApprovalTypeDefinition | AccessApprovalTypeDefinition;
-
 declare type Api = KnownApi | (string & {});
 
 export declare const ApprovalOrigin: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -157,24 +158,6 @@ export declare const ApprovalOrigin: z.ZodDiscriminatedUnion<[z.ZodObject<{
 
 export declare type ApprovalOrigin = z.infer<typeof ApprovalOrigin>;
 
-export declare interface ApprovalTypeContext {
-    readonly signal: AbortSignal;
-    readonly read?: (uri: string) => Promise<{
-        readonly content: string | Uint8Array;
-    }>;
-    readonly edit?: (uri: string, patch: unknown, options: {
-        readonly signal: AbortSignal;
-    }) => Promise<{
-        readonly resource: unknown;
-    }>;
-    readonly report?: (stage: "edit" | "verify", attributes: Readonly<Record<string, string>>) => void;
-}
-
-/** Legacy name for a message approval type; message-only plugins keep compiling against it. */
-export declare type ApprovalTypeDefinition = MessageApprovalTypeDefinition;
-
-export declare type ApprovalTypeResolver = (provider: string) => RegisteredApprovalType | undefined;
-
 /** Creates an Array type. */
 declare function _Array_<Type extends TSchema>(items: Type, options?: TArrayOptions): TArray<Type>;
 
@@ -372,10 +355,6 @@ declare type AvailabilityFactsMessage = CustomMessage<AvailabilityFactsDetails>
     readonly display: true;
 };
 
-declare type AvailableDraft = Extract<UiMessageDraftResource, {
-    status: "available";
-}>;
-
 declare const BACKGROUND_TASK_RESULT_CUSTOM_TYPE = "background_task_result";
 
 declare interface BackgroundTaskAdoptOptions {
@@ -1552,13 +1531,10 @@ declare const FileExtensionToken: z.ZodString;
 
 declare type FileExtensionToken = z.infer<typeof FileExtensionToken>;
 
-export declare type FinalizedAccessApproval = FinalizedMessageApproval;
-
-export declare type FinalizedMessageApproval = {
+export declare type FinalizedAccessApproval = {
     readonly status: "ready";
     readonly uri: string;
     readonly content: Record<string, unknown>;
-    readonly resourceChanged?: true;
 } | {
     readonly status: "failed";
     readonly message: string;
@@ -2630,8 +2606,14 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * registers the named function on any such scheme, its own client's included, and the SDK refuses a
  * plugin whose lookup and manifest disagree. An own-client (`pkce`) scheme may carry the
  * `clientSecret` that goes with its `clientId`. A plugin with an `oauth2` sign-in declares ^0.26.3.
+ *
+ * 0.27.0 makes a message approval card manifest data (#14574). `approvalTypes` declares the card's
+ * facts and forms, and Bonsai draws it with the module's `describeOperation` and sends it with its
+ * `write`. `app.approvals`, its `prepare`, `finalize` and `resolveResource` are gone, and a write can
+ * refuse in the person's words with `UriProviderError.refusalMessage`. No plugin outside this repo
+ * declared a card, so 0.26.3 stays served. A plugin that declares a card declares ^0.27.0.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.26.3";
+declare const KAY_PLUGIN_SDK_VERSION: "0.27.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -3151,11 +3133,6 @@ export declare interface KayAppAgents {
     }): Promise<KayAppSessionRunOutcome>;
 }
 
-export declare interface KayAppApprovals {
-    /** Register a declared type exactly once during activation. */
-    registerType(localId: string, definition: AnyApprovalTypeDefinition): void;
-}
-
 export declare interface KayAppArtifact {
     readonly uri: string;
     readonly kind: string;
@@ -5024,7 +5001,6 @@ export declare interface KayAppPhaseShiftSessionEvent extends KayAppSessionEvent
 export declare interface KayAppPluginApi {
     /** This plugin's canonical id (already validated by the host registry). */
     readonly id: string;
-    readonly approvals: KayAppApprovals;
     /** Register app-lifetime cleanup for plugin-owned processes, sockets, watchers, or timers. */
     readonly lifecycle: KayAppLifecycle;
     /**
@@ -8722,175 +8698,12 @@ export declare namespace Memory {
 
 declare type Message = SystemMessage | UserMessage | AssistantMessage | ToolResultMessage;
 
-export declare const MESSAGE_DRAFT_BODY_MAX = 20000;
-
-export declare const MESSAGE_DRAFT_SUBJECT_MAX = 300;
-
-export declare type MessageApprovalContent = AvailableDraft["content"] | {
-    readonly kind: "inline-email";
-    readonly to: readonly string[];
-    readonly cc?: readonly string[];
-    readonly bcc?: readonly string[];
-    readonly subject: string;
-    readonly body: string;
-} | {
-    readonly kind: "inline-chat";
-    readonly provider: "slack";
-    readonly conversationUri: string;
-    readonly body: string;
-};
-
-export declare interface MessageApprovalInput {
-    readonly content: MessageApprovalContent;
-    readonly request: UiMessageDraftDeliveryRequest | UiMessageDraftInlineDeliveryRequest;
-    /** Unqualified provider URI after host account validation. */
-    readonly uri: string;
-    readonly resource?: AvailableDraft;
-}
-
-/** A fixed delivery refusal from pure preparation; safe across separately bundled SDK copies. */
-export declare class MessageApprovalPreparationError extends Error {
-    readonly reason: "invalid-destination" | "invalid-content";
-    constructor(reason: "invalid-destination" | "invalid-content");
-}
-
-export declare interface MessageApprovalTypeDefinition {
-    readonly kind: "message";
-    readonly provider: string;
-    readonly moduleId: string;
-    readonly unknownMessage: string;
-    readonly fields: {
-        readonly body: {
-            readonly key: string;
-            readonly max: number;
-        };
-        readonly subject?: {
-            readonly key: string;
-            readonly max: number;
-        };
-    };
-    readonly presentation: {
-        readonly showAccount: boolean;
-        readonly recipient: "person" | "target";
-    };
-    /** Pure preparation; does not execute the reviewed operation. Async because the host may call it across a process boundary. */
-    readonly prepare: (input: MessageApprovalInput) => Promise<PreparedMessageApproval | undefined>;
-    readonly finalize: (input: {
-        readonly prepared: PreparedMessageApproval;
-        readonly failure?: {
-            readonly error: unknown;
-        };
-        readonly body: string;
-        readonly subject?: string;
-    }, ctx: ApprovalTypeContext) => Promise<FinalizedMessageApproval>;
-    /** Finds a saved draft this provider keeps. Omit it when the provider keeps none. */
-    readonly resolveResource?: (uri: string, ctx: ApprovalTypeContext) => Promise<UiMessageDraftResource | undefined>;
-}
-
-/** Review-specific routing inputs. The host must resolve the stable account and validate the provider route. */
-declare const messageDraftDeliveryRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    provider: z.ZodLiteral<"gmail">;
-    accountId: z.ZodString;
-    threadId: z.ZodOptional<z.ZodString>;
-    inReplyTo: z.ZodOptional<z.ZodString>;
-    references: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$strict>, z.ZodObject<{
-    provider: z.ZodLiteral<"slack">;
-    accountId: z.ZodString;
-    threadTs: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>, z.ZodObject<{
-    provider: z.ZodLiteral<"teams">;
-    accountId: z.ZodString;
-    replyTo: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>], "provider">;
-
 /**
- * The routing an INLINE card may ask the host for: Gmail, whose recipients are the card's own
- * props, or Slack, whose request names its conversation. An inline Teams card names no
- * destination the host could bind to the press, so it keeps the agent's own write.
+ * A message approval card's facts as Bonsai resolves them from the plugin's manifest. A card runs
+ * no card-specific plugin code: it is drawn with the module's `describeOperation` and sent with its
+ * `write`.
  */
-declare const messageDraftInlineDeliveryRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    provider: z.ZodLiteral<"gmail">;
-    accountId: z.ZodString;
-    threadId: z.ZodOptional<z.ZodString>;
-    inReplyTo: z.ZodOptional<z.ZodString>;
-    references: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$strict>, z.ZodObject<{
-    provider: z.ZodLiteral<"slack">;
-    accountId: z.ZodString;
-    conversationUri: z.ZodString;
-    threadTs: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>], "provider">;
-
-/** Immutable display evidence, not an approval or an editable copy of the draft. */
-export declare const messageDraftResourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    status: z.ZodLiteral<"available">;
-    draftUri: z.ZodString;
-    revision: z.ZodString;
-    content: z.ZodDiscriminatedUnion<[z.ZodObject<{
-        kind: z.ZodLiteral<"email">;
-        to: z.ZodArray<z.ZodString>;
-        cc: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        bcc: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        subject: z.ZodString;
-        bodyMarkdown: z.ZodString;
-        bodyFormat: z.ZodOptional<z.ZodLiteral<"plain">>;
-        attachments: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    }, z.core.$strict>, z.ZodObject<{
-        kind: z.ZodLiteral<"chat">;
-        provider: z.ZodEnum<{
-            slack: "slack";
-            teams: "teams";
-        }>;
-        conversationUri: z.ZodOptional<z.ZodString>;
-        bodyMarkdown: z.ZodString;
-    }, z.core.$strict>], "kind">;
-    delivery: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
-        status: z.ZodLiteral<"ready">;
-        sessionId: z.ZodString;
-        request: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject<{
-            provider: z.ZodLiteral<"gmail">;
-            accountId: z.ZodString;
-            threadId: z.ZodOptional<z.ZodString>;
-            inReplyTo: z.ZodOptional<z.ZodString>;
-            references: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        }, z.core.$strict>, z.ZodObject<{
-            provider: z.ZodLiteral<"slack">;
-            accountId: z.ZodString;
-            threadTs: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>, z.ZodObject<{
-            provider: z.ZodLiteral<"teams">;
-            accountId: z.ZodString;
-            replyTo: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>], "provider">, z.ZodObject<{
-            provider: z.ZodLiteral<"slack">;
-            accountId: z.ZodString;
-            conversationUri: z.ZodString;
-            threadTs: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>]>;
-        accountName: z.ZodOptional<z.ZodString>;
-        destination: z.ZodOptional<z.ZodString>;
-        writeUri: z.ZodString;
-    }, z.core.$strict>, z.ZodObject<{
-        status: z.ZodLiteral<"unavailable">;
-        reason: z.ZodEnum<{
-            "missing-context": "missing-context";
-            "account-unavailable": "account-unavailable";
-            "invalid-destination": "invalid-destination";
-            "invalid-content": "invalid-content";
-            "unnamed-destination": "unnamed-destination";
-        }>;
-    }, z.core.$strict>], "status">>;
-}, z.core.$strict>, z.ZodObject<{
-    status: z.ZodEnum<{
-        unavailable: "unavailable";
-        missing: "missing";
-        invalid: "invalid";
-        "unsupported-version": "unsupported-version";
-        "too-large": "too-large";
-    }>;
-    draftUri: z.ZodString;
-}, z.core.$strict>], "status">;
+export declare type MessageApprovalFacts = ResolvedKayAppApprovalType;
 
 declare interface MessageEntry extends EntryBase {
     type: "message";
@@ -9884,13 +9697,6 @@ export declare interface PreparedAccessApproval {
     readonly binding?: unknown;
 }
 
-export declare interface PreparedMessageApproval {
-    readonly uri: string;
-    readonly content: Record<string, unknown>;
-    /** Provider-private state retained only in host memory. */
-    readonly binding?: unknown;
-}
-
 declare const Properties: (input: string) => [unknown, string] | [];
 
 declare function PropertiesMapping(input: [unknown, unknown, unknown]): unknown;
@@ -9959,8 +9765,6 @@ export declare interface QualifiedApprovalTypeId {
     readonly localId: string;
 }
 
-export declare type QualifiedApprovalTypeResolver = (id: QualifiedApprovalTypeId) => ResolvedApprovalType | undefined;
-
 export declare interface RawResource {
     readonly uri: string;
     readonly content: string | Uint8Array;
@@ -10126,18 +9930,18 @@ declare function refineWebSessionScopeConfined(webSession: {
     };
 }, ctx: z.RefinementCtx): void;
 
-export declare interface RegisteredApprovalType<D extends AnyApprovalTypeDefinition = MessageApprovalTypeDefinition> {
-    readonly pluginId: string;
-    readonly localId: string;
-    readonly definition: D;
-}
-
 export declare interface RegisteredHostApprovalType {
     readonly hostId: string;
     readonly localId: string;
     readonly definition: AccessApprovalTypeDefinition;
 }
 
+export declare interface RegisteredMessageApprovalFacts {
+    readonly pluginId: string;
+    readonly localId: string;
+    readonly definition: MessageApprovalFacts;
+}
+
 declare const RegistrableDomain: z.ZodString;
 
 declare type RegistrableDomain = z.infer<typeof RegistrableDomain>;
@@ -10219,8 +10023,6 @@ declare interface RequiresAuth {
  */
 export declare function requireWriteContent(payload: UriPayload | Uint8Array | undefined, uri: string): UriPayload;
 
-export declare type ResolvedApprovalType = RegisteredApprovalType<AnyApprovalTypeDefinition> | RegisteredHostApprovalType;
-
 /**
  * The credential the host resolved for one call to plugin code that declares `requiresAuth`: a URI
  * verb (`ctx.auth.credential`), a tool (`ctx.credential`) or a search provider (`ctx.credential`).
@@ -10239,6 +10041,85 @@ declare interface ResolvedCredential {
     readonly fields?: Readonly<Record<string, string>>;
 }
 
+declare const ResolvedKayAppApprovalType: z.ZodObject<{
+    kind: z.ZodLiteral<"message">;
+    localId: z.ZodString;
+    provider: z.ZodString;
+    unknownMessage: z.ZodString;
+    fields: z.ZodObject<{
+        body: z.ZodObject<{
+            key: z.ZodString;
+            max: z.ZodNumber;
+        }, z.core.$strict>;
+        subject: z.ZodOptional<z.ZodObject<{
+            key: z.ZodString;
+            max: z.ZodNumber;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    presentation: z.ZodObject<{
+        showAccount: z.ZodBoolean;
+        recipient: z.ZodEnum<{
+            target: "target";
+            person: "person";
+        }>;
+    }, z.core.$strict>;
+    forms: z.ZodObject<{
+        inline: z.ZodOptional<z.ZodObject<{
+            uri: z.ZodUnion<readonly [z.ZodObject<{
+                fixed: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                value: z.ZodString;
+            }, z.core.$strict>]>;
+            requestFields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            payload: z.ZodRecord<z.ZodString, z.ZodString>;
+            fixed: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>>>;
+        }, z.core.$strict>>;
+        saved: z.ZodOptional<z.ZodObject<{
+            uri: z.ZodUnion<readonly [z.ZodObject<{
+                fixed: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                value: z.ZodString;
+            }, z.core.$strict>]>;
+            requestFields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            payload: z.ZodRecord<z.ZodString, z.ZodString>;
+            fixed: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>>>;
+        }, z.core.$strict>>;
+        stored: z.ZodOptional<z.ZodObject<{
+            uri: z.ZodUnion<readonly [z.ZodObject<{
+                fixed: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                value: z.ZodString;
+            }, z.core.$strict>]>;
+            requestFields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            payload: z.ZodRecord<z.ZodString, z.ZodString>;
+            fixed: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>>>;
+            read: z.ZodObject<{
+                revision: z.ZodString;
+                body: z.ZodString;
+                subject: z.ZodOptional<z.ZodString>;
+                to: z.ZodOptional<z.ZodString>;
+                cc: z.ZodOptional<z.ZodString>;
+                bcc: z.ZodOptional<z.ZodString>;
+                attachments: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    display: z.ZodOptional<z.ZodObject<{
+        bodyFormat: z.ZodOptional<z.ZodLiteral<"mrkdwn">>;
+        replyField: z.ZodOptional<z.ZodString>;
+        replyLabel: z.ZodOptional<z.ZodString>;
+        facts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            field: z.ZodString;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+    globalId: z.ZodString;
+    moduleId: z.ZodString;
+    authService: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+
+declare type ResolvedKayAppApprovalType = z.infer<typeof ResolvedKayAppApprovalType>;
+
 /** Match remaining characters in the buffer until end. If no characters are in buffer, no match */
 declare function Rest<Input extends string>(input: Input): TRest<Input>;
 
@@ -15321,12 +15202,6 @@ declare type UiActionMessage = CustomMessage<UiActionDetails> & {
     readonly display: true;
 };
 
-declare type UiMessageDraftDeliveryRequest = z.infer<typeof messageDraftDeliveryRequestSchema>;
-
-declare type UiMessageDraftInlineDeliveryRequest = z.infer<typeof messageDraftInlineDeliveryRequestSchema>;
-
-export declare type UiMessageDraftResource = z.infer<typeof messageDraftResourceSchema>;
-
 /** Applies a Uncapitalize action to the given type. */
 declare function Uncapitalize_2<Type extends TSchema>(type: Type, options?: TSchemaOptions): TUncapitalize<Type>;
 
@@ -16069,6 +15944,8 @@ export declare class UriProviderError extends UriError {
     readonly retryAfterMs?: number;
     /** See {@link UriProviderErrorOptions.effect}. */
     readonly effect?: "none";
+    /** See {@link UriProviderErrorOptions.refusalMessage}. */
+    readonly refusalMessage?: string;
     constructor(options: UriProviderErrorOptions);
 }
 
@@ -16091,6 +15968,11 @@ export declare interface UriProviderErrorOptions {
      * earlier request may have changed something.
      */
     readonly effect?: "none";
+    /**
+     * What to tell the person when a write they approved was refused, in their words. Only with
+     * `effect: "none"`: it is the plugin saying nothing happened and why.
+     */
+    readonly refusalMessage?: string;
 }
 
 /**

package/dist/kay-app.js

@@ -299,6 +299,8 @@ var UriProviderError = class extends UriError {
   retryAfterMs;
   /** See {@link UriProviderErrorOptions.effect}. */
   effect;
+  /** See {@link UriProviderErrorOptions.refusalMessage}. */
+  refusalMessage;
   constructor(options) {
     super(options.message);
     this.name = "UriProviderError";
@@ -319,6 +321,12 @@ var UriProviderError = class extends UriError {
     }
     if (options.effect !== void 0)
       this.effect = options.effect;
+    if (options.refusalMessage !== void 0) {
+      if (options.effect !== "none") {
+        throw new TypeError('refusalMessage requires effect: "none".');
+      }
+      this.refusalMessage = options.refusalMessage;
+    }
   }
 };
 var UriNotFoundError = class extends UriError {
@@ -537,189 +545,6 @@ function isRetryable(result) {
   return result.status === "not-ready";
 }
 
-// packages/kay-ui-catalog/dist/message-draft-resource.js
-import { z as z7 } from "zod";
-var MESSAGE_DRAFT_SUBJECT_MAX = 300;
-var MESSAGE_DRAFT_BODY_MAX = 2e4;
-var MESSAGE_DRAFT_RESOURCE_MAX = 8;
-var UI_RENDER_RESULT_MAX_BYTES = 64 * 1024;
-var contextIdSchema = z7.string().min(1).max(2048);
-var gmailDeliveryRequestSchema = z7.strictObject({
-  provider: z7.literal("gmail"),
-  accountId: contextIdSchema,
-  threadId: contextIdSchema.optional(),
-  inReplyTo: contextIdSchema.optional(),
-  references: z7.array(contextIdSchema).max(50).optional()
-});
-var messageDraftDeliveryRequestSchema = z7.discriminatedUnion("provider", [
-  gmailDeliveryRequestSchema,
-  z7.strictObject({
-    provider: z7.literal("slack"),
-    accountId: contextIdSchema,
-    threadTs: contextIdSchema.optional()
-  }),
-  z7.strictObject({
-    provider: z7.literal("teams"),
-    accountId: contextIdSchema,
-    replyTo: contextIdSchema.optional()
-  })
-]);
-var slackInlineDeliveryRequestSchema = z7.strictObject({
-  provider: z7.literal("slack"),
-  accountId: contextIdSchema,
-  /**
-   * The conversation itself: `slack://channels/<id>`, or the same under `slack://@<accountId>/`.
-   * A thread's address is refused unless `threadTs` names the same thread, because the card shows
-   * a reply only from `threadTs`.
-   */
-  conversationUri: contextIdSchema,
-  threadTs: contextIdSchema.optional()
-});
-var messageDraftInlineDeliveryRequestSchema = z7.discriminatedUnion("provider", [gmailDeliveryRequestSchema, slackInlineDeliveryRequestSchema]);
-var messageDraftResourcePropsSchema = z7.strictObject({
-  draftUri: z7.string().min(1).max(2048),
-  editable: z7.boolean().optional(),
-  delivery: messageDraftDeliveryRequestSchema.optional()
-});
-var deliveryResultSchema = z7.discriminatedUnion("status", [
-  z7.strictObject({
-    status: z7.literal("ready"),
-    sessionId: contextIdSchema,
-    // A saved draft's request, or an inline card's. They differ only for Slack, where the inline
-    // form carries `conversationUri`; each strict variant refuses the other's shape.
-    request: z7.union([
-      messageDraftDeliveryRequestSchema,
-      slackInlineDeliveryRequestSchema
-    ]),
-    accountName: z7.string().min(1).max(2048).optional(),
-    /**
-     * Where a chat message lands, named as the provider named it when the card was drawn
-     * (`#engineering`, `Alex Kim <alex@example.com> (direct message)`: a direct message by the
-     * person's name and Slack email, never a display name alone; Slack's module may answer from its
-     * own name cache, up to a day old, never for another conversation). The card shows this instead of the
-     * agent's own `to` label. Absent for email, whose recipients are the card's own props.
-     */
-    destination: z7.string().min(1).max(2048).optional(),
-    writeUri: contextIdSchema
-  }),
-  z7.strictObject({
-    status: z7.literal("unavailable"),
-    reason: z7.enum([
-      "missing-context",
-      "account-unavailable",
-      "invalid-destination",
-      "invalid-content",
-      // The provider could not name the conversation in time, so the card could not show the
-      // person where Send would post.
-      "unnamed-destination"
-    ])
-  })
-]);
-var contentSchema = z7.discriminatedUnion("kind", [
-  z7.strictObject({
-    kind: z7.literal("email"),
-    to: z7.array(z7.string().max(320)).max(50),
-    /** Copy recipients a draft stored in the mail provider carries; a Whiteboard draft has none. */
-    cc: z7.array(z7.string().max(320)).max(50).optional(),
-    bcc: z7.array(z7.string().max(320)).max(50).optional(),
-    subject: z7.string().max(MESSAGE_DRAFT_SUBJECT_MAX),
-    bodyMarkdown: z7.string().max(MESSAGE_DRAFT_BODY_MAX),
-    /**
-     * `plain` when `bodyMarkdown` holds the literal text of a draft stored in the mail provider,
-     * which is sent as written and must not be shown through a Markdown reading. Absent means
-     * Markdown, the Whiteboard draft's format.
-     */
-    bodyFormat: z7.literal("plain").optional(),
-    /** File names a draft stored in the mail provider carries (names only, never content). */
-    attachments: z7.array(z7.string().min(1).max(200)).max(20).optional()
-  }),
-  z7.strictObject({
-    kind: z7.literal("chat"),
-    provider: z7.enum(["slack", "teams"]),
-    conversationUri: z7.string().max(2048).optional(),
-    bodyMarkdown: z7.string().max(MESSAGE_DRAFT_BODY_MAX)
-  })
-]);
-var messageDraftResourceSchema = z7.discriminatedUnion("status", [
-  z7.strictObject({
-    status: z7.literal("available"),
-    draftUri: z7.string().min(1).max(2048),
-    revision: z7.string().min(1).max(256),
-    content: contentSchema,
-    delivery: deliveryResultSchema.optional()
-  }).refine(({ content, delivery }) => delivery?.status !== "ready" || delivery.request.provider === (content.kind === "email" ? "gmail" : content.provider) && // A saved draft names its own conversation; only an inline card's request carries one.
-  messageDraftDeliveryRequestSchema.safeParse(delivery.request).success, "Delivery provider must match the saved content"),
-  z7.strictObject({
-    status: z7.enum([
-      "missing",
-      "unavailable",
-      "invalid",
-      "unsupported-version",
-      "too-large"
-    ]),
-    draftUri: z7.string().max(2048)
-  })
-]);
-var messageDraftResourceSubmissionSchema = z7.strictObject({
-  version: z7.literal(1),
-  approved: z7.literal(true),
-  elementId: z7.string().min(1).max(2048),
-  draftUri: z7.string().min(1).max(2048),
-  revision: z7.string().min(1).max(256),
-  body: z7.string().max(MESSAGE_DRAFT_BODY_MAX),
-  subject: z7.string().max(MESSAGE_DRAFT_SUBJECT_MAX).optional()
-});
-var messageDraftApprovalWriteSchema = z7.strictObject({
-  messageDraftApproval: z7.strictObject({
-    version: z7.literal(1),
-    toolCallId: contextIdSchema
-  })
-});
-var messageDraftSentDetailsSchema = z7.object({
-  version: z7.literal(1),
-  /** The `ui_render` call that drew the card. */
-  reviewToolCallId: z7.string().min(1),
-  /** The MessageDraft element within that render. */
-  elementId: z7.string().min(1),
-  /** The send intent that produced this record. */
-  clientIntentId: z7.string().min(1),
-  provider: z7.enum(["gmail", "slack"]),
-  accountId: z7.string().min(1),
-  accountName: z7.string().min(1).optional(),
-  /** A chat message's conversation as the card named it (`#engineering`); absent for email. */
-  destination: z7.string().min(1).optional(),
-  /** ISO 8601 instant the provider accepted the send. */
-  sentAt: z7.string().min(1),
-  /**
-   * The sent message, addressed under its account (`gmail://@<accountId>/messages/<id>`,
-   * `slack://@<accountId>/channels/<id>/messages/<ts>`), when the provider named it.
-   */
-  sentMessageUri: z7.string().min(1).optional(),
-  subject: z7.string().max(MESSAGE_DRAFT_SUBJECT_MAX).optional(),
-  body: z7.string().max(MESSAGE_DRAFT_BODY_MAX)
-});
-var uiRenderResultDetailsSchema = z7.union([
-  z7.strictObject({
-    version: z7.literal(1),
-    messageDrafts: z7.record(z7.string(), messageDraftResourceSchema).refine((drafts) => Object.keys(drafts).length <= MESSAGE_DRAFT_RESOURCE_MAX).optional(),
-    inlineDeliveries: z7.record(z7.string(), deliveryResultSchema).refine((deliveries) => Object.keys(deliveries).length <= MESSAGE_DRAFT_RESOURCE_MAX).refine((deliveries) => Object.values(deliveries).every((delivery) => delivery.status !== "ready" || messageDraftInlineDeliveryRequestSchema.safeParse(delivery.request).success)).optional()
-  }).refine((details) => details.messageDrafts !== void 0 || details.inlineDeliveries !== void 0).refine((details) => new TextEncoder().encode(JSON.stringify(details)).byteLength <= UI_RENDER_RESULT_MAX_BYTES),
-  z7.strictObject({
-    version: z7.literal(1),
-    error: z7.literal("resource-limit-exceeded")
-  })
-]);
-
-// packages/plugin-sdk/dist/kay-app/approvals.js
-var MessageApprovalPreparationError = class extends Error {
-  reason;
-  constructor(reason) {
-    super(reason);
-    this.reason = reason;
-    this.name = "MessageApprovalPreparationError";
-  }
-};
-
 // packages/plugin-sdk/dist/kay-app/auth.js
 var KayAppCredentialRejectedError = class extends Error {
   name = "KayAppCredentialRejectedError";
@@ -1072,9 +897,6 @@ export {
   KayAppCredentialRejectedError,
   KayAppWorkflowFailure,
   MAX_CHOICE_LABELS,
-  MESSAGE_DRAFT_BODY_MAX,
-  MESSAGE_DRAFT_SUBJECT_MAX,
-  MessageApprovalPreparationError,
   SIGNAL_TIME_MAX_MS,
   STORED_TRANSCRIPT_MESSAGE_FILTER,
   STORED_TRANSCRIPT_MESSAGE_KINDS,
@@ -1094,7 +916,6 @@ export {
   failedRunCause,
   invalidObservation,
   isRetryable,
-  messageDraftResourceSchema,
   parseLineSelector,
   parseStoredTranscriptKindFilter,
   pathToFileURL,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaklabs-ai/plugin-sdk",
-  "version": "0.26.3",
+  "version": "0.27.0",
   "description": "The Kay plugin SDK — types and helpers for authoring a Kay directory plugin.",
   "author": "YakLabs",
   "type": "module",