@yaklabs-ai/plugin-sdk 0.15.0 → 0.15.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.15.0"
+    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.15.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.15.0" },
+  "compatibility": { "sdk": "^0.15.1" },
   "targets": {
     "kay": {
       "agent": {

package/THIRD-PARTY-INVENTORY.json

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

package/dist/disclosure.d.ts

@@ -7077,6 +7077,14 @@ declare type ToolParametersWire = unknown;
  * declares {@link ToolPermissionHint.quiet} and keeps its honest `kind`.
  */
 declare interface ToolPermissionHint {
+    /**
+     * Names this exact call for the approval card, from its validated input: a title and optional
+     * labelled facts. Render-only: never matched against a rule, never one-tap approval grounds.
+     * The tool says what its input claims, so the gate shows it as the tool's claim, not as the
+     * daemon's attestation. The host admits only display-safe text; a throw, a blank title or an
+     * unsafe string costs the description and the call is asked about as before.
+     */
+    readonly describePreview?: (input: Record<string, unknown>) => ToolPreviewDescription | undefined;
     readonly kind?: ToolActionKind;
     readonly scheme?: string;
     readonly ruleKey?: string;
@@ -7203,6 +7211,16 @@ declare interface ToolPermissionHint {
     readonly defaultPermission?: "allow" | "ask" | "never";
 }
 
+/** What {@link ToolPermissionHint.describePreview} answers. */
+declare interface ToolPreviewDescription {
+    readonly title: string;
+    readonly description?: string;
+    readonly fields?: readonly {
+        readonly label: string;
+        readonly value: string;
+    }[];
+}
+
 /** Controls whether a tool is expected to complete inline or via background adoption. */
 declare type ToolRunPolicy = "inline" | "background";
 

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

@@ -7000,6 +7000,14 @@ declare type ToolParametersWire = unknown;
  * declares {@link ToolPermissionHint.quiet} and keeps its honest `kind`.
  */
 declare interface ToolPermissionHint {
+    /**
+     * Names this exact call for the approval card, from its validated input: a title and optional
+     * labelled facts. Render-only: never matched against a rule, never one-tap approval grounds.
+     * The tool says what its input claims, so the gate shows it as the tool's claim, not as the
+     * daemon's attestation. The host admits only display-safe text; a throw, a blank title or an
+     * unsafe string costs the description and the call is asked about as before.
+     */
+    readonly describePreview?: (input: Record<string, unknown>) => ToolPreviewDescription | undefined;
     readonly kind?: ToolActionKind;
     readonly scheme?: string;
     readonly ruleKey?: string;
@@ -7126,6 +7134,16 @@ declare interface ToolPermissionHint {
     readonly defaultPermission?: "allow" | "ask" | "never";
 }
 
+/** What {@link ToolPermissionHint.describePreview} answers. */
+declare interface ToolPreviewDescription {
+    readonly title: string;
+    readonly description?: string;
+    readonly fields?: readonly {
+        readonly label: string;
+        readonly value: string;
+    }[];
+}
+
 /** Controls whether a tool is expected to complete inline or via background adoption. */
 declare type ToolRunPolicy = "inline" | "background";
 

package/dist/kay-agent.d.ts

@@ -9053,6 +9053,14 @@ export declare type ToolParametersWire = unknown;
  * declares {@link ToolPermissionHint.quiet} and keeps its honest `kind`.
  */
 declare interface ToolPermissionHint {
+    /**
+     * Names this exact call for the approval card, from its validated input: a title and optional
+     * labelled facts. Render-only: never matched against a rule, never one-tap approval grounds.
+     * The tool says what its input claims, so the gate shows it as the tool's claim, not as the
+     * daemon's attestation. The host admits only display-safe text; a throw, a blank title or an
+     * unsafe string costs the description and the call is asked about as before.
+     */
+    readonly describePreview?: (input: Record<string, unknown>) => ToolPreviewDescription | undefined;
     readonly kind?: ToolActionKind;
     readonly scheme?: string;
     readonly ruleKey?: string;
@@ -9179,6 +9187,16 @@ declare interface ToolPermissionHint {
     readonly defaultPermission?: "allow" | "ask" | "never";
 }
 
+/** What {@link ToolPermissionHint.describePreview} answers. */
+declare interface ToolPreviewDescription {
+    readonly title: string;
+    readonly description?: string;
+    readonly fields?: readonly {
+        readonly label: string;
+        readonly value: string;
+    }[];
+}
+
 /** Controls whether a tool is expected to complete inline or via background adoption. */
 export declare type ToolRunPolicy = "inline" | "background";
 

package/dist/kay-app-session-summary.d.ts

@@ -2884,6 +2884,7 @@ declare const SessionProvenanceRecord: z.ZodObject<{
             cron: "cron";
             occurrence: "occurrence";
             "uri-change": "uri-change";
+            "plugin-event": "plugin-event";
             manual: "manual";
         }>;
     }, z.core.$strict>, z.ZodObject<{

package/dist/kay-app.d.ts

@@ -1850,7 +1850,7 @@ declare type JsonValue_4 = null | boolean | number | string | readonly JsonValue
  * the union and not to this list, so the next kind cannot repeat that bug
  * quietly.
  */
-export declare const KAY_APP_AUTOMATION_CONDITION_KINDS: readonly ["time", "uri-change", "occurrence", "delayed-occurrence"];
+export declare const KAY_APP_AUTOMATION_CONDITION_KINDS: readonly ["time", "uri-change", "plugin-event", "occurrence", "delayed-occurrence"];
 
 /** Maximum UTF-8 JSON size of one plugin app-data live change. */
 export declare const KAY_APP_DATA_CHANGE_MAX_BYTES: number;
@@ -2473,7 +2473,7 @@ export declare interface KayAppAutomationBinding {
     readonly scriptLastError?: string;
 }
 
-export declare type KayAppAutomationCondition = Extract<KayAppAutomationConditionInput, {
+export declare type KayAppAutomationCondition = KayAppAutomationPluginEventCondition | Extract<KayAppAutomationConditionInput, {
     readonly kind: "time";
 }> | KayAppAutomationUriChangeCondition | {
     readonly kind: "occurrence";
@@ -2495,7 +2495,7 @@ export declare type KayAppAutomationCondition = Extract<KayAppAutomationConditio
     readonly guard?: "session-idle";
 };
 
-export declare type KayAppAutomationConditionInput = {
+export declare type KayAppAutomationConditionInput = KayAppAutomationPluginEventCondition | {
     readonly kind: "time";
     readonly schedule: {
         readonly kind: "every";
@@ -2607,6 +2607,22 @@ export declare interface KayAppAutomationExternalResourceItem {
 export declare type KayAppAutomationFactSource = "run-settled" | "tool-used" | "tool-failed";
 
 export declare type KayAppAutomationMatch = {
+    readonly kind: "plugin-event";
+    readonly event: {
+        readonly id: string;
+        readonly type: string;
+        readonly version: number;
+        readonly uri: string;
+        readonly occurredAt: string;
+        readonly publishedAt: string;
+        readonly source: {
+            readonly layer: "runtime";
+            readonly pluginId: string;
+            readonly poller?: string | undefined;
+            readonly runId?: string | undefined;
+        };
+    };
+} | {
     readonly kind: "time";
     readonly scheduledAtMs: number;
 } | {
@@ -2648,6 +2664,16 @@ export declare type KayAppAutomationMatch = {
     readonly requestedBy?: "user" | "agent" | undefined;
 };
 
+/** Match any listed type; filters use strict equality or scalar-list containment. */
+export declare interface KayAppAutomationPluginEventCondition {
+    readonly kind: "plugin-event";
+    readonly events: readonly string[];
+    readonly where?: readonly {
+        readonly path: string;
+        readonly equals: string | number | boolean;
+    }[];
+}
+
 /**
  * One URI a run produced: every URI its successful `write` and `edit` calls
  * changed, every URI a tool declared it created or updated, and every row
@@ -8260,6 +8286,7 @@ declare const SessionCreator: z.ZodDiscriminatedUnion<[z.ZodObject<{
         cron: "cron";
         occurrence: "occurrence";
         "uri-change": "uri-change";
+        "plugin-event": "plugin-event";
         manual: "manual";
     }>;
 }, z.core.$strict>, z.ZodObject<{
@@ -8351,6 +8378,7 @@ declare const SessionProvenanceRecord: z.ZodObject<{
             cron: "cron";
             occurrence: "occurrence";
             "uri-change": "uri-change";
+            "plugin-event": "plugin-event";
             manual: "manual";
         }>;
     }, z.core.$strict>, z.ZodObject<{
@@ -11201,6 +11229,14 @@ export declare type ToolParametersWire = unknown;
  * declares {@link ToolPermissionHint.quiet} and keeps its honest `kind`.
  */
 export declare interface ToolPermissionHint {
+    /**
+     * Names this exact call for the approval card, from its validated input: a title and optional
+     * labelled facts. Render-only: never matched against a rule, never one-tap approval grounds.
+     * The tool says what its input claims, so the gate shows it as the tool's claim, not as the
+     * daemon's attestation. The host admits only display-safe text; a throw, a blank title or an
+     * unsafe string costs the description and the call is asked about as before.
+     */
+    readonly describePreview?: (input: Record<string, unknown>) => ToolPreviewDescription | undefined;
     readonly kind?: ToolActionKind;
     readonly scheme?: string;
     readonly ruleKey?: string;
@@ -11327,6 +11363,16 @@ export declare interface ToolPermissionHint {
     readonly defaultPermission?: "allow" | "ask" | "never";
 }
 
+/** What {@link ToolPermissionHint.describePreview} answers. */
+declare interface ToolPreviewDescription {
+    readonly title: string;
+    readonly description?: string;
+    readonly fields?: readonly {
+        readonly label: string;
+        readonly value: string;
+    }[];
+}
+
 declare interface ToolReference {
     name: string;
 }

package/dist/kay-app.js

@@ -444,6 +444,7 @@ function isRetryable(result) {
 var KAY_APP_AUTOMATION_CONDITION_KINDS = [
   "time",
   "uri-change",
+  "plugin-event",
   "occurrence",
   "delayed-occurrence"
 ];

package/package.json

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