@yaklabs-ai/plugin-sdk 0.45.0 → 0.46.0

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

@@ -2485,9 +2485,19 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 0.44.0 adds `words.kinds` to a reference presentation (#15905): an ordered list of address patterns
  * and the kind each one names. Additive: a plugin that lists them declares ^0.44.0.
  *
- * 0.45.0 adds declared plugin cards and app.implementCard for their read/submit endpoints.
+ * 0.45.0 adds declared plugin cards and app.implementCard for their read/submit endpoints. It also
+ * lets a plugin declare what the window hardcoded about it (#15906). A reference presentation gains
+ * `accountLinks`, how a page opens under the account an address means, and a `local-app` open, for
+ * an item an app on this machine shows; a plugin the person installed can't declare that open. A
+ * `webSession` gains `signInFirst`. A URI module defines `lookupWebLink` and sets `looksUpWebLinks`
+ * to find a page when someone opens the address, and a preview field marks which `part` of a message
+ * it is. A claim's `brandIcon` is a file path and no longer inline markup, which only this repo's
+ * Microsoft plugin used. Otherwise additive: a plugin using any of these declares ^0.45.0.
+ *
+ * 0.46.0 adds `@bonsai/plugin-sdk/artifact-provenance`, so a plugin shipped as files can finalize
+ * and read the provenance the host captured. Additive: a plugin that imports it declares ^0.46.0.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.45.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.46.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -4751,6 +4761,7 @@ declare function refineWebSessionScopeConfined(webSession: {
     readonly probe: {
         readonly url: string;
     };
+    readonly signInFirst?: string | undefined;
 }, ctx: z.RefinementCtx): void;
 
 declare const RegistrableDomain: z.ZodString;
@@ -5059,6 +5070,7 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                 external: "external";
                 embedded: "embedded";
             }>;
+            signInFirst: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
     grants: z.ZodOptional<z.ZodObject<{
@@ -5518,6 +5530,7 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
         authSchemeId: z.ZodOptional<z.ZodString>;
         knownResources: z.ZodOptional<z.ZodLiteral<true>>;
         describesOperations: z.ZodOptional<z.ZodLiteral<true>>;
+        looksUpWebLinks: z.ZodOptional<z.ZodLiteral<true>>;
     }, z.core.$strict>>>;
     kayAgentArtifactUriModules: z.ZodOptional<z.ZodArray<z.ZodObject<{
         localId: z.ZodString;
@@ -5769,6 +5782,29 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
         uriModule: z.ZodOptional<z.ZodString>;
         schemes: z.ZodOptional<z.ZodArray<z.ZodString>>;
         displayName: z.ZodOptional<z.ZodString>;
+        authService: z.ZodOptional<z.ZodString>;
+        accountLinks: z.ZodOptional<z.ZodObject<{
+            label: z.ZodOptional<z.ZodEnum<{
+                email: "email";
+                name: "name";
+            }>>;
+            pages: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                hostname: z.ZodString;
+                pathname: z.ZodOptional<z.ZodString>;
+                unlessPathname: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                setPathname: z.ZodOptional<z.ZodString>;
+                addQuery: z.ZodRecord<z.ZodString, z.ZodString>;
+            }, z.core.$strict>>>;
+            addresses: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                pattern: z.ZodObject<{
+                    protocol: z.ZodString;
+                    hostname: z.ZodString;
+                    pathname: z.ZodOptional<z.ZodString>;
+                    search: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>;
+                url: z.ZodString;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>>;
         addresses: z.ZodOptional<z.ZodArray<z.ZodObject<{
             pattern: z.ZodObject<{
                 protocol: z.ZodString;
@@ -5789,6 +5825,9 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
         }, z.core.$strict>, z.ZodObject<{
             kind: z.ZodLiteral<"page">;
             pageId: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"local-app">;
+            schemes: z.ZodArray<z.ZodString>;
         }, z.core.$strict>], "kind">>;
         variants: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
             resourceKind: z.ZodString;
@@ -10670,6 +10709,11 @@ declare type UriClaim = UriSchemeClaim | UriPatternClaim | UrlPatternClaim;
  * - `base64`: unpadded base64 of the UTF-8 text (`{base64(:id :calendar)}`).
  * - `slackTimestamp`: a Slack archive message token as the API's timestamp
  *   (`p1783350000000100` becomes `1783350000.000100`).
+ * - `beforeColon`: the part of a `<team>:<user>` id before the colon. It fills nothing for an id
+ *   with no colon or nothing before it.
+ * - `beforeTilde`: the part of an id before its last `~`. It fills nothing with no `~`.
+ * - `encoded`: every reserved character escaped, `:` and `@` too, for a whole URL carried as a
+ *   query value (`continue={encoded(:url)}`).
  *
  * A transform that cannot read its input fills nothing. A claim whose `normalizeTo` fills nothing
  * does not match; a `sourceUrl` that fills nothing paints no link.
@@ -10928,6 +10972,13 @@ declare interface UriModule {
         readonly uri: string;
         readonly payload: unknown;
     }, ctx: UriResolveContext): Promise<UriOperationDescription | undefined>;
+    /**
+     * Find the web address of `uri` by asking the provider, for a resource whose address alone can't
+     * name its page. Called only when someone opens the address, under the account it means, and never
+     * to draw a reference. `undefined` means there's no page to open. A plugin module that defines
+     * this sets `looksUpWebLinks` in its manifest.
+     */
+    lookupWebLink?(uri: string, ctx: UriResolveContext): Promise<string | undefined>;
     readonly getCachePolicy?: UriCachePolicyResolver;
     /**
      * Code matching, for the host's own modules whose addresses no claim can describe (a bare file
@@ -11049,6 +11100,11 @@ declare interface UriOperationDescription {
             readonly editable?: true;
             /** Longest edited value, in UTF-16 code units. Meaningful only with `editable`. */
             readonly maxLength?: number;
+            /**
+             * Which part of a message this field is, when the call sends one. A preview with a `to` and
+             * a `text` is drawn as a message; without them it stays labelled rows.
+             */
+            readonly part?: "to" | "cc" | "bcc" | "subject" | "text";
         }[];
     };
     /** True only when every displayed fact comes from the input, independent of the executing account. */

package/dist/kay-agent.d.ts

@@ -2760,9 +2760,19 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 0.44.0 adds `words.kinds` to a reference presentation (#15905): an ordered list of address patterns
  * and the kind each one names. Additive: a plugin that lists them declares ^0.44.0.
  *
- * 0.45.0 adds declared plugin cards and app.implementCard for their read/submit endpoints.
+ * 0.45.0 adds declared plugin cards and app.implementCard for their read/submit endpoints. It also
+ * lets a plugin declare what the window hardcoded about it (#15906). A reference presentation gains
+ * `accountLinks`, how a page opens under the account an address means, and a `local-app` open, for
+ * an item an app on this machine shows; a plugin the person installed can't declare that open. A
+ * `webSession` gains `signInFirst`. A URI module defines `lookupWebLink` and sets `looksUpWebLinks`
+ * to find a page when someone opens the address, and a preview field marks which `part` of a message
+ * it is. A claim's `brandIcon` is a file path and no longer inline markup, which only this repo's
+ * Microsoft plugin used. Otherwise additive: a plugin using any of these declares ^0.45.0.
+ *
+ * 0.46.0 adds `@bonsai/plugin-sdk/artifact-provenance`, so a plugin shipped as files can finalize
+ * and read the provenance the host captured. Additive: a plugin that imports it declares ^0.46.0.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.45.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.46.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -5800,6 +5810,7 @@ declare function refineWebSessionScopeConfined(webSession: {
     readonly probe: {
         readonly url: string;
     };
+    readonly signInFirst?: string | undefined;
 }, ctx: z.RefinementCtx): void;
 
 declare const RegistrableDomain: z.ZodString;
@@ -10790,6 +10801,11 @@ export declare type UriClaim = UriSchemeClaim | UriPatternClaim | UrlPatternClai
  * - `base64`: unpadded base64 of the UTF-8 text (`{base64(:id :calendar)}`).
  * - `slackTimestamp`: a Slack archive message token as the API's timestamp
  *   (`p1783350000000100` becomes `1783350000.000100`).
+ * - `beforeColon`: the part of a `<team>:<user>` id before the colon. It fills nothing for an id
+ *   with no colon or nothing before it.
+ * - `beforeTilde`: the part of an id before its last `~`. It fills nothing with no `~`.
+ * - `encoded`: every reserved character escaped, `:` and `@` too, for a whole URL carried as a
+ *   query value (`continue={encoded(:url)}`).
  *
  * A transform that cannot read its input fills nothing. A claim whose `normalizeTo` fills nothing
  * does not match; a `sourceUrl` that fills nothing paints no link.
@@ -11096,6 +11112,13 @@ export declare interface UriModule {
         readonly uri: string;
         readonly payload: unknown;
     }, ctx: UriResolveContext): Promise<UriOperationDescription | undefined>;
+    /**
+     * Find the web address of `uri` by asking the provider, for a resource whose address alone can't
+     * name its page. Called only when someone opens the address, under the account it means, and never
+     * to draw a reference. `undefined` means there's no page to open. A plugin module that defines
+     * this sets `looksUpWebLinks` in its manifest.
+     */
+    lookupWebLink?(uri: string, ctx: UriResolveContext): Promise<string | undefined>;
     readonly getCachePolicy?: UriCachePolicyResolver;
     /**
      * Code matching, for the host's own modules whose addresses no claim can describe (a bare file
@@ -11234,6 +11257,11 @@ export declare interface UriOperationDescription {
             readonly editable?: true;
             /** Longest edited value, in UTF-16 code units. Meaningful only with `editable`. */
             readonly maxLength?: number;
+            /**
+             * Which part of a message this field is, when the call sends one. A preview with a `to` and
+             * a `text` is drawn as a message; without them it stays labelled rows.
+             */
+            readonly part?: "to" | "cc" | "bcc" | "subject" | "text";
         }[];
     };
     /** True only when every displayed fact comes from the input, independent of the executing account. */

package/dist/kay-agent.js

@@ -5,12 +5,15 @@ var REST_CAPTURE_RE = /^:([A-Za-z_][A-Za-z0-9_]*)\*$/;
 var CONSTRAINED_CAPTURE_RE = /^([A-Za-z_][A-Za-z0-9_]*)(?:\((.*)\))?(\.[A-Za-z0-9]+)?$/;
 var MAX_CAPTURE_CONSTRAINT_LENGTH = 64;
 function compileUriClaim(claim) {
+  return compileClaim(claim);
+}
+function compileClaim(claim) {
   if (claim.kind === "scheme") {
     const scheme = normalizeProtocol(claim.scheme);
     return {
       claim,
       match(input) {
-        const actual = SCHEME_RE.exec(input.trim())?.[1]?.toLowerCase();
+        const actual = typeof input === "string" ? SCHEME_RE.exec(input.trim())?.[1]?.toLowerCase() : input.scheme;
         if (actual !== scheme)
           return void 0;
         return { claimKind: claim.kind };
@@ -20,8 +23,7 @@ function compileUriClaim(claim) {
   const pattern = compileRoutePattern(claim.pattern);
   const normalizeTo = claim.normalizeTo === void 0 ? void 0 : compileTemplate(claim.normalizeTo);
   const sourceUrl = claim.kind === "uriPattern" && claim.sourceUrl !== void 0 ? compileTemplate(claim.sourceUrl) : void 0;
-  const matchAt = (target, selector) => {
-    const parsed = parsePatternInput(target);
+  const matchAt = (parsed, selector) => {
     if (parsed === void 0)
       return void 0;
     const captures = matchRoute(pattern, parsed);
@@ -47,14 +49,14 @@ function compileUriClaim(claim) {
     claim,
     match(input) {
       if (claim.kind === "uriPattern") {
-        const { selector, rest } = parseUriConnectionSelector(input);
+        const { selector, rest } = typeof input === "string" ? parseUriConnectionSelector(input) : input.connection;
         if (selector !== void 0) {
-          const match = matchAt(rest, selector);
+          const match = matchAt(typeof input === "string" ? parsePatternInput(rest) : input.selected, selector);
           if (match !== void 0)
             return match;
         }
       }
-      return matchAt(input, void 0);
+      return matchAt(typeof input === "string" ? parsePatternInput(input) : input.raw, void 0);
     }
   };
 }
@@ -252,7 +254,16 @@ var TRANSFORMS = {
   slackTimestamp: (value) => {
     const match = /^p(\d+)(\d{6})$/.exec(value);
     return match === null ? void 0 : `${match[1]}.${match[2]}`;
-  }
+  },
+  beforeColon: (value) => {
+    const end = value.indexOf(":");
+    return end > 0 ? value.slice(0, end) : void 0;
+  },
+  beforeTilde: (value) => {
+    const end = value.lastIndexOf("~");
+    return end > 0 ? value.slice(0, end) : void 0;
+  },
+  encoded: encodeURIComponent
 };
 function isTransform(name) {
   return Object.prototype.hasOwnProperty.call(TRANSFORMS, name);
@@ -323,7 +334,7 @@ function fillTemplate(parts, captures, restCaptures) {
     const transformed = TRANSFORMS[part.transform](raw);
     if (transformed === void 0)
       return void 0;
-    out += escapeForPosition(transformed, part.position);
+    out += part.transform === "encoded" ? transformed : escapeForPosition(transformed, part.position);
   }
   return out;
 }

package/dist/kay-app.d.ts

@@ -2745,9 +2745,19 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 0.44.0 adds `words.kinds` to a reference presentation (#15905): an ordered list of address patterns
  * and the kind each one names. Additive: a plugin that lists them declares ^0.44.0.
  *
- * 0.45.0 adds declared plugin cards and app.implementCard for their read/submit endpoints.
+ * 0.45.0 adds declared plugin cards and app.implementCard for their read/submit endpoints. It also
+ * lets a plugin declare what the window hardcoded about it (#15906). A reference presentation gains
+ * `accountLinks`, how a page opens under the account an address means, and a `local-app` open, for
+ * an item an app on this machine shows; a plugin the person installed can't declare that open. A
+ * `webSession` gains `signInFirst`. A URI module defines `lookupWebLink` and sets `looksUpWebLinks`
+ * to find a page when someone opens the address, and a preview field marks which `part` of a message
+ * it is. A claim's `brandIcon` is a file path and no longer inline markup, which only this repo's
+ * Microsoft plugin used. Otherwise additive: a plugin using any of these declares ^0.45.0.
+ *
+ * 0.46.0 adds `@bonsai/plugin-sdk/artifact-provenance`, so a plugin shipped as files can finalize
+ * and read the provenance the host captured. Additive: a plugin that imports it declares ^0.46.0.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.45.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.46.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -3653,14 +3663,15 @@ export declare type KayAppAutomationMatch = {
     readonly requestedBy?: "user" | "agent" | undefined;
 };
 
-/** Match any listed type; filters use strict equality or scalar-list containment. */
+/**
+ * Match any listed type. `where` is an expression over the event: `==` and `!=` compare a whole
+ * value, and `contains` looks inside a list, as in
+ * `payload.status == 'open' && payload.labels contains 'urgent'`.
+ */
 export declare interface KayAppAutomationPluginEventCondition {
     readonly kind: "plugin-event";
     readonly events: readonly string[];
-    readonly where?: readonly {
-        readonly path: string;
-        readonly equals: string | number | boolean;
-    }[];
+    readonly where?: string;
 }
 
 /**
@@ -10234,6 +10245,7 @@ declare function refineWebSessionScopeConfined(webSession: {
     readonly probe: {
         readonly url: string;
     };
+    readonly signInFirst?: string | undefined;
 }, ctx: z.RefinementCtx): void;
 
 export declare interface RegisteredHostApprovalType {
@@ -15652,6 +15664,11 @@ declare type UriClaim = UriSchemeClaim | UriPatternClaim | UrlPatternClaim;
  * - `base64`: unpadded base64 of the UTF-8 text (`{base64(:id :calendar)}`).
  * - `slackTimestamp`: a Slack archive message token as the API's timestamp
  *   (`p1783350000000100` becomes `1783350000.000100`).
+ * - `beforeColon`: the part of a `<team>:<user>` id before the colon. It fills nothing for an id
+ *   with no colon or nothing before it.
+ * - `beforeTilde`: the part of an id before its last `~`. It fills nothing with no `~`.
+ * - `encoded`: every reserved character escaped, `:` and `@` too, for a whole URL carried as a
+ *   query value (`continue={encoded(:url)}`).
  *
  * A transform that cannot read its input fills nothing. A claim whose `normalizeTo` fills nothing
  * does not match; a `sourceUrl` that fills nothing paints no link.
@@ -15893,6 +15910,13 @@ declare interface UriModule_2 {
         readonly uri: string;
         readonly payload: unknown;
     }, ctx: UriResolveContext): Promise<UriOperationDescription | undefined>;
+    /**
+     * Find the web address of `uri` by asking the provider, for a resource whose address alone can't
+     * name its page. Called only when someone opens the address, under the account it means, and never
+     * to draw a reference. `undefined` means there's no page to open. A plugin module that defines
+     * this sets `looksUpWebLinks` in its manifest.
+     */
+    lookupWebLink?(uri: string, ctx: UriResolveContext): Promise<string | undefined>;
     /**
      * Set false when the generic write tool must reject `source` copies before
      * fetching the source. Inline `content` writes remain available.
@@ -16090,6 +16114,11 @@ declare interface UriOperationDescription {
             readonly editable?: true;
             /** Longest edited value, in UTF-16 code units. Meaningful only with `editable`. */
             readonly maxLength?: number;
+            /**
+             * Which part of a message this field is, when the call sends one. A preview with a `to` and
+             * a `text` is drawn as a message; without them it stays labelled rows.
+             */
+            readonly part?: "to" | "cc" | "bcc" | "subject" | "text";
         }[];
     };
     /** True only when every displayed fact comes from the input, independent of the executing account. */

package/dist/vendored-mcp.d.ts

@@ -377,6 +377,11 @@ declare type UriClaim = UriSchemeClaim | UriPatternClaim | UrlPatternClaim;
  * - `base64`: unpadded base64 of the UTF-8 text (`{base64(:id :calendar)}`).
  * - `slackTimestamp`: a Slack archive message token as the API's timestamp
  *   (`p1783350000000100` becomes `1783350000.000100`).
+ * - `beforeColon`: the part of a `<team>:<user>` id before the colon. It fills nothing for an id
+ *   with no colon or nothing before it.
+ * - `beforeTilde`: the part of an id before its last `~`. It fills nothing with no `~`.
+ * - `encoded`: every reserved character escaped, `:` and `@` too, for a whole URL carried as a
+ *   query value (`continue={encoded(:url)}`).
  *
  * A transform that cannot read its input fills nothing. A claim whose `normalizeTo` fills nothing
  * does not match; a `sourceUrl` that fills nothing paints no link.
@@ -635,6 +640,13 @@ declare interface UriModule {
         readonly uri: string;
         readonly payload: unknown;
     }, ctx: UriResolveContext): Promise<UriOperationDescription | undefined>;
+    /**
+     * Find the web address of `uri` by asking the provider, for a resource whose address alone can't
+     * name its page. Called only when someone opens the address, under the account it means, and never
+     * to draw a reference. `undefined` means there's no page to open. A plugin module that defines
+     * this sets `looksUpWebLinks` in its manifest.
+     */
+    lookupWebLink?(uri: string, ctx: UriResolveContext): Promise<string | undefined>;
     readonly getCachePolicy?: UriCachePolicyResolver;
     /**
      * Code matching, for the host's own modules whose addresses no claim can describe (a bare file
@@ -756,6 +768,11 @@ declare interface UriOperationDescription {
             readonly editable?: true;
             /** Longest edited value, in UTF-16 code units. Meaningful only with `editable`. */
             readonly maxLength?: number;
+            /**
+             * Which part of a message this field is, when the call sends one. A preview with a `to` and
+             * a `text` is drawn as a message; without them it stays labelled rows.
+             */
+            readonly part?: "to" | "cc" | "bcc" | "subject" | "text";
         }[];
     };
     /** True only when every displayed fact comes from the input, independent of the executing account. */

package/dist/vendored-mcp.js

@@ -76,12 +76,15 @@ var REST_CAPTURE_RE = /^:([A-Za-z_][A-Za-z0-9_]*)\*$/;
 var CONSTRAINED_CAPTURE_RE = /^([A-Za-z_][A-Za-z0-9_]*)(?:\((.*)\))?(\.[A-Za-z0-9]+)?$/;
 var MAX_CAPTURE_CONSTRAINT_LENGTH = 64;
 function compileUriClaim(claim) {
+  return compileClaim(claim);
+}
+function compileClaim(claim) {
   if (claim.kind === "scheme") {
     const scheme = normalizeProtocol(claim.scheme);
     return {
       claim,
       match(input) {
-        const actual = SCHEME_RE.exec(input.trim())?.[1]?.toLowerCase();
+        const actual = typeof input === "string" ? SCHEME_RE.exec(input.trim())?.[1]?.toLowerCase() : input.scheme;
         if (actual !== scheme)
           return void 0;
         return { claimKind: claim.kind };
@@ -91,8 +94,7 @@ function compileUriClaim(claim) {
   const pattern = compileRoutePattern(claim.pattern);
   const normalizeTo = claim.normalizeTo === void 0 ? void 0 : compileTemplate(claim.normalizeTo);
   const sourceUrl = claim.kind === "uriPattern" && claim.sourceUrl !== void 0 ? compileTemplate(claim.sourceUrl) : void 0;
-  const matchAt = (target, selector) => {
-    const parsed = parsePatternInput(target);
+  const matchAt = (parsed, selector) => {
     if (parsed === void 0)
       return void 0;
     const captures = matchRoute(pattern, parsed);
@@ -118,14 +120,14 @@ function compileUriClaim(claim) {
     claim,
     match(input) {
       if (claim.kind === "uriPattern") {
-        const { selector, rest } = parseUriConnectionSelector(input);
+        const { selector, rest } = typeof input === "string" ? parseUriConnectionSelector(input) : input.connection;
         if (selector !== void 0) {
-          const match = matchAt(rest, selector);
+          const match = matchAt(typeof input === "string" ? parsePatternInput(rest) : input.selected, selector);
           if (match !== void 0)
             return match;
         }
       }
-      return matchAt(input, void 0);
+      return matchAt(typeof input === "string" ? parsePatternInput(input) : input.raw, void 0);
     }
   };
 }
@@ -323,7 +325,16 @@ var TRANSFORMS = {
   slackTimestamp: (value) => {
     const match = /^p(\d+)(\d{6})$/.exec(value);
     return match === null ? void 0 : `${match[1]}.${match[2]}`;
-  }
+  },
+  beforeColon: (value) => {
+    const end = value.indexOf(":");
+    return end > 0 ? value.slice(0, end) : void 0;
+  },
+  beforeTilde: (value) => {
+    const end = value.lastIndexOf("~");
+    return end > 0 ? value.slice(0, end) : void 0;
+  },
+  encoded: encodeURIComponent
 };
 function isTransform(name) {
   return Object.prototype.hasOwnProperty.call(TRANSFORMS, name);
@@ -394,7 +405,7 @@ function fillTemplate(parts, captures, restCaptures) {
     const transformed = TRANSFORMS[part.transform](raw);
     if (transformed === void 0)
       return void 0;
-    out += escapeForPosition(transformed, part.position);
+    out += part.transform === "encoded" ? transformed : escapeForPosition(transformed, part.position);
   }
   return out;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaklabs-ai/plugin-sdk",
-  "version": "0.45.0",
+  "version": "0.46.0",
   "description": "The Kay plugin SDK — types and helpers for authoring a Kay directory plugin.",
   "author": "YakLabs",
   "type": "module",
@@ -33,6 +33,10 @@
       "types": "./dist/disclosure.d.ts",
       "default": "./dist/disclosure.js"
     },
+    "./artifact-provenance": {
+      "types": "./dist/artifact-provenance.d.ts",
+      "default": "./dist/artifact-provenance.js"
+    },
     "./signals": {
       "types": "./dist/signals.d.ts",
       "default": "./dist/signals.js"

package/skills/directory-plugin-authoring/SKILL.md

@@ -43,8 +43,8 @@ pnpm create-plugin --id com.example.widgets
 Run from the root of a Bonsai checkout. It writes a working plugin (manifest, entrypoint, tsconfig,
 README) that already typechecks and loads; `--tier starter` adds a URI module, a bundled skill,
 and a standalone `node --test` test to copy from. Add `--ui` (either tier) when the plugin needs a
-page: it writes `ui.tsx`, declares the `kay.ui` entrypoint, and generates the UI typecheck config
-described below. `--ui` also needs `pnpm --filter @bonsai/ui build` once per checkout; the scaffold
+page: it writes `ui.tsx`, declares it under the manifest's `apps`, and generates the UI typecheck
+config described below. `--ui` also needs `pnpm --filter @bonsai/ui build` once per checkout; the scaffold
 stops and says so when that build is missing.
 
 Never hand-build a plugin as a tsc-compiled package and copy the output into `~/.kay/plugins/`.
@@ -122,14 +122,15 @@ a plugin you install yourself.
 
 A plugin with a UI has three targets. Each declared daemon target is a bundle root, so its
 entrypoint may import other files in the plugin; `kay.agent` runs in the daemon per session and
-`kay.app` runs in the daemon once. `kay.ui` runs in the renderer through its own UI bundle, which is a single
-self-contained module: unlike the daemon targets, `ui.tsx` cannot import sibling files. A
-plugin UI contributes through `api.slots` (`registerPage`, `registerSidebarItem`,
-`registerPaneAction`, and the rest of `buildSlots` in
-`packages/kay-renderer/src/renderer/src/extension-loader/build-extension-api.ts`). A page gets its own
+`kay.app` runs in the daemon once. A page runs in the renderer: declare it under `apps` in
+`targets.kay.ui.contributes`, with `entrypoint.module` naming your source and `entrypoint.export`
+the component. Bonsai compiles it when it loads the plugin, so there is no build step: relative
+imports work within the plugin's folder, and Tailwind classes work with no setup against Bonsai's
+theme. A page imports only `react` and `@bonsai/plugin-ui-sdk`; a `kay.ui` `entrypoint` with an
+`activate` function is for what a declaration cannot do yet, not for pages. A page gets its own
 activity-rail button when the manifest declares it: `railEntries` under `targets.kay.ui.contributes`,
-with `id`, `title` and `page`, and optionally `icon`, `shortcut`, `order` and `section`. That
-declaration works with no `ui.tsx` at all. To give the entry a sidebar, add `panel: { body }` naming
+with `id`, `title` and `page` (`<namespace>.<app localId>`), and optionally `icon`, `shortcut`,
+`order` and `section`. To give the entry a sidebar, add `panel: { body }` naming
 an app in the same manifest with `contextOnly: true`. The sidebar is always there once declared, so
 the app shows its own empty state. To give a notification rule's toast a "Show changes" preview, add
 a `toastPreviews` entry under `targets.kay.ui.contributes` with `rule` (the rule's `localId`), `body`
@@ -143,11 +144,11 @@ on a small white tile). Set `icon` on a rail entry to show a single-colour glyph
 the plugin (`"./assets/rail.svg"`). Only its shape is used, painted in the rail's colour, so colours
 in the file are ignored, and it must be transparent where nothing should draw. A missing file is a
 load diagnostic and the entry falls back to the plugin icon. The page the entry opens wears the same
-icon unless `registerPage`'s `icon` says otherwise. Full
+icon. Full
 precedence: `packages/kay-frontend-sdk/ARCHITECTURE.md`, "Plugin icon".
 
-`ui.tsx` has no `node_modules` of its own. The renderer bundles it and rewrites its `react` and
-`@bonsai/*` imports to the host's `__KAY_UI_RUNTIME__` singletons, so the agent `tsconfig.json`
+`ui.tsx` has no `node_modules` of its own. Bonsai compiles it and rewrites its `react` and
+`@bonsai/plugin-ui-sdk` imports to the host's `__KAY_UI_RUNTIME__` singletons, so the agent `tsconfig.json`
 cannot cover it, and a plugin whose UI nothing typechecks has shipped three wrong API shapes at
 once. `pnpm create-plugin --ui` generates `tsconfig.ui.json` for exactly this: its `paths` are
 derived from the bundler's own shim set (`uiRuntimeShimModules` in `@bonsai/ui-app-bundler`), each
@@ -155,15 +156,13 @@ specifier mapped to the type entry the renderer binds it to, and `npm run typech
 configs. Do not hand-write the map; when the bundler's set changes, the scaffold's test fails and
 the generated config follows.
 
-Two facts about that config worth knowing when you read errors from it:
+That config typechecks `ui.tsx` as a browser module: `Bundler` resolution, automatic JSX, DOM libs,
+no Node globals. The agent config keeps `**/*.ts`, so the two programs never overlap. Add a new page
+file to its `include`.
 
-- The bare `@bonsai/frontend-sdk` is typed against the SDK's `ui-runtime` facade, because that is
-  what the renderer binds it to. The facade carries the SDK's whole type surface, so
-  `KayUiExtensionApi` and every descriptor type import fine; a **value** only the package's main
-  entry exports fails to compile there (TS1362, "exported using export type"), which is the
-  compiler telling you the running extension would receive `undefined`.
-- It typechecks `ui.tsx` alone, as a browser module: `Bundler` resolution, automatic JSX, DOM
-  libs, no Node globals. The agent config keeps `**/*.ts`, so the two programs never overlap.
+`pnpm plugin:check` also compiles a page declared as source, so a broken import or a refused
+`@bonsai/*` package shows up there as `kay-ui-app-compile-failed`. If a class with a variant seems
+to do nothing, see "How a plugin page gets Tailwind" in `docs/frontend-styling.md`.
 
 For a plugin scaffolded before `--ui` existed, scaffold a throwaway `--ui` plugin from the same
 checkout and copy its `tsconfig.ui.json` and the second `typecheck` command into yours; `--force`