@yaklabs-ai/plugin-sdk 0.47.0 → 0.48.1

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.47.0"
+    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.48.1"
   }
 }
 ```
@@ -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.47.0" },
+  "compatibility": { "sdk": "^0.48.1" },
   "targets": {
     "kay": {
       "agent": {

package/THIRD-PARTY-INVENTORY.json

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

package/dist/canonical-transcript.d.ts

@@ -2152,6 +2152,8 @@ declare interface InteractiveQueuedMessage {
     readonly attachments?: AttachmentsDetails["refs"] | undefined;
     readonly context?: readonly ManagedHumanQueueContextPart[] | undefined;
     readonly resendError?: string | undefined;
+    /** Why this message is waiting, when something is stopping its delivery. */
+    readonly deliveryError?: string | undefined;
     /**
      * Managed-queue lifecycle, present only for items projected from a
      * `managed_human_queue_update` snapshot: `queued` (live in a delivery queue) or `editing`
@@ -2656,6 +2658,7 @@ declare interface ManagedHumanQueueItemSnapshot {
     readonly attachments?: AttachmentsDetails["refs"] | undefined;
     readonly context?: readonly ManagedHumanQueueContextPart[] | undefined;
     readonly resendError?: string | undefined;
+    readonly deliveryError?: string | undefined;
 }
 
 /**

package/dist/canonical-transcript.js

@@ -445,6 +445,7 @@ var HerdSessionProjection = z4.discriminatedUnion("type", [
         attachments: z4.array(ManagedQueueAttachmentRef).optional(),
         context: z4.array(ManagedQueueContextPart).optional(),
         resendError: z4.string().optional(),
+        deliveryError: z4.string().optional(),
         text: z4.string(),
         channel: z4.enum(["follow_up", "steer"]),
         status: z4.enum(["queued", "editing"])
@@ -1966,6 +1967,7 @@ function reduceManagedHumanQueueUpdate(state, event) {
     });
     const context = extractQueuedMessageContext(record);
     const resendError = getString(record, "resendError");
+    const deliveryError = getString(record, "deliveryError");
     return [
       {
         id,
@@ -1976,6 +1978,7 @@ function reduceManagedHumanQueueUpdate(state, event) {
         ...attachments === void 0 || attachments.length === 0 ? {} : { attachments },
         ...context === void 0 ? {} : { context },
         ...resendError === void 0 ? {} : { resendError },
+        ...deliveryError === void 0 ? {} : { deliveryError },
         ...status === "queued" || status === "editing" ? { status } : {}
       }
     ];

package/dist/disclosure.d.ts

@@ -2444,8 +2444,12 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * and read the provenance the host captured. Additive: a plugin that imports it declares ^0.46.0.
  *
  * 0.47.0 adds card layouts and builders; successful card submits now require a summary.
+ *
+ * 0.48.0 adds the models.complete UI capability.
+ *
+ * 0.48.1 adds app-tool metadata, conditional tool permissions and screen-action declarations.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.47.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.48.1";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 

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

@@ -2498,8 +2498,12 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * and read the provenance the host captured. Additive: a plugin that imports it declares ^0.46.0.
  *
  * 0.47.0 adds card layouts and builders; successful card submits now require a summary.
+ *
+ * 0.48.0 adds the models.complete UI capability.
+ *
+ * 0.48.1 adds app-tool metadata, conditional tool permissions and screen-action declarations.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.47.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.48.1";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -5362,6 +5366,32 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
         }, z.core.$strict>;
     }, z.core.$strict>>;
     kayAgentUriModules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        screenActions: z.ZodExactOptional<z.ZodObject<{
+            scheme: z.ZodString;
+            hosts: z.ZodArray<z.ZodString>;
+            paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            apps: z.ZodArray<z.ZodString>;
+            options: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"exact">;
+                description: z.ZodString;
+                verb: z.ZodEnum<{
+                    read: "read";
+                    write: "write";
+                    edit: "edit";
+                    delete: "delete";
+                }>;
+                uri: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"catch-all">;
+                description: z.ZodString;
+                verb: z.ZodEnum<{
+                    read: "read";
+                    write: "write";
+                    edit: "edit";
+                    delete: "delete";
+                }>;
+            }, z.core.$strict>], "kind">>;
+        }, z.core.$strict>>;
         claims: z.ZodExactOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
             kind: z.ZodLiteral<"scheme">;
             scheme: z.ZodString;
@@ -5398,27 +5428,27 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                 list: "list";
                 read: "read";
                 write: "write";
-                help: "help";
                 edit: "edit";
                 delete: "delete";
+                help: "help";
             }>>>;
             operationDocs: z.ZodExactOptional<z.ZodRecord<z.ZodEnum<{
                 search: "search";
                 list: "list";
                 read: "read";
                 write: "write";
-                help: "help";
                 edit: "edit";
                 delete: "delete";
+                help: "help";
             }> & z.core.$partial, z.ZodString>>;
             operationDefaults: z.ZodExactOptional<z.ZodRecord<z.ZodEnum<{
                 search: "search";
                 list: "list";
                 read: "read";
                 write: "write";
-                help: "help";
                 edit: "edit";
                 delete: "delete";
+                help: "help";
             }> & z.core.$partial, z.ZodEnum<{
                 never: "never";
                 allow: "allow";
@@ -5480,9 +5510,9 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                     list: "list";
                     read: "read";
                     write: "write";
-                    help: "help";
                     edit: "edit";
                     delete: "delete";
+                    help: "help";
                 }>>>;
                 routes: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
                 query: z.ZodExactOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
@@ -5493,9 +5523,9 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                     list: "list";
                     read: "read";
                     write: "write";
-                    help: "help";
                     edit: "edit";
                     delete: "delete";
+                    help: "help";
                 }>>>;
                 routes: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
                 query: z.ZodExactOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
@@ -5584,15 +5614,80 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
             scheme: z.ZodOptional<z.ZodString>;
             resourcePrefix: z.ZodOptional<z.ZodString>;
             resourceArgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            resourceTrim: z.ZodOptional<z.ZodLiteral<true>>;
+            defaultPermission: z.ZodOptional<z.ZodEnum<{
+                never: "never";
+                allow: "allow";
+                ask: "ask";
+            }>>;
+            classificationRules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                when: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                    arg: z.ZodString;
+                    equals: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+                }, z.core.$strict>, z.ZodObject<{
+                    arg: z.ZodString;
+                    present: z.ZodBoolean;
+                }, z.core.$strict>]>>;
+                kind: z.ZodEnum<{
+                    read: "read";
+                    mutate: "mutate";
+                    destructive: "destructive";
+                    execute: "execute";
+                }>;
+                ruleKey: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>>;
         }, z.core.$strict>>;
         localId: z.ZodString;
         globalId: z.ZodString;
         toolName: z.ZodString;
     }, z.core.$strict>>>;
     kayAppTools: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
         localId: z.ZodString;
-        globalId: z.ZodString;
+        displayName: z.ZodOptional<z.ZodString>;
         toolName: z.ZodString;
+        parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>>;
+        executionMode: z.ZodOptional<z.ZodEnum<{
+            sequential: "sequential";
+            parallel: "parallel";
+        }>>;
+        promptSnippet: z.ZodOptional<z.ZodString>;
+        promptGuidelines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        permission: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodEnum<{
+                read: "read";
+                mutate: "mutate";
+                destructive: "destructive";
+                execute: "execute";
+            }>;
+            ruleKey: z.ZodOptional<z.ZodString>;
+            scheme: z.ZodOptional<z.ZodString>;
+            resourcePrefix: z.ZodOptional<z.ZodString>;
+            resourceArgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            resourceTrim: z.ZodOptional<z.ZodLiteral<true>>;
+            defaultPermission: z.ZodOptional<z.ZodEnum<{
+                never: "never";
+                allow: "allow";
+                ask: "ask";
+            }>>;
+            classificationRules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                when: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                    arg: z.ZodString;
+                    equals: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+                }, z.core.$strict>, z.ZodObject<{
+                    arg: z.ZodString;
+                    present: z.ZodBoolean;
+                }, z.core.$strict>]>>;
+                kind: z.ZodEnum<{
+                    read: "read";
+                    mutate: "mutate";
+                    destructive: "destructive";
+                    execute: "execute";
+                }>;
+                ruleKey: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>>;
+        globalId: z.ZodString;
     }, z.core.$strict>>>;
     kayAppApprovalTypes: z.ZodOptional<z.ZodArray<z.ZodObject<{
         kind: z.ZodLiteral<"message">;
@@ -5917,6 +6012,7 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
             host: z.ZodOptional<z.ZodArray<z.ZodEnum<{
                 "navigation.open-session": "navigation.open-session";
                 "sessions.create": "sessions.create";
+                "models.complete": "models.complete";
                 "artifacts.read": "artifacts.read";
                 "artifacts.preview": "artifacts.preview";
                 "markdown.document-view": "markdown.document-view";

package/dist/kay-agent-testing.js

@@ -123,16 +123,31 @@ function createKayPluginLog(write, bound = {}) {
 }
 
 // packages/plugin-sdk/dist/kay-agent/declared-tool.js
-function permissionHint(permission) {
-  const { kind, ruleKey, resourceArgs, scheme, resourcePrefix } = permission;
+function declaredToolPermission(permission) {
+  const { kind, ruleKey, resourceArgs, scheme, resourcePrefix, resourceTrim, defaultPermission, classificationRules } = permission;
   return {
     kind,
     ...scheme === void 0 ? {} : { scheme },
     ...ruleKey === void 0 ? {} : { ruleKey },
+    ...defaultPermission === void 0 ? {} : { defaultPermission },
+    ...classificationRules === void 0 ? {} : {
+      deriveClassification: (input) => {
+        const rule = classificationRules.find((candidate) => candidate.when.every((condition) => {
+          const value = Object.hasOwn(input, condition.arg) ? input[condition.arg] : void 0;
+          return "equals" in condition ? value === condition.equals : value !== void 0 === condition.present;
+        }));
+        return rule === void 0 ? void 0 : {
+          kind: rule.kind,
+          ...rule.ruleKey === void 0 ? {} : { ruleKey: rule.ruleKey }
+        };
+      }
+    },
     ...resourceArgs === void 0 ? {} : {
       deriveResources: (input) => resourceArgs.flatMap((arg) => {
         const value = input[arg];
-        return typeof value === "string" ? [`${resourcePrefix ?? ""}${value}`] : [];
+        return typeof value === "string" ? [
+          `${resourcePrefix ?? ""}${resourceTrim === true ? value.trim() : value}`
+        ] : [];
       })
     }
   };
@@ -156,7 +171,7 @@ function declaredToolDefinition(tool, execute) {
         ...requiresAuth.schemeId === void 0 ? {} : { schemeId: requiresAuth.schemeId }
       }
     },
-    ...permission === void 0 ? {} : { permission: permissionHint(permission) },
+    ...permission === void 0 ? {} : { permission: declaredToolPermission(permission) },
     execute
   };
 }

package/dist/kay-agent.d.ts

@@ -2773,8 +2773,12 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * and read the provenance the host captured. Additive: a plugin that imports it declares ^0.46.0.
  *
  * 0.47.0 adds card layouts and builders; successful card submits now require a summary.
+ *
+ * 0.48.0 adds the models.complete UI capability.
+ *
+ * 0.48.1 adds app-tool metadata, conditional tool permissions and screen-action declarations.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.47.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.48.1";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 

package/dist/kay-app.d.ts

@@ -1139,6 +1139,9 @@ declare interface Decision<Q extends DecideQuestions = DecideQuestions> {
     readonly usage?: SystemOneTokenUsage;
 }
 
+/** Builds an app tool from manifest facts, retaining its execution, availability and preview callbacks. */
+export declare function declaredAppToolDefinition(tool: ToolContribution, implementation: KayAppToolImplementation): KayAppToolDefinition;
+
 /** Createsa  uni-directional Codec with Decode only. The Decode function is called on Value.Decode */
 declare function Decode<Type extends TSchema, Callback extends TDecodeCallback<StaticDecode<Type>, unknown>>(type: Type, callback: Callback): TCodec<Type, ReturnType<Callback>>;
 
@@ -2880,8 +2883,12 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * and read the provenance the host captured. Additive: a plugin that imports it declares ^0.46.0.
  *
  * 0.47.0 adds card layouts and builders; successful card submits now require a summary.
+ *
+ * 0.48.0 adds the models.complete UI capability.
+ *
+ * 0.48.1 adds app-tool metadata, conditional tool permissions and screen-action declarations.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.47.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.48.1";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -7860,6 +7867,10 @@ export declare interface KayAppToolEvents {
     subscribe(handler: (event: unknown) => void): () => void;
 }
 
+export declare type KayAppToolImplementation = Omit<KayAppToolDefinition, "label" | "description" | "parameters" | "permission" | "executionMode" | "promptSnippet" | "promptGuidelines"> & {
+    readonly permission?: Pick<ToolPermissionHint, "describePreview">;
+};
+
 /** Where a described tool or address comes from. */
 export declare type KayAppToolOrigin = 
 /** The agent kernel's own (`bash`, `read`, `help`, `skill://`). */
@@ -14198,6 +14209,56 @@ declare interface ToolContext {
     readonly paths?: ExtensionPaths;
 }
 
+export declare const ToolContribution: z.ZodObject<{
+    parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>>;
+    executionMode: z.ZodOptional<z.ZodEnum<{
+        sequential: "sequential";
+        parallel: "parallel";
+    }>>;
+    promptSnippet: z.ZodOptional<z.ZodString>;
+    promptGuidelines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    permission: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodEnum<{
+            read: "read";
+            mutate: "mutate";
+            destructive: "destructive";
+            execute: "execute";
+        }>;
+        ruleKey: z.ZodOptional<z.ZodString>;
+        scheme: z.ZodOptional<z.ZodString>;
+        resourcePrefix: z.ZodOptional<z.ZodString>;
+        resourceArgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        resourceTrim: z.ZodOptional<z.ZodLiteral<true>>;
+        defaultPermission: z.ZodOptional<z.ZodEnum<{
+            never: "never";
+            allow: "allow";
+            ask: "ask";
+        }>>;
+        classificationRules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            when: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                arg: z.ZodString;
+                equals: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+            }, z.core.$strict>, z.ZodObject<{
+                arg: z.ZodString;
+                present: z.ZodBoolean;
+            }, z.core.$strict>]>>;
+            kind: z.ZodEnum<{
+                read: "read";
+                mutate: "mutate";
+                destructive: "destructive";
+                execute: "execute";
+            }>;
+            ruleKey: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+    localId: z.ZodString;
+    toolName: z.ZodString;
+    displayName: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+
+export declare type ToolContribution = z.infer<typeof ToolContribution>;
+
 export declare interface ToolDefinition<TParams extends ToolParametersWire = ToolParametersWire, TDetails = unknown> {
     /** Tool name (used in LLM tool calls) */
     name: string;

package/dist/kay-app.js

@@ -880,6 +880,60 @@ function refusedCountOf(error) {
   return typeof count === "number" && Number.isSafeInteger(count) && count > 0 ? count : 1;
 }
 
+// packages/plugin-sdk/dist/kay-agent/declared-tool.js
+function declaredToolPermission(permission) {
+  const { kind, ruleKey, resourceArgs, scheme, resourcePrefix, resourceTrim, defaultPermission, classificationRules } = permission;
+  return {
+    kind,
+    ...scheme === void 0 ? {} : { scheme },
+    ...ruleKey === void 0 ? {} : { ruleKey },
+    ...defaultPermission === void 0 ? {} : { defaultPermission },
+    ...classificationRules === void 0 ? {} : {
+      deriveClassification: (input) => {
+        const rule = classificationRules.find((candidate) => candidate.when.every((condition) => {
+          const value = Object.hasOwn(input, condition.arg) ? input[condition.arg] : void 0;
+          return "equals" in condition ? value === condition.equals : value !== void 0 === condition.present;
+        }));
+        return rule === void 0 ? void 0 : {
+          kind: rule.kind,
+          ...rule.ruleKey === void 0 ? {} : { ruleKey: rule.ruleKey }
+        };
+      }
+    },
+    ...resourceArgs === void 0 ? {} : {
+      deriveResources: (input) => resourceArgs.flatMap((arg) => {
+        const value = input[arg];
+        return typeof value === "string" ? [
+          `${resourcePrefix ?? ""}${resourceTrim === true ? value.trim() : value}`
+        ] : [];
+      })
+    }
+  };
+}
+
+// packages/plugin-sdk/dist/kay-app/declared-tool.js
+function declaredAppToolDefinition(tool, implementation) {
+  if (tool.parameters === void 0 || tool.description === void 0) {
+    throw new Error(`Tool '${tool.toolName}' declares no parameters or description.`);
+  }
+  const { permission: preview, label: _label, description: _description, parameters: _parameters, executionMode: _executionMode, promptSnippet: _promptSnippet, promptGuidelines: _promptGuidelines, ...callbacks } = implementation;
+  return {
+    ...callbacks,
+    label: tool.displayName ?? tool.toolName,
+    description: tool.description,
+    parameters: tool.parameters,
+    ...tool.executionMode === void 0 ? {} : { executionMode: tool.executionMode },
+    ...tool.promptSnippet === void 0 ? {} : { promptSnippet: tool.promptSnippet },
+    ...tool.promptGuidelines === void 0 ? {} : { promptGuidelines: tool.promptGuidelines },
+    ...tool.permission === void 0 ? {} : {
+      permission: {
+        ...declaredToolPermission(tool.permission),
+        ...preview?.describePreview === void 0 ? {} : { describePreview: preview.describePreview }
+      }
+    }
+  };
+}
+
 // packages/plugin-sdk/dist/kay-app/sealing.js
 var KAY_APP_SEALING_MAX_BYTES = 1048576;
 function createUnavailableSealing(message) {
@@ -1031,6 +1085,7 @@ export {
   createUnavailableSkills,
   createUnavailableTools,
   createUnavailableUsage,
+  declaredAppToolDefinition,
   definePoller,
   failedRunCause,
   invalidObservation,

package/package.json

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