@yaklabs-ai/plugin-sdk 0.37.1 → 0.38.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.37.1"
+    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.38.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.37.1" },
+  "compatibility": { "sdk": "^0.38.0" },
   "targets": {
     "kay": {
       "agent": {

package/THIRD-PARTY-INVENTORY.json

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

package/dist/disclosure.d.ts

@@ -2399,8 +2399,13 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.37.1";
+declare const KAY_PLUGIN_SDK_VERSION: "0.38.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 

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

@@ -2453,8 +2453,13 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.37.1";
+declare const KAY_PLUGIN_SDK_VERSION: "0.38.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -5652,9 +5657,9 @@ 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/kay-agent.d.ts

@@ -2728,8 +2728,13 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.37.1";
+declare const KAY_PLUGIN_SDK_VERSION: "0.38.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -5087,6 +5092,10 @@ 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">;

package/dist/kay-app.d.ts

@@ -1813,6 +1813,20 @@ declare function IsCodec(value: unknown): value is TCodec;
 /** Returns true if the given value is a TConstructor. */
 declare function IsConstructor(value: unknown): value is TConstructor;
 
+/**
+ * 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;
+
 /** Returns true if the given value is a TCyclic. */
 declare function IsCyclic(value: unknown): value is TCyclic;
 
@@ -2690,8 +2704,13 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.37.1";
+declare const KAY_PLUGIN_SDK_VERSION: "0.38.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -8317,6 +8336,22 @@ export declare interface KayAppWorkflows {
     inspect(localId: string, options?: KayAppWorkflowInspectOptions): Promise<KayAppWorkflowInspection>;
 }
 
+/**
+ * Every event any plugin declares `signal: true`, from every plugin, including plugins installed
+ * later. The payload of each is `PluginSignal` v1, and `related.thread` names its conversation or
+ * object, so the workflow handles a new source without changing.
+ *
+ * Only a plugin Bonsai ships may define one: it asks for the private `workflows.signals` claim,
+ * and any other plugin's activation is refused. `where` filters take envelope paths,
+ * `related.thread|from|to|cc` and `payload.<PluginSignal field>`.
+ */
+export declare interface KayAppWorkflowSignalsTrigger {
+    readonly kind: "plugin-event";
+    readonly signals: true;
+    readonly events?: undefined;
+    readonly where?: KayAppAutomationPluginEventCondition["where"];
+}
+
 export declare type KayAppWorkflowTimeTrigger = Extract<KayAppAutomationConditionInput, {
     readonly kind: "time";
 }>;
@@ -8326,12 +8361,13 @@ export declare type KayAppWorkflowTimeTrigger = Extract<KayAppAutomationConditio
  *
  * An event trigger names full event types (`google.gmail.message.received`) and takes the same
  * filters as a `plugin-event` automation. Each matching event starts one run. Only events this
- * plugin declares are accepted; another plugin's events are refused at `define`.
+ * plugin declares are accepted; another plugin's events are refused at `define`. The one way to
+ * hear other plugins is {@link KayAppWorkflowSignalsTrigger}, for plugins Bonsai ships.
  *
  * A run is not started by an event that one of this workflow's own runs published, as long as the
  * publish names the run: pass `source: { runId: ctx.runId }` (the Poller helper does).
  */
-export declare type KayAppWorkflowTrigger = KayAppWorkflowTimeTrigger | KayAppAutomationPluginEventCondition;
+export declare type KayAppWorkflowTrigger = KayAppWorkflowTimeTrigger | KayAppAutomationPluginEventCondition | KayAppWorkflowSignalsTrigger;
 
 /**
  * Read/arrange access to the live desktop workspace (tabs, panes, the shell chrome). Always
@@ -9711,6 +9747,26 @@ declare function Pick_2<Type extends TSchema, Indexer extends TSchema>(type: Typ
 /** Creates a deferred Pick action. */
 declare function PickDeferred<Type extends TSchema, Indexer extends TSchema>(type: Type, indexer: Indexer, options?: TSchemaOptions): TPickDeferred<Type, Indexer>;
 
+/**
+ * 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 `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";
@@ -9781,6 +9837,86 @@ declare const PluginNamespace: z.ZodString;
 
 declare type PluginNamespace = z.infer<typeof PluginNamespace>;
 
+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];
+
+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>;
+
 declare const PluginSourceClass: z.ZodEnum<{
     bundled: "bundled";
     "org-shared": "org-shared";

package/dist/kay-app.js

@@ -1,3 +1,62 @@
+// 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/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/json.js
 import { z } from "zod";
 var JsonValue = z.lazy(() => z.union([
@@ -655,6 +714,7 @@ function definePoller(app, localId, options) {
     let initialized = 0;
     let skipped = 0;
     let failed = 0;
+    let refused = 0;
     for (const { account, credential } of accounts) {
       const saved = previous.find((entry) => entry.schemeId === account.schemeId && entry.accountId === account.accountId);
       const name = `${account.schemeId}/${account.accountId}`;
@@ -682,15 +742,35 @@ function definePoller(app, localId, options) {
         continue;
       }
       const toPublish = saved === void 0 ? [] : result.events ?? [];
-      await runStep(async () => {
-        for (const event of toPublish) {
-          events.publish(event.localId, {
-            ...event.input,
-            source: { poller: localId, runId }
-          });
-        }
-      });
-      published += toPublish.length;
+      let refusedHere = 0;
+      try {
+        refusedHere = await runStep(async () => {
+          let refusedInStep = 0;
+          for (const event of toPublish) {
+            try {
+              events.publish(event.localId, {
+                ...event.input,
+                source: { poller: localId, runId }
+              });
+            } catch (error) {
+              if (!isPublishRefusal(error))
+                throw error;
+              refusedInStep++;
+            }
+          }
+          return refusedInStep;
+        });
+      } catch (error) {
+        if (!isPublishRefusal(error))
+          throw error;
+        refusedHere = Math.max(refusedHere, refusedCountOf(error));
+      }
+      refused += refusedHere;
+      published += toPublish.length - refusedHere;
+      if (refusedHere > 0) {
+        const names = [...new Set(toPublish.map((event) => event.localId))];
+        details.push(`${name}: ${refusedHere} event(s) refused as invalid and skipped (${names.join(", ")})`);
+      }
       if (saved === void 0)
         initialized++;
       next.push({
@@ -705,13 +785,20 @@ function definePoller(app, localId, options) {
     return {
       state: { accounts: next },
       summary: {
-        headline: plainText(`${published} events; ${initialized} initialized; ${skipped} skipped; ${failed} failed`, 100),
+        headline: plainText(`${published} events; ${initialized} initialized; ${skipped} skipped; ${failed} failed${refused === 0 ? "" : `; ${refused} refused`}`, 100),
         ...details.length === 0 ? {} : { details: plainText(details.join("; "), 600) },
         author: "automation"
       }
     };
   });
 }
+function isPublishRefusal(error) {
+  return error instanceof Error && error.name === PLUGIN_EVENT_REFUSED_ERROR_NAME;
+}
+function refusedCountOf(error) {
+  const count = error.refusedCount;
+  return typeof count === "number" && Number.isSafeInteger(count) && count > 0 ? count : 1;
+}
 
 // packages/plugin-sdk/dist/kay-app/sealing.js
 var KAY_APP_SEALING_MAX_BYTES = 1048576;
@@ -841,6 +928,13 @@ export {
   KayAppCredentialRejectedError,
   KayAppWorkflowFailure,
   MAX_CHOICE_LABELS,
+  PLUGIN_EVENT_REFUSED_ERROR_NAME,
+  PLUGIN_SIGNAL_KINDS,
+  PLUGIN_SIGNAL_LABELS_MAX,
+  PLUGIN_SIGNAL_LABEL_MAX,
+  PLUGIN_SIGNAL_RELATED_KEYS,
+  PLUGIN_SIGNAL_SNIPPET_MAX,
+  PLUGIN_SIGNAL_TITLE_MAX,
   SIGNAL_TIME_MAX_MS,
   STORED_TRANSCRIPT_MESSAGE_FILTER,
   STORED_TRANSCRIPT_MESSAGE_KINDS,
@@ -859,6 +953,7 @@ export {
   definePoller,
   failedRunCause,
   invalidObservation,
+  isCredentialShapedText,
   isRetryable,
   parseLineSelector,
   parseStoredTranscriptKindFilter,

package/package.json

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