@yaklabs-ai/plugin-protocol 0.37.0 → 0.38.0

package/README.md

@@ -11,7 +11,7 @@ flow.
 ```json
 {
   "dependencies": {
-    "@bonsai/plugin-protocol": "npm:@yaklabs-ai/plugin-protocol@^0.37.0"
+    "@bonsai/plugin-protocol": "npm:@yaklabs-ai/plugin-protocol@^0.38.0"
   }
 }
 ```

package/THIRD-PARTY-INVENTORY.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@yaklabs-ai/plugin-protocol",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "target": "npm",
   "firstPartyLicense": "MIT",
   "bundled": [],

package/dist/index.d.ts

@@ -2528,25 +2528,25 @@ declare const canonicalContributionSchemas: {
     }, z.core.$strict>;
     McpServerUrl: z.ZodString;
     McpServerAuthMode: z.ZodEnum<{
+        none: "none";
         oauth: "oauth";
         "api-key": "api-key";
-        none: "none";
     }>;
     McpServerContribution: z.ZodObject<{
         url: z.ZodString;
         auth: z.ZodOptional<z.ZodEnum<{
+            none: "none";
             oauth: "oauth";
             "api-key": "api-key";
-            none: "none";
         }>>;
         authService: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
     McpServerContributions: z.ZodRecord<z.ZodString, z.ZodObject<{
         url: z.ZodString;
         auth: z.ZodOptional<z.ZodEnum<{
+            none: "none";
             oauth: "oauth";
             "api-key": "api-key";
-            none: "none";
         }>>;
         authService: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
@@ -2567,6 +2567,7 @@ declare const canonicalContributionSchemas: {
         uriScheme: z.ZodString;
         relatedKeys: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
         payloadSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>>;
+        signal: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>;
     PluginNotificationRuleContribution: z.ZodObject<{
         localId: z.ZodString;
@@ -3434,6 +3435,20 @@ export declare function isCanonicalArtifactOutputUri(uri: string): boolean;
 /** Whether the report permits the plugin to load. */
 export declare function isCompatible(report: KayPluginCompatibilityReport): boolean;
 
+/**
+ * The recognized credential VALUE formats: one detector for the runtime wire's raw-credential
+ * tripwire (`@bonsai/agent-runtime-protocol`'s `hasRawCredentialField`) and for a plugin that
+ * must keep such text out of what it publishes, so the two cannot disagree on what a hit is.
+ * Lives here, below both, because a plugin cannot import the runtime protocol.
+ */
+/**
+ * Whether `value` is a string in a recognized credential format (a whole `sk-...`, `ghp_...` or
+ * `xoxb-...` token, a JWT, an Authorization header value, or anything holding a PEM private key
+ * block). A publisher that copies outside text into an event drops or replaces such a string:
+ * the daemon refuses an event that carries one.
+ */
+export declare function isCredentialShapedText(value: unknown): boolean;
+
 /**
  * Whether a refusal `code` came from the compatibility check: the plugin was written for another
  * SDK or protocol, as opposed to being malformed.
@@ -4152,8 +4167,17 @@ export declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * `contributes` names the `rule`, the `body` that fills the preview, either a `contextOnly` app in
  * the plugin or a body the host ships, and the `address` it is about. Additive. A plugin that
  * declares a preview declares ^0.37.0.
+ *
+ * 0.37.1 adds the required, ungated `featureFlags.value(key)` reader to both backend targets.
+ * Unknown keys return false; the host supplies evaluated values before activation and updates them.
+ * Additive: existing plugins keep loading. A consumer declares ^0.37.1.
+ *
+ * 0.38.0 adds signals (epic #15668). An event definition may declare `signal: true`, and its payload
+ * is then the shared `PluginSignal` v1 with a `related.thread`; a workflow of a plugin the release
+ * carries may start on every plugin's signals with `{ kind: "plugin-event", signals: true }` (the
+ * private `workflows.signals` claim). Additive: a plugin that declares a signal declares ^0.38.0.
  */
-export declare const KAY_PLUGIN_SDK_VERSION: "0.37.0";
+export declare const KAY_PLUGIN_SDK_VERSION: "0.38.0";
 
 export declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -4770,6 +4794,7 @@ export declare const KayAppTargetManifest: z.ZodObject<{
             uriScheme: z.ZodString;
             relatedKeys: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
             payloadSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>>;
+            signal: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>>;
         notificationRules: z.ZodOptional<z.ZodArray<z.ZodObject<{
             localId: z.ZodString;
@@ -4809,9 +4834,9 @@ export declare const KayAppTargetManifest: z.ZodObject<{
         mcpServers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
             url: z.ZodString;
             auth: z.ZodOptional<z.ZodEnum<{
+                none: "none";
                 oauth: "oauth";
                 "api-key": "api-key";
-                none: "none";
             }>>;
             authService: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>>;
@@ -5541,6 +5566,7 @@ export declare const KayPluginManifestV1: z.ZodObject<{
                         uriScheme: z.ZodString;
                         relatedKeys: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
                         payloadSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>>;
+                        signal: z.ZodOptional<z.ZodBoolean>;
                     }, z.core.$strict>>>;
                     notificationRules: z.ZodOptional<z.ZodArray<z.ZodObject<{
                         localId: z.ZodString;
@@ -5580,9 +5606,9 @@ export declare const KayPluginManifestV1: z.ZodObject<{
                     mcpServers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
                         url: z.ZodString;
                         auth: z.ZodOptional<z.ZodEnum<{
+                            none: "none";
                             oauth: "oauth";
                             "api-key": "api-key";
-                            none: "none";
                         }>>;
                         authService: z.ZodOptional<z.ZodString>;
                     }, z.core.$strict>>>;
@@ -6992,9 +7018,9 @@ export declare const MCP_SIGN_IN_SCHEME_KIND: {
 };
 
 export declare const McpServerAuthMode: z.ZodEnum<{
+    none: "none";
     oauth: "oauth";
     "api-key": "api-key";
-    none: "none";
 }>;
 
 export declare type McpServerAuthMode = z.infer<typeof McpServerAuthMode>;
@@ -7002,9 +7028,9 @@ export declare type McpServerAuthMode = z.infer<typeof McpServerAuthMode>;
 export declare const McpServerContribution: z.ZodObject<{
     url: z.ZodString;
     auth: z.ZodOptional<z.ZodEnum<{
+        none: "none";
         oauth: "oauth";
         "api-key": "api-key";
-        none: "none";
     }>>;
     authService: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
@@ -7014,9 +7040,9 @@ export declare type McpServerContribution = z.infer<typeof McpServerContribution
 export declare const McpServerContributions: z.ZodRecord<z.ZodString, z.ZodObject<{
     url: z.ZodString;
     auth: z.ZodOptional<z.ZodEnum<{
+        none: "none";
         oauth: "oauth";
         "api-key": "api-key";
-        none: "none";
     }>>;
     authService: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>>;
@@ -7145,7 +7171,7 @@ export declare function parseSemver(value: string): ParsedSemver | undefined;
 export declare function parseWhere(source: string, keyTypes?: WhereKeyTypes): WhereParseResult;
 
 /** Every capability slug {@link PluginCapabilityClaimV1} can express, for exhaustive table checks. */
-export declare const PLUGIN_CAPABILITY_SLUGS: readonly ["sessions.run", "network.connect", "web-session.request", "web-session.download", "process.spawn", "sessions.read", "signals.read", "memory.read", "memory.write", "skills.read", "skills.write", "skills.share", "plugins.set-enabled", "sessions.annotate", "sessions.compact", "soul.write", "tools.describe", "workspace.command", "sessions.create", "sessions.update", "models.complete", "systemOne.use", "automations.write", "automations.run", "workflows.define", "session-events.subscribe", "agents.run", "dynamic-context.register", "app-data.register", "knowledge-source.register", "artifacts.read", "account.assert", "account.update", "agents.permissions", "tool-interception.register", "interaction.surface", "config.declare-section", "auth.own-service", "auth.shared-identity", "cli.bind", "mcp.host-server", "prompt.resident", "skills.declared-source", "whiteboard.discover", "whiteboard.read", "whiteboard.create", "whiteboard.update", "whiteboard.remove", "model-selection.register", "system-prompt.register"];
+export declare const PLUGIN_CAPABILITY_SLUGS: readonly ["sessions.run", "network.connect", "web-session.request", "web-session.download", "process.spawn", "sessions.read", "signals.read", "memory.read", "memory.write", "skills.read", "skills.write", "skills.share", "plugins.set-enabled", "sessions.annotate", "sessions.compact", "soul.write", "tools.describe", "workspace.command", "sessions.create", "sessions.update", "models.complete", "systemOne.use", "automations.write", "automations.run", "workflows.define", "workflows.signals", "session-events.subscribe", "agents.run", "dynamic-context.register", "app-data.register", "knowledge-source.register", "artifacts.read", "account.assert", "account.update", "agents.permissions", "tool-interception.register", "interaction.surface", "config.declare-section", "auth.own-service", "auth.shared-identity", "cli.bind", "mcp.host-server", "prompt.resident", "skills.declared-source", "whiteboard.discover", "whiteboard.read", "whiteboard.create", "whiteboard.update", "whiteboard.remove", "model-selection.register", "system-prompt.register"];
 
 /** Diagnostic messages carry plugin-controlled text (parse errors, module errors); bound it so a
  *  hostile or accidental multi-megabyte error can never blow up a log line or a render surface. */
@@ -7153,12 +7179,32 @@ export declare const PLUGIN_DIAGNOSTIC_MESSAGE_CAP = 300;
 
 export declare const PLUGIN_EVENT_ID_MAX_BYTES = 1024;
 
+/**
+ * The `name` of the error a host throws when it refuses a publish because the event is invalid.
+ * A publisher skips such an event; any other publish failure may be transient.
+ */
+export declare const PLUGIN_EVENT_REFUSED_ERROR_NAME = "PluginEventRefusedError";
+
 /** The root `<svg>` attribute a tile icon declares itself with. */
 export declare const PLUGIN_ICON_SHAPE_ATTRIBUTE = "data-icon-shape";
 
 /** Rule-body keys the host stamps, so a manifest's `rule` may not carry them. */
 export declare const PLUGIN_NOTIFICATION_RULE_HOST_KEYS: readonly ["id", "match", "sender"];
 
+/** The `kind` values of `PluginSignal` v1. `status` is system state that clears itself. */
+export declare const PLUGIN_SIGNAL_KINDS: readonly ["message", "request", "mention", "invite", "status"];
+
+export declare const PLUGIN_SIGNAL_LABEL_MAX = 64;
+
+export declare const PLUGIN_SIGNAL_LABELS_MAX = 20;
+
+/** The `related` keys a signal may use; `thread` is required on every signal publish. */
+export declare const PLUGIN_SIGNAL_RELATED_KEYS: readonly ["thread", "from", "to", "cc"];
+
+export declare const PLUGIN_SIGNAL_SNIPPET_MAX = 500;
+
+export declare const PLUGIN_SIGNAL_TITLE_MAX = 300;
+
 export declare const PluginAgentDefinitionPermissionRule: z.ZodObject<{
     effect: z.ZodEnum<{
         allow: "allow";
@@ -7747,6 +7793,10 @@ export declare const PluginCapabilityClaimInputV1: z.ZodCustom<{
     target: "kay.app";
     slug: "workflows.define";
     envelope: Record<string, never>;
+} | {
+    target: "kay.app";
+    slug: "workflows.signals";
+    envelope: Record<string, never>;
 } | {
     target: "kay.app";
     slug: "session-events.subscribe";
@@ -7992,6 +8042,10 @@ export declare const PluginCapabilityClaimInputV1: z.ZodCustom<{
     target: "kay.app";
     slug: "workflows.define";
     envelope: Record<string, never>;
+} | {
+    target: "kay.app";
+    slug: "workflows.signals";
+    envelope: Record<string, never>;
 } | {
     target: "kay.app";
     slug: "session-events.subscribe";
@@ -8233,6 +8287,10 @@ export declare const PluginCapabilityClaimV1: z.ZodDiscriminatedUnion<[z.ZodObje
     target: z.ZodLiteral<"kay.app">;
     slug: z.ZodLiteral<"workflows.define">;
     envelope: z.ZodObject<{}, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    target: z.ZodLiteral<"kay.app">;
+    slug: z.ZodLiteral<"workflows.signals">;
+    envelope: z.ZodObject<{}, z.core.$strict>;
 }, z.core.$strict>, z.ZodObject<{
     target: z.ZodLiteral<"kay.app">;
     slug: z.ZodLiteral<"session-events.subscribe">;
@@ -8517,6 +8575,10 @@ export declare const PluginCapabilityDecisionV1: z.ZodDiscriminatedUnion<[z.ZodO
         target: z.ZodLiteral<"kay.app">;
         slug: z.ZodLiteral<"workflows.define">;
         envelope: z.ZodObject<{}, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"kay.app">;
+        slug: z.ZodLiteral<"workflows.signals">;
+        envelope: z.ZodObject<{}, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         target: z.ZodLiteral<"kay.app">;
         slug: z.ZodLiteral<"session-events.subscribe">;
@@ -8800,6 +8862,10 @@ export declare const PluginCapabilityDecisionV1: z.ZodDiscriminatedUnion<[z.ZodO
             target: z.ZodLiteral<"kay.app">;
             slug: z.ZodLiteral<"workflows.define">;
             envelope: z.ZodObject<{}, z.core.$strict>;
+        }, z.core.$strict>, z.ZodObject<{
+            target: z.ZodLiteral<"kay.app">;
+            slug: z.ZodLiteral<"workflows.signals">;
+            envelope: z.ZodObject<{}, z.core.$strict>;
         }, z.core.$strict>, z.ZodObject<{
             target: z.ZodLiteral<"kay.app">;
             slug: z.ZodLiteral<"session-events.subscribe">;
@@ -9117,6 +9183,10 @@ export declare const PluginCapabilityRefusalV1: z.ZodObject<{
         target: z.ZodLiteral<"kay.app">;
         slug: z.ZodLiteral<"workflows.define">;
         envelope: z.ZodObject<{}, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"kay.app">;
+        slug: z.ZodLiteral<"workflows.signals">;
+        envelope: z.ZodObject<{}, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         target: z.ZodLiteral<"kay.app">;
         slug: z.ZodLiteral<"session-events.subscribe">;
@@ -9399,6 +9469,7 @@ export declare const PluginEventDefinitionContribution: z.ZodObject<{
     uriScheme: z.ZodString;
     relatedKeys: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
     payloadSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>>;
+    signal: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 
 export declare type PluginEventDefinitionContribution = z.infer<typeof PluginEventDefinitionContribution>;
@@ -10207,6 +10278,92 @@ export declare const PluginProvisioningRequirement: z.ZodObject<{
 
 export declare type PluginProvisioningRequirement = z.infer<typeof PluginProvisioningRequirement>;
 
+export declare const PluginSignal: z.ZodObject<{
+    kind: z.ZodEnum<{
+        message: "message";
+        status: "status";
+        request: "request";
+        mention: "mention";
+        invite: "invite";
+    }>;
+    direction: z.ZodOptional<z.ZodEnum<{
+        out: "out";
+        in: "in";
+    }>>;
+    title: z.ZodOptional<z.ZodString>;
+    snippet: z.ZodOptional<z.ZodString>;
+    actor: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        uri: z.ZodString;
+    }, z.core.$strict>>;
+    addressed: z.ZodOptional<z.ZodEnum<{
+        mention: "mention";
+        cc: "cc";
+        direct: "direct";
+        group: "group";
+        none: "none";
+    }>>;
+    labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    dueAt: z.ZodOptional<z.ZodISODateTime>;
+    state: z.ZodOptional<z.ZodEnum<{
+        open: "open";
+        resolved: "resolved";
+    }>>;
+}, z.core.$strict>;
+
+export declare type PluginSignal = z.infer<typeof PluginSignal>;
+
+export declare type PluginSignalKind = (typeof PLUGIN_SIGNAL_KINDS)[number];
+
+/**
+ * `PluginSignal` v1 as JSON Schema, for the hosts that check a `payload.*` filter path against a
+ * declaration. A signal definition declares no `payloadSchema`; this stands in for it.
+ */
+export declare function pluginSignalPayloadJsonSchema(): Record<string, unknown>;
+
+export declare const PluginSignalPublish: z.ZodObject<{
+    payload: z.ZodObject<{
+        kind: z.ZodEnum<{
+            message: "message";
+            status: "status";
+            request: "request";
+            mention: "mention";
+            invite: "invite";
+        }>;
+        direction: z.ZodOptional<z.ZodEnum<{
+            out: "out";
+            in: "in";
+        }>>;
+        title: z.ZodOptional<z.ZodString>;
+        snippet: z.ZodOptional<z.ZodString>;
+        actor: z.ZodOptional<z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
+            uri: z.ZodString;
+        }, z.core.$strict>>;
+        addressed: z.ZodOptional<z.ZodEnum<{
+            mention: "mention";
+            cc: "cc";
+            direct: "direct";
+            group: "group";
+            none: "none";
+        }>>;
+        labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        dueAt: z.ZodOptional<z.ZodISODateTime>;
+        state: z.ZodOptional<z.ZodEnum<{
+            open: "open";
+            resolved: "resolved";
+        }>>;
+    }, z.core.$strict>;
+    related: z.ZodObject<{
+        thread: z.ZodString;
+        from: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+        to: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+        cc: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    }, z.core.$strict>;
+}, z.core.$strip>;
+
+export declare type PluginSignalPublish = z.infer<typeof PluginSignalPublish>;
+
 export declare const PluginSkillSourceDeclaration: z.ZodDiscriminatedUnion<[z.ZodObject<{
     channel: z.ZodLiteral<"installer">;
     localId: z.ZodString;
@@ -10950,9 +11107,9 @@ export declare const ResolvedKayAppMcpServer: z.ZodObject<{
     pluginId: z.ZodString;
     url: z.ZodString;
     auth: z.ZodEnum<{
+        none: "none";
         oauth: "oauth";
         "api-key": "api-key";
-        none: "none";
     }>;
     authServiceId: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
@@ -12243,9 +12400,9 @@ export declare const ResolvedPluginContractV1: z.ZodObject<{
         pluginId: z.ZodString;
         url: z.ZodString;
         auth: z.ZodEnum<{
+            none: "none";
             oauth: "oauth";
             "api-key": "api-key";
-            none: "none";
         }>;
         authServiceId: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>>;

package/dist/index.js

@@ -254,7 +254,7 @@ var JsonSchema = z4.record(z4.string(), JsonValue);
 var KAY_PLUGIN_MANIFEST_SIZE_CAP_BYTES = 1024 * 1024;
 var KAY_PLUGIN_PROTOCOL_VERSION = "kay.plugin.v1";
 var KAY_PLUGIN_PROTOCOL_PACKAGE_NAME = "@bonsai/plugin-protocol";
-var KAY_PLUGIN_SDK_VERSION = "0.37.0";
+var KAY_PLUGIN_SDK_VERSION = "0.38.0";
 var KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS = [
   "0.26.3",
   "0.27.1",
@@ -266,7 +266,8 @@ var KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS = [
   "0.33.0",
   "0.34.0",
   "0.35.0",
-  "0.36.0"
+  "0.36.0",
+  "0.37.1"
 ];
 var KAY_PLUGIN_TARGET_NAMES = [
   "kay.agent",
@@ -1755,6 +1756,7 @@ var PLUGIN_CAPABILITY_SLUGS = [
   "automations.write",
   "automations.run",
   "workflows.define",
+  "workflows.signals",
   "session-events.subscribe",
   "agents.run",
   "dynamic-context.register",
@@ -1786,7 +1788,8 @@ var PRIVATE_PLUGIN_CAPABILITY_SLUGS = [
   "soul.write",
   "skills.share",
   "plugins.set-enabled",
-  "system-prompt.register"
+  "system-prompt.register",
+  "workflows.signals"
 ];
 function isPrivateCapabilityClaim(claim) {
   return PRIVATE_PLUGIN_CAPABILITY_SLUGS.includes(claim.slug);
@@ -2011,6 +2014,14 @@ function createAuthoritySchemas(canonical) {
       slug: z10.literal("workflows.define"),
       envelope: z10.strictObject({})
     }),
+    z10.strictObject({
+      // Start a declared workflow on every plugin's signal events (`signals: true`), which carry
+      // other plugins' data. Private (PRIVATE_PLUGIN_CAPABILITY_SLUGS): only a plugin the release
+      // carries may hold it, so a third-party plugin cannot read every source's signals.
+      target: z10.literal("kay.app"),
+      slug: z10.literal("workflows.signals"),
+      envelope: z10.strictObject({})
+    }),
     z10.strictObject({
       target: z10.literal("kay.app"),
       slug: z10.literal("session-events.subscribe"),
@@ -2242,6 +2253,7 @@ function sameClaim(a, b) {
     case "automations.write":
     case "automations.run":
     case "workflows.define":
+    case "workflows.signals":
     case "session-events.subscribe":
     case "agents.run":
     case "account.assert":
@@ -2326,6 +2338,7 @@ function envelopePairs(a, b) {
     case "automations.write":
     case "automations.run":
     case "workflows.define":
+    case "workflows.signals":
     case "session-events.subscribe":
     case "agents.run":
     case "account.assert":
@@ -2777,6 +2790,13 @@ import { z as z12 } from "zod";
 var plugin_events_exports = {};
 __export(plugin_events_exports, {
   PLUGIN_EVENT_ID_MAX_BYTES: () => PLUGIN_EVENT_ID_MAX_BYTES,
+  PLUGIN_EVENT_REFUSED_ERROR_NAME: () => PLUGIN_EVENT_REFUSED_ERROR_NAME,
+  PLUGIN_SIGNAL_KINDS: () => PLUGIN_SIGNAL_KINDS,
+  PLUGIN_SIGNAL_LABELS_MAX: () => PLUGIN_SIGNAL_LABELS_MAX,
+  PLUGIN_SIGNAL_LABEL_MAX: () => PLUGIN_SIGNAL_LABEL_MAX,
+  PLUGIN_SIGNAL_RELATED_KEYS: () => PLUGIN_SIGNAL_RELATED_KEYS,
+  PLUGIN_SIGNAL_SNIPPET_MAX: () => PLUGIN_SIGNAL_SNIPPET_MAX,
+  PLUGIN_SIGNAL_TITLE_MAX: () => PLUGIN_SIGNAL_TITLE_MAX,
   PluginEventEnvelope: () => PluginEventEnvelope,
   PluginEventId: () => PluginEventId,
   PluginEventLocalId: () => PluginEventLocalId,
@@ -2786,9 +2806,34 @@ __export(plugin_events_exports, {
   PluginEventSource: () => PluginEventSource,
   PluginEventTimestamp: () => PluginEventTimestamp,
   PluginEventUri: () => PluginEventUri,
-  canonicalPluginEventSchemas: () => canonicalPluginEventSchemas
+  PluginSignal: () => PluginSignal,
+  PluginSignalPublish: () => PluginSignalPublish,
+  canonicalPluginEventSchemas: () => canonicalPluginEventSchemas,
+  pluginSignalPayloadJsonSchema: () => pluginSignalPayloadJsonSchema
 });
 import { z as z11 } from "zod";
+
+// packages/plugin-protocol/dist/plugin-signal-limits.js
+var PLUGIN_EVENT_REFUSED_ERROR_NAME = "PluginEventRefusedError";
+var PLUGIN_SIGNAL_KINDS = [
+  "message",
+  "request",
+  "mention",
+  "invite",
+  "status"
+];
+var PLUGIN_SIGNAL_TITLE_MAX = 300;
+var PLUGIN_SIGNAL_SNIPPET_MAX = 500;
+var PLUGIN_SIGNAL_LABELS_MAX = 20;
+var PLUGIN_SIGNAL_LABEL_MAX = 64;
+var PLUGIN_SIGNAL_RELATED_KEYS = [
+  "thread",
+  "from",
+  "to",
+  "cc"
+];
+
+// packages/plugin-protocol/dist/plugin-events.js
 var PLUGIN_EVENT_ID_MAX_BYTES = 1024;
 function createPluginEventsSchemas(canonical) {
   const { GlobalContributionId: GlobalContributionId2, NonEmptyString: NonEmptyString3 } = canonical ? canonicalCommonSchemas : common_exports;
@@ -2840,7 +2885,39 @@ function createPluginEventsSchemas(canonical) {
     source: PluginEventSource2,
     payload: JsonValue.optional()
   });
+  const PluginSignal2 = z11.strictObject({
+    kind: z11.enum(PLUGIN_SIGNAL_KINDS),
+    direction: z11.enum(["in", "out"]).optional(),
+    title: z11.string().max(PLUGIN_SIGNAL_TITLE_MAX).optional(),
+    snippet: z11.string().max(PLUGIN_SIGNAL_SNIPPET_MAX).optional(),
+    actor: z11.strictObject({
+      name: z11.string().max(PLUGIN_SIGNAL_TITLE_MAX).optional(),
+      uri: PluginEventUri2
+    }).optional(),
+    addressed: z11.enum(["direct", "cc", "mention", "group", "none"]).optional(),
+    labels: z11.array(z11.string().min(1).max(PLUGIN_SIGNAL_LABEL_MAX)).max(PLUGIN_SIGNAL_LABELS_MAX).optional(),
+    dueAt: PluginEventTimestamp2.optional(),
+    state: z11.enum(["open", "resolved"]).optional()
+  }).refine((signal) => signal.state === void 0 || signal.kind === "status", {
+    message: "state is only for a status signal",
+    path: ["state"]
+  });
+  const PluginSignalRelatedValue = z11.union([
+    PluginEventUri2,
+    z11.array(PluginEventUri2)
+  ]);
+  const PluginSignalPublish2 = z11.object({
+    payload: PluginSignal2,
+    related: z11.strictObject({
+      thread: PluginEventUri2,
+      from: PluginSignalRelatedValue.optional(),
+      to: PluginSignalRelatedValue.optional(),
+      cc: PluginSignalRelatedValue.optional()
+    })
+  });
   return {
+    PluginSignal: PluginSignal2,
+    PluginSignalPublish: PluginSignalPublish2,
     PluginEventLocalId: PluginEventLocalId2,
     PluginEventUri: PluginEventUri2,
     PluginEventTimestamp: PluginEventTimestamp2,
@@ -2852,8 +2929,14 @@ function createPluginEventsSchemas(canonical) {
     PluginEventEnvelope: PluginEventEnvelope2
   };
 }
-var { PluginEventLocalId, PluginEventUri, PluginEventTimestamp, PluginEventRelated, PluginEventPublishSource, PluginEventSource, PluginEventId, PluginEventPublishInput, PluginEventEnvelope } = createPluginEventsSchemas(false);
+var { PluginSignal, PluginSignalPublish, PluginEventLocalId, PluginEventUri, PluginEventTimestamp, PluginEventRelated, PluginEventPublishSource, PluginEventSource, PluginEventId, PluginEventPublishInput, PluginEventEnvelope } = createPluginEventsSchemas(false);
 var canonicalPluginEventSchemas = createPluginEventsSchemas(true);
+function pluginSignalPayloadJsonSchema() {
+  return z11.toJSONSchema(PluginSignal, {
+    io: "input",
+    unrepresentable: "any"
+  });
+}
 
 // packages/plugin-protocol/dist/where-expression.js
 var TOKEN = /\s*(?:(\|\||&&|==|!=|!|\(|\))|'([^']*)'|"([^"]*)"|([A-Za-z][A-Za-z0-9]*(?:\.[A-Za-z][A-Za-z0-9]*)*))/y;
@@ -3588,7 +3671,34 @@ function createContributionsSchemas(canonical) {
     version: canonical ? EventDefinitionVersion : EventDefinitionVersion.default(1),
     uriScheme: UriScheme2,
     relatedKeys: z12.array(NonEmptyString3).readonly().optional(),
-    payloadSchema: JsonSchema.optional()
+    payloadSchema: JsonSchema.optional(),
+    /**
+     * This event is a signal: its payload is the shared `PluginSignal` v1 and every publish
+     * names `related.thread`. Bundled workflows that subscribe with `signals: true` receive it
+     * without naming it. The payload schema is the shared one, so `payloadSchema` is omitted,
+     * and `relatedKeys` holds `thread` plus any of `from`, `to`, `cc`. Turning it on changes
+     * the payload, so bump `version` with it.
+     */
+    signal: z12.boolean().optional()
+  }).superRefine((definition, context) => {
+    if (definition.signal !== true)
+      return;
+    if (definition.payloadSchema !== void 0) {
+      context.addIssue({
+        code: "custom",
+        path: ["payloadSchema"],
+        message: "A signal event uses the shared PluginSignal v1 payload; omit payloadSchema."
+      });
+    }
+    const allowed = PLUGIN_SIGNAL_RELATED_KEYS;
+    const keys = definition.relatedKeys ?? [];
+    if (!keys.includes("thread") || keys.some((key) => !allowed.includes(key))) {
+      context.addIssue({
+        code: "custom",
+        path: ["relatedKeys"],
+        message: `A signal event declares relatedKeys 'thread' plus any of ${allowed.filter((key) => key !== "thread").map((key) => `'${key}'`).join(", ")}.`
+      });
+    }
   });
   const PluginNotificationRuleContribution2 = z12.strictObject({
     localId: LocalContributionId2,
@@ -4879,6 +4989,27 @@ function createManifestSchemas(canonical) {
         });
       }
     }
+    const ownSchemes = new Set([
+      ...manifest.targets?.kay?.agent?.contributes?.uriModules ?? [],
+      ...manifest.targets?.kay?.app?.contributes?.uriModules ?? []
+    ].flatMap((module) => module.schemes));
+    for (const [index, definition] of (manifest.targets?.kay?.app?.contributes?.eventDefinitions ?? []).entries()) {
+      if (definition.signal !== true || ownSchemes.has(definition.uriScheme))
+        continue;
+      ctx.addIssue({
+        code: "custom",
+        path: [
+          "targets",
+          "kay",
+          "app",
+          "contributes",
+          "eventDefinitions",
+          index,
+          "uriScheme"
+        ],
+        message: `signal event ${definition.localId} must use a URI scheme one of this plugin's own URI modules serves; '${definition.uriScheme}' is not among them`
+      });
+    }
     reportDuplicateLocalIds(ctx, ["targets", "kay", "app", "contributes", "workflows"], manifest.targets?.kay?.app?.contributes?.workflows, "workflow");
     for (const [index, workflow] of (manifest.targets?.kay?.app?.contributes?.workflows ?? []).entries()) {
       const path = [
@@ -7046,6 +7177,45 @@ var ArtifactOutputChange = z20.union([
   z20.strictObject({ sessionId: Segment })
 ]);
 
+// packages/plugin-protocol/dist/credential-text.js
+var CREDENTIAL_VALUE_PATTERNS = [
+  // Anthropic / OpenAI-style secret keys (`sk-`, `sk-ant-`, `sk-proj-`).
+  /^sk-[A-Za-z0-9_-]{16,}$/u,
+  // GitHub classic, fine-grained, app, and OAuth tokens.
+  /^gh[pousr]_[A-Za-z0-9]{16,}$/u,
+  /^github_pat_[A-Za-z0-9_]{20,}$/u,
+  // GitLab personal access tokens.
+  /^glpat-[A-Za-z0-9_-]{16,}$/u,
+  // Slack bot/user/app tokens.
+  /^xox[baprse]-[A-Za-z0-9-]{10,}$/u,
+  // AWS access key ids, long-lived and STS-issued.
+  /^(?:AKIA|ASIA)[0-9A-Z]{16}$/u,
+  // Google API keys, both published shapes.
+  /^AIza[0-9A-Za-z_-]{35}$/u,
+  /^AQ\.[A-Za-z0-9_-]{20,}$/u,
+  // npm automation tokens.
+  /^npm_[A-Za-z0-9]{30,}$/u,
+  // SendGrid API keys (SG.<key id>.<secret>).
+  /^SG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}$/u,
+  // HashiCorp Vault service/batch/recovery tokens.
+  /^hv[sbr]\.[A-Za-z0-9_-]{20,}$/u,
+  // Shopify access tokens.
+  /^shp(?:at|ss|ca|pa)_[a-fA-F0-9]{32}$/u,
+  // Stripe live/test secret and restricted keys.
+  /^(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{16,}$/u,
+  // JSON Web Tokens - header.payload.signature, header always starts `eyJ`.
+  /^eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]*$/u,
+  // A whole Authorization header value carried as data.
+  /^(?:Bearer|Basic) [A-Za-z0-9+/._~-]{16,}={0,2}$/iu,
+  // PEM private key blocks, anywhere in the string.
+  /-----BEGIN (?:[A-Z]+ )?PRIVATE KEY-----/u
+];
+function isCredentialShapedText(value) {
+  if (typeof value !== "string" || value.length === 0)
+    return false;
+  return CREDENTIAL_VALUE_PATTERNS.some((pattern) => pattern.test(value));
+}
+
 // packages/plugin-protocol/dist/ui-module-bundle.js
 import { z as z21 } from "zod";
 var KAY_UI_MODULE_BUNDLE_PROTOCOL = "kay.ui.module-bundle.v1";
@@ -7216,8 +7386,15 @@ export {
   PLUGIN_CAPABILITY_SLUGS,
   PLUGIN_DIAGNOSTIC_MESSAGE_CAP,
   PLUGIN_EVENT_ID_MAX_BYTES,
+  PLUGIN_EVENT_REFUSED_ERROR_NAME,
   PLUGIN_ICON_SHAPE_ATTRIBUTE,
   PLUGIN_NOTIFICATION_RULE_HOST_KEYS,
+  PLUGIN_SIGNAL_KINDS,
+  PLUGIN_SIGNAL_LABELS_MAX,
+  PLUGIN_SIGNAL_LABEL_MAX,
+  PLUGIN_SIGNAL_RELATED_KEYS,
+  PLUGIN_SIGNAL_SNIPPET_MAX,
+  PLUGIN_SIGNAL_TITLE_MAX,
   PRIVATE_PLUGIN_CAPABILITY_SLUGS,
   PackageAssetPath,
   PluginAgentDefinitionPermissionRule,
@@ -7253,6 +7430,8 @@ export {
   PluginPermissionManifest,
   PluginProvisioningProbe,
   PluginProvisioningRequirement,
+  PluginSignal,
+  PluginSignalPublish,
   PluginSkillSourceDeclaration,
   PluginSourceClass,
   PluginStorageManifest,
@@ -7381,6 +7560,7 @@ export {
   hostWithinDomain,
   isCanonicalArtifactOutputUri,
   isCompatible,
+  isCredentialShapedText,
   isKayPluginCompatibilityRefusal,
   isPrivateCapabilityClaim,
   isQualifiedAuthSchemeRef,
@@ -7404,6 +7584,7 @@ export {
   parseSemver,
   parseWhere,
   pluginIconShape,
+  pluginSignalPayloadJsonSchema,
   precedingPersonMessages,
   readKayPluginDeclaredCompatibility,
   refineWebSessionScopeConfined,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaklabs-ai/plugin-protocol",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "description": "The Kay plugin manifest schema (`kay.plugin.v1`) — parse and validate a kay-plugin.json.",
   "author": "YakLabs",
   "type": "module",