@yaklabs-ai/plugin-protocol 0.9.1 → 0.10.0

package/README.md

@@ -11,7 +11,7 @@ flow.
 ```json
 {
   "dependencies": {
-    "@kay/plugin-protocol": "npm:@yaklabs-ai/plugin-protocol@^0.9.1"
+    "@kay/plugin-protocol": "npm:@yaklabs-ai/plugin-protocol@^0.10.0"
   }
 }
 ```

package/THIRD-PARTY-INVENTORY.json

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

package/dist/index.d.ts

@@ -1935,7 +1935,7 @@ export declare const KAY_APP_DATA_SNAPSHOT_MAX_BYTES: number;
 export declare const KAY_EVENT_PUBLISHER_ID: "kay";
 
 /** Released SDK contracts still implemented by the host, alongside its current SDK. */
-export declare const KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS: readonly ["0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.9.0"];
+export declare const KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS: readonly ["0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.9.0", "0.9.1"];
 
 export declare const KAY_PLUGIN_PROTOCOL_PACKAGE_NAME: "@kay/plugin-protocol";
 
@@ -2039,8 +2039,30 @@ export declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * EXISTING apis; the type contract does not change. It still takes the patch
  * slot: nothing a `^0.8.1`/`^0.8.3` plugin already compiles against changes
  * shape, and the fix is which bytes reach npm, not what the contract promises.
+ *
+ * 0.9.0 adds timer_cancelled and requires workflow descriptions and summary
+ * returns. This is an authoring-type break only: the host retains the 0.8
+ * runtime contracts.
+ *
+ * 0.9.1 adds bounded corpus invocation reads (`app.corpus.listResourceInvocations`).
+ * Existing received APIs are unchanged, so this is additive only.
+ *
+ * 0.10.0 removes the `spawn-session` variant from `KayAppAutomationEffectInput`
+ * (and its daemon-facing mirror, `KayAutomationEffectInput`): an agent or
+ * plugin can no longer create a spawn-session automation binding (owner
+ * ruling, 2026-09-28) — durable recurring agent work is a plugin workflow
+ * (`app.workflows.define` + `ctx.runAgent`) or a direct `session/run`. A
+ * binding created before this version, or by daemon-internal code, still
+ * stores and reads the effect fine (`KayAppAutomationEffect` keeps it); only
+ * the create-time input type is narrower. Mostly an authoring-type break —
+ * 0.9.0 and 0.9.1 stay in the runtime-contract retention list below, so a
+ * plugin still running bytecode compiled against either keeps loading and
+ * working — except for the one call this ruling actually closes:
+ * `app.automations.create` with a `spawn-session` effect now throws
+ * explicitly at the call site instead of being accepted, for any plugin
+ * regardless of its declared SDK range.
  */
-export declare const KAY_PLUGIN_SDK_VERSION: "0.9.1";
+export declare const KAY_PLUGIN_SDK_VERSION: "0.10.0";
 
 export declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -3562,6 +3584,9 @@ export declare function parseSemver(value: string): ParsedSemver | undefined;
 /** 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", "filesystem.read", "filesystem.write", "process.spawn", "corpus.read", "signals.read", "workspace.command", "sessions.create", "sessions.update", "models.complete", "jev.use", "automations.write", "automations.run", "workflows.define", "session-events.subscribe", "agents.run", "dynamic-context.register", "app-data.register", "account.assert", "account.update", "agents.permissions", "tool-interception.register", "config.declare-section", "auth.own-service", "auth.shared-identity", "cli.bind", "whiteboard.discover", "whiteboard.read", "whiteboard.create", "whiteboard.update", "whiteboard.remove"];
 
+/** 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"];
 
@@ -4912,6 +4937,29 @@ export declare const PluginEventDefinitionContribution: z.ZodObject<{
 
 export declare type PluginEventDefinitionContribution = z.infer<typeof PluginEventDefinitionContribution>;
 
+/**
+ * How a plugin icon asks to be drawn.
+ *
+ * - `"mark"` (the default): a logo or glyph on a transparent field. The host frames it, inset
+ *   on a white tile, so marks of every shape and color read at one size.
+ * - `"tile"`: a tile icon, artwork that is already a complete tile (its own background, edge to
+ *   edge). The host draws it full-bleed in its tile's shape, with no white field, border, or
+ *   inset.
+ *
+ * The icon declares this itself with `data-icon-shape="tile"` on its root `<svg>` element, so
+ * any plugin (first- or third-party) opts in the same way and a host keeps no list of which
+ * plugins do. It lives in the markup, not the manifest: the manifest is a strict schema, and a
+ * new field there would make every older host reject the plugin.
+ */
+export declare type PluginIconShape = "mark" | "tile";
+
+/**
+ * Read a plugin icon's declared {@link PluginIconShape}. Only the ROOT element's attribute
+ * counts (a nested `<svg>`, a comment, or text never turns a mark into a tile); anything
+ * undeclared or unparseable is a `"mark"`.
+ */
+export declare function pluginIconShape(svg: string): PluginIconShape;
+
 export declare const PluginId: z.ZodString;
 
 export declare type PluginId = z.infer<typeof PluginId>;
@@ -7777,6 +7825,9 @@ export declare const StorageGrantRequest: z.ZodObject<{
 
 export declare type StorageGrantRequest = z.infer<typeof StorageGrantRequest>;
 
+/** Markup that opens an SVG document: the prolog, then the root `<svg` start tag. */
+export declare const SVG_DOCUMENT_START: RegExp;
+
 export declare const TargetEntrypoint: z.ZodObject<{
     module: z.ZodString;
     export: z.ZodOptional<z.ZodString>;

package/dist/index.js

@@ -115,7 +115,7 @@ import { z as z2 } from "zod";
 import { z } from "zod";
 var KAY_PLUGIN_PROTOCOL_VERSION = "kay.plugin.v1";
 var KAY_PLUGIN_PROTOCOL_PACKAGE_NAME = "@kay/plugin-protocol";
-var KAY_PLUGIN_SDK_VERSION = "0.9.1";
+var KAY_PLUGIN_SDK_VERSION = "0.10.0";
 var KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS = [
   "0.8.0",
   "0.8.1",
@@ -123,7 +123,8 @@ var KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS = [
   "0.8.3",
   "0.8.4",
   "0.8.5",
-  "0.9.0"
+  "0.9.0",
+  "0.9.1"
 ];
 var KAY_PLUGIN_TARGET_NAMES = [
   "kay.agent",
@@ -2667,6 +2668,24 @@ var PluginContributionKind = z7.enum([
   "configSection"
 ]);
 
+// packages/plugin-protocol/dist/icon-shape.js
+var SVG_PROLOG = String.raw`^\s*(?:<\?xml[^>]*>\s*)?(?:<!--[\s\S]*?-->\s*)*(?:<!DOCTYPE[^>]*>\s*)?`;
+var SVG_DOCUMENT_START = new RegExp(`${SVG_PROLOG}<svg[\\s>]`, "iu");
+var SVG_ROOT_START_TAG = new RegExp(`${SVG_PROLOG}<svg((?:\\s+[^\\s=>/]+(?:\\s*=\\s*(?:"[^"]*"|'[^']*'|[^\\s"'>]+))?)*)\\s*/?>`, "iu");
+var ATTRIBUTE = /([^\s=>/]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+)))?/gu;
+var PLUGIN_ICON_SHAPE_ATTRIBUTE = "data-icon-shape";
+function pluginIconShape(svg) {
+  const attributes = SVG_ROOT_START_TAG.exec(svg)?.[1];
+  if (attributes === void 0)
+    return "mark";
+  for (const [, name, double, single, bare] of attributes.matchAll(ATTRIBUTE)) {
+    if (name === PLUGIN_ICON_SHAPE_ATTRIBUTE) {
+      return (double ?? single ?? bare) === "tile" ? "tile" : "mark";
+    }
+  }
+  return "mark";
+}
+
 // packages/plugin-protocol/dist/ids.js
 function resolvePluginNamespace(pluginId, namespace) {
   return namespace ?? pluginId;
@@ -3033,10 +3052,20 @@ var KayPluginManifestV1 = z8.strictObject({
    */
   description: NonEmptyString,
   // Display icons resolved relative to the package root and traversal-guarded
-  // by `PackageAssetPath`. `iconDark` is an optional dark-appearance variant;
-  // when absent the host falls back to `icon`. This is a *raster/asset* icon —
-  // distinct from the *symbolic* `UiCommandContribution.icon` (an icon-set
-  // name), see LEXICON `icon`.
+  // by `PackageAssetPath`. This is a *raster/asset* icon — distinct from the
+  // *symbolic* `UiCommandContribution.icon` (an icon-set name), see LEXICON
+  // `icon`. By default the host treats the SVG as a mark and frames it, inset
+  // on a white tile. An SVG whose artwork is already a complete tile (its own
+  // background, edge to edge) says so with `data-icon-shape="tile"` on its
+  // root `<svg>` element, and the host then draws it full-bleed in its tile
+  // shape (LEXICON `tile icon`; `pluginIconShape` in `./icon-shape.ts`). The
+  // signal lives in the asset, not here, so older hosts keep parsing the
+  // manifest.
+  //
+  // `iconDark` is accepted and containment-checked, but no host reads or
+  // renders it today. The supported dark variant lives inside `icon` itself:
+  // an internal `@media (prefers-color-scheme: dark)` rule, which follows the
+  // app theme (docs/directory-plugins.md).
   icon: PackageAssetPath.optional(),
   iconDark: PackageAssetPath.optional(),
   namespace: PluginNamespace.optional(),
@@ -4685,6 +4714,7 @@ export {
   MimeTypeString,
   NonEmptyString,
   PLUGIN_CAPABILITY_SLUGS,
+  PLUGIN_ICON_SHAPE_ATTRIBUTE,
   PLUGIN_NOTIFICATION_RULE_HOST_KEYS,
   PackageAssetPath,
   PluginAgentDefinitionPermissionRule,
@@ -4756,6 +4786,7 @@ export {
   SESSION_HEALTH_CUSTOM_TYPE,
   SESSION_HEALTH_ENTRY_NAME,
   SESSION_HEALTH_EXTENSION_ID,
+  SVG_DOCUMENT_START,
   ScopeAlternative,
   ScopeNeed,
   ScopeRequirement,
@@ -4824,6 +4855,7 @@ export {
   parseKayUiBundleIndexV1,
   parseResolvedPluginContractV1,
   parseSemver,
+  pluginIconShape,
   precedingPersonMessages,
   refineWebSessionScopeConfined,
   resolveAdapterId,

package/package.json

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