@yaklabs-ai/plugin-sdk 0.55.1 → 0.55.2

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.55.1"
+    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.55.2"
   }
 }
 ```
@@ -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.55.1" },
+  "compatibility": { "sdk": "^0.55.2" },
   "targets": {
     "kay": {
       "agent": {
@@ -153,7 +153,7 @@ naming both versions, instead of loading it and finding no `activate`.
 | `@bonsai/plugin-sdk/system-one`         | The types and error class for `api.systemOne` / `app.systemOne`, from 0.13.8                                  |
 | `@bonsai/plugin-sdk/zod`                | `z` (the host's in the daemon), on an entry with no other import, from 0.13.9                                 |
 
-A plugin that imports these subpaths declares the current supported SDK range (`^0.55.1`).
+A plugin that imports these subpaths declares the current supported SDK range (`^0.55.2`).
 The rows record when each subpath appeared, not retained runtime compatibility. `vendored-mcp` builds the plugin's URI module (its link cards and help); hosting the
 vendor's MCP server itself is a separate host decision: Bonsai hosts it once a person approves
 the plugin's `mcp.host-server` grant for that server's name and URL. A server that needs an OAuth
@@ -161,7 +161,7 @@ sign-in names one of the plugin's auth services in `authService`; that service m
 one `delegated` scheme, which Bonsai uses to sign the person in to the server. Bonsai declares that
 scheme at runtime; the plugin's code must not declare it again. From 0.16.2 a plugin's code can also
 call the server's tools through `api.vendoredMcp.port(<server>)`, typed by this subpath's
-`VendoredMcpPort` and `VendoredMcpOutcome` (declare `^0.55.1`).
+`VendoredMcpPort` and `VendoredMcpOutcome` (declare `^0.55.2`).
 
 From 0.13.10 the manifest schema carries two facts Bonsai reads for its own plugins only; another
 plugin's are ignored, with a load diagnostic. An `external-cli` auth scheme's `cli` says how Bonsai
@@ -243,7 +243,7 @@ Provider schemas remain authoritative; declaring a dependency grants no authorit
 through `app.uri`, parse returned Markdown in the consuming plugin, and retain the read's
 revision (or `contentDigest` from `/uri`) for edits. The old `memory.read` and `memory.write`
 grants do not authorize the replacement scheme-and-verb calls. Contracts before 0.49.0 are
-refused; migrate and declare `^0.55.1`. The current host also serves the 0.49.0 resource contract.
+refused; migrate and declare `^0.55.2`. The current host also serves the 0.49.0 resource contract.
 
 ## What this package is, and is not, at runtime
 

package/THIRD-PARTY-INVENTORY.json

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

package/dist/disclosure.d.ts

@@ -1723,7 +1723,7 @@ declare type InteractionSurface = Pick<InteractionDriver, "isAvailable" | "targe
 
 /**
  * One thing a driver can be pointed at: a browser page, a running app. `id` is the driver-owned
- * address the agent passes back as `target` (`kay://tabs/.../items/<item>`, `app://<bundle id>`).
+ * address the agent passes back as `target` (`bonsai://tabs/.../items/<item>`, `app://<bundle id>`).
  * `active` marks the default target (the page the user is looking at, the front app).
  */
 declare const InteractionTarget: z.ZodObject<{
@@ -2680,8 +2680,10 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 0.55.1 adds canonical path resources on declared tool permissions, asynchronous display-only
  * tool previews with cancellation, app-scoped availability snapshots and app-target output
  * artifact usage declarations. A plugin using these declares ^0.55.1.
+ *
+ * 0.55.2 adds opt-in query and connection-selector preservation during URI claim normalization.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.55.1";
+declare const KAY_PLUGIN_SDK_VERSION: "0.55.2";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -10225,7 +10227,7 @@ declare interface UriParameter {
 /**
  * A claim on a module's own custom-scheme addresses. The pattern matches with or without an
  * account prefix: `gcal://@work/events/x` is matched as `gcal://events/x`, and the prefix is put
- * back on the official spelling, so one claim covers both spellings.
+ * back on the same-scheme official spelling, so one claim covers both spellings.
  */
 declare interface UriPatternClaim {
     readonly kind: "uriPattern";
@@ -10236,9 +10238,13 @@ declare interface UriPatternClaim {
      * carried over verbatim so a route flag such as `?permanent=true` survives
      * canonicalization (kay#7859); a template that re-targets to another scheme
      * (a projection to a web link) drops it, as does a pattern that consumed the
-     * query itself or a template that spells its own.
+     * query itself or a template that spells its own. `preserveQuery` opts out of those defaults.
      */
     readonly normalizeTo?: UriClaimTemplate;
+    /** Carry the matched query verbatim across normalization; incompatible with a target query. */
+    readonly preserveQuery?: true;
+    /** Carry the input's account selector even when normalization changes scheme. */
+    readonly preserveConnection?: true;
     /**
      * Names the route this claim matches, so data keyed by route (a module's sign-in action rules)
      * can say which addresses it means. Several claims may name the same route.

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

@@ -1759,7 +1759,7 @@ declare type InteractionSurface = Pick<InteractionDriver, "isAvailable" | "targe
 
 /**
  * One thing a driver can be pointed at: a browser page, a running app. `id` is the driver-owned
- * address the agent passes back as `target` (`kay://tabs/.../items/<item>`, `app://<bundle id>`).
+ * address the agent passes back as `target` (`bonsai://tabs/.../items/<item>`, `app://<bundle id>`).
  * `active` marks the default target (the page the user is looking at, the front app).
  */
 declare const InteractionTarget: z.ZodObject<{
@@ -2734,8 +2734,10 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 0.55.1 adds canonical path resources on declared tool permissions, asynchronous display-only
  * tool previews with cancellation, app-scoped availability snapshots and app-target output
  * artifact usage declarations. A plugin using these declares ^0.55.1.
+ *
+ * 0.55.2 adds opt-in query and connection-selector preservation during URI claim normalization.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.55.1";
+declare const KAY_PLUGIN_SDK_VERSION: "0.55.2";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -5763,6 +5765,8 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                 search: z.ZodExactOptional<z.ZodString>;
             }, z.core.$strict>;
             normalizeTo: z.ZodExactOptional<z.ZodString>;
+            preserveQuery: z.ZodExactOptional<z.ZodLiteral<true>>;
+            preserveConnection: z.ZodExactOptional<z.ZodLiteral<true>>;
             route: z.ZodExactOptional<z.ZodString>;
             sourceUrl: z.ZodExactOptional<z.ZodString>;
             title: z.ZodExactOptional<z.ZodString>;
@@ -6049,6 +6053,8 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                 search: z.ZodExactOptional<z.ZodString>;
             }, z.core.$strict>;
             normalizeTo: z.ZodExactOptional<z.ZodString>;
+            preserveQuery: z.ZodExactOptional<z.ZodLiteral<true>>;
+            preserveConnection: z.ZodExactOptional<z.ZodLiteral<true>>;
             route: z.ZodExactOptional<z.ZodString>;
             sourceUrl: z.ZodExactOptional<z.ZodString>;
             title: z.ZodExactOptional<z.ZodString>;
@@ -11849,7 +11855,7 @@ declare interface UriParameter {
 /**
  * A claim on a module's own custom-scheme addresses. The pattern matches with or without an
  * account prefix: `gcal://@work/events/x` is matched as `gcal://events/x`, and the prefix is put
- * back on the official spelling, so one claim covers both spellings.
+ * back on the same-scheme official spelling, so one claim covers both spellings.
  */
 declare interface UriPatternClaim {
     readonly kind: "uriPattern";
@@ -11860,9 +11866,13 @@ declare interface UriPatternClaim {
      * carried over verbatim so a route flag such as `?permanent=true` survives
      * canonicalization (kay#7859); a template that re-targets to another scheme
      * (a projection to a web link) drops it, as does a pattern that consumed the
-     * query itself or a template that spells its own.
+     * query itself or a template that spells its own. `preserveQuery` opts out of those defaults.
      */
     readonly normalizeTo?: UriClaimTemplate;
+    /** Carry the matched query verbatim across normalization; incompatible with a target query. */
+    readonly preserveQuery?: true;
+    /** Carry the input's account selector even when normalization changes scheme. */
+    readonly preserveConnection?: true;
     /**
      * Names the route this claim matches, so data keyed by route (a module's sign-in action rules)
      * can say which addresses it means. Several claims may name the same route.

package/dist/kay-agent.d.ts

@@ -2107,7 +2107,7 @@ export declare type InteractionTarget = ReadonlyContract<InteractionTarget_2>;
 
 /**
  * One thing a driver can be pointed at: a browser page, a running app. `id` is the driver-owned
- * address the agent passes back as `target` (`kay://tabs/.../items/<item>`, `app://<bundle id>`).
+ * address the agent passes back as `target` (`bonsai://tabs/.../items/<item>`, `app://<bundle id>`).
  * `active` marks the default target (the page the user is looking at, the front app).
  */
 declare const InteractionTarget_2: z.ZodObject<{
@@ -3088,8 +3088,10 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 0.55.1 adds canonical path resources on declared tool permissions, asynchronous display-only
  * tool previews with cancellation, app-scoped availability snapshots and app-target output
  * artifact usage declarations. A plugin using these declares ^0.55.1.
+ *
+ * 0.55.2 adds opt-in query and connection-selector preservation during URI claim normalization.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.55.1";
+declare const KAY_PLUGIN_SDK_VERSION: "0.55.2";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -11753,7 +11755,7 @@ export declare interface UriParameterOptions {
 /**
  * A claim on a module's own custom-scheme addresses. The pattern matches with or without an
  * account prefix: `gcal://@work/events/x` is matched as `gcal://events/x`, and the prefix is put
- * back on the official spelling, so one claim covers both spellings.
+ * back on the same-scheme official spelling, so one claim covers both spellings.
  */
 declare interface UriPatternClaim {
     readonly kind: "uriPattern";
@@ -11764,9 +11766,13 @@ declare interface UriPatternClaim {
      * carried over verbatim so a route flag such as `?permanent=true` survives
      * canonicalization (kay#7859); a template that re-targets to another scheme
      * (a projection to a web link) drops it, as does a pattern that consumed the
-     * query itself or a template that spells its own.
+     * query itself or a template that spells its own. `preserveQuery` opts out of those defaults.
      */
     readonly normalizeTo?: UriClaimTemplate;
+    /** Carry the matched query verbatim across normalization; incompatible with a target query. */
+    readonly preserveQuery?: true;
+    /** Carry the input's account selector even when normalization changes scheme. */
+    readonly preserveConnection?: true;
     /**
      * Names the route this claim matches, so data keyed by route (a module's sign-in action rules)
      * can say which addresses it means. Several claims may name the same route.

package/dist/kay-agent.js

@@ -37,6 +37,9 @@ function compileClaim(claim) {
       }
     };
   }
+  if (claim.kind === "uriPattern" && claim.preserveQuery === true && claim.normalizeTo?.split("#", 1)[0]?.includes("?") === true) {
+    throw new Error("URI claim preserveQuery cannot use normalizeTo with a query.");
+  }
   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;
@@ -55,7 +58,7 @@ function compileClaim(claim) {
       claimKind: claim.kind,
       ...Object.keys(captures).length > 0 ? { captures } : {},
       ...normalized !== void 0 ? {
-        normalizedUri: withSelector(withInputSearch(claim, pattern, parsed, normalized), parsed.protocol, selector)
+        normalizedUri: withSelector(withInputSearch(claim, pattern, parsed, normalized), parsed.protocol, selector, claim.kind === "uriPattern" && claim.preserveConnection === true)
       } : {},
       ...claim.route !== void 0 ? { route: claim.route } : {},
       ...filledSourceUrl !== void 0 ? { sourceUrl: filledSourceUrl } : {},
@@ -88,11 +91,13 @@ function parseUriConnectionSelector(input) {
   }
   return { selector: match[2], rest: `${match[1]}${match[3] ?? ""}` };
 }
-function withSelector(normalized, inputProtocol, selector) {
+function withSelector(normalized, inputProtocol, selector, preserveConnection) {
   if (selector === void 0)
     return normalized;
-  if (templateProtocol(normalized) !== inputProtocol)
+  const targetProtocol = templateProtocol(normalized);
+  if (targetProtocol === void 0 || !preserveConnection && targetProtocol !== inputProtocol) {
     return normalized;
+  }
   const schemeEnd = normalized.indexOf("://") + 3;
   return `${normalized.slice(0, schemeEnd)}@${selector}/${normalized.slice(schemeEnd)}`;
 }
@@ -253,7 +258,14 @@ function safeDecode(value) {
   }
 }
 function withInputSearch(claim, pattern, input, normalized) {
-  if (claim.kind !== "uriPattern" || claim.normalizeTo === void 0 || pattern.search !== void 0 || input.search.length === 0 || claim.normalizeTo.includes("?") || templateProtocol(claim.normalizeTo) !== input.protocol) {
+  if (claim.kind !== "uriPattern" || claim.normalizeTo === void 0 || input.search.length === 0) {
+    return normalized;
+  }
+  if (claim.preserveQuery === true) {
+    const fragment = normalized.indexOf("#");
+    return fragment === -1 ? `${normalized}?${input.search}` : `${normalized.slice(0, fragment)}?${input.search}${normalized.slice(fragment)}`;
+  }
+  if (pattern.search !== void 0 || claim.normalizeTo.includes("?") || templateProtocol(claim.normalizeTo) !== input.protocol) {
     return normalized;
   }
   return `${normalized}?${input.search}`;

package/dist/kay-app.d.ts

@@ -4390,8 +4390,10 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 0.55.1 adds canonical path resources on declared tool permissions, asynchronous display-only
  * tool previews with cancellation, app-scoped availability snapshots and app-target output
  * artifact usage declarations. A plugin using these declares ^0.55.1.
+ *
+ * 0.55.2 adds opt-in query and connection-selector preservation during URI claim normalization.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.55.1";
+declare const KAY_PLUGIN_SDK_VERSION: "0.55.2";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -6142,6 +6144,8 @@ export declare interface KayAppKnowledgeSearchOptions {
     readonly limit?: number;
     /** Treat the last query term as a prefix, for search as the person types. */
     readonly prefixLastTerm?: boolean;
+    /** Skip vector eligibility and query embedding; false or absent keeps hybrid search. */
+    readonly lexicalOnly?: boolean;
     /** Drop vector-leg hits below this cosine similarity. */
     readonly minCosineSimilarity?: number;
     /** Relative weights of the lexical and vector legs in rank fusion. */
@@ -18261,7 +18265,7 @@ declare interface UriParameter {
 /**
  * A claim on a module's own custom-scheme addresses. The pattern matches with or without an
  * account prefix: `gcal://@work/events/x` is matched as `gcal://events/x`, and the prefix is put
- * back on the official spelling, so one claim covers both spellings.
+ * back on the same-scheme official spelling, so one claim covers both spellings.
  */
 declare interface UriPatternClaim {
     readonly kind: "uriPattern";
@@ -18272,9 +18276,13 @@ declare interface UriPatternClaim {
      * carried over verbatim so a route flag such as `?permanent=true` survives
      * canonicalization (kay#7859); a template that re-targets to another scheme
      * (a projection to a web link) drops it, as does a pattern that consumed the
-     * query itself or a template that spells its own.
+     * query itself or a template that spells its own. `preserveQuery` opts out of those defaults.
      */
     readonly normalizeTo?: UriClaimTemplate;
+    /** Carry the matched query verbatim across normalization; incompatible with a target query. */
+    readonly preserveQuery?: true;
+    /** Carry the input's account selector even when normalization changes scheme. */
+    readonly preserveConnection?: true;
     /**
      * Names the route this claim matches, so data keyed by route (a module's sign-in action rules)
      * can say which addresses it means. Several claims may name the same route.

package/dist/vendored-mcp.d.ts

@@ -865,7 +865,7 @@ declare interface UriParameter {
 /**
  * A claim on a module's own custom-scheme addresses. The pattern matches with or without an
  * account prefix: `gcal://@work/events/x` is matched as `gcal://events/x`, and the prefix is put
- * back on the official spelling, so one claim covers both spellings.
+ * back on the same-scheme official spelling, so one claim covers both spellings.
  */
 declare interface UriPatternClaim {
     readonly kind: "uriPattern";
@@ -876,9 +876,13 @@ declare interface UriPatternClaim {
      * carried over verbatim so a route flag such as `?permanent=true` survives
      * canonicalization (kay#7859); a template that re-targets to another scheme
      * (a projection to a web link) drops it, as does a pattern that consumed the
-     * query itself or a template that spells its own.
+     * query itself or a template that spells its own. `preserveQuery` opts out of those defaults.
      */
     readonly normalizeTo?: UriClaimTemplate;
+    /** Carry the matched query verbatim across normalization; incompatible with a target query. */
+    readonly preserveQuery?: true;
+    /** Carry the input's account selector even when normalization changes scheme. */
+    readonly preserveConnection?: true;
     /**
      * Names the route this claim matches, so data keyed by route (a module's sign-in action rules)
      * can say which addresses it means. Several claims may name the same route.

package/dist/vendored-mcp.js

@@ -91,6 +91,9 @@ function compileClaim(claim) {
       }
     };
   }
+  if (claim.kind === "uriPattern" && claim.preserveQuery === true && claim.normalizeTo?.split("#", 1)[0]?.includes("?") === true) {
+    throw new Error("URI claim preserveQuery cannot use normalizeTo with a query.");
+  }
   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;
@@ -109,7 +112,7 @@ function compileClaim(claim) {
       claimKind: claim.kind,
       ...Object.keys(captures).length > 0 ? { captures } : {},
       ...normalized !== void 0 ? {
-        normalizedUri: withSelector(withInputSearch(claim, pattern, parsed, normalized), parsed.protocol, selector)
+        normalizedUri: withSelector(withInputSearch(claim, pattern, parsed, normalized), parsed.protocol, selector, claim.kind === "uriPattern" && claim.preserveConnection === true)
       } : {},
       ...claim.route !== void 0 ? { route: claim.route } : {},
       ...filledSourceUrl !== void 0 ? { sourceUrl: filledSourceUrl } : {},
@@ -142,11 +145,13 @@ function parseUriConnectionSelector(input) {
   }
   return { selector: match[2], rest: `${match[1]}${match[3] ?? ""}` };
 }
-function withSelector(normalized, inputProtocol, selector) {
+function withSelector(normalized, inputProtocol, selector, preserveConnection) {
   if (selector === void 0)
     return normalized;
-  if (templateProtocol(normalized) !== inputProtocol)
+  const targetProtocol = templateProtocol(normalized);
+  if (targetProtocol === void 0 || !preserveConnection && targetProtocol !== inputProtocol) {
     return normalized;
+  }
   const schemeEnd = normalized.indexOf("://") + 3;
   return `${normalized.slice(0, schemeEnd)}@${selector}/${normalized.slice(schemeEnd)}`;
 }
@@ -307,7 +312,14 @@ function safeDecode(value) {
   }
 }
 function withInputSearch(claim, pattern, input, normalized) {
-  if (claim.kind !== "uriPattern" || claim.normalizeTo === void 0 || pattern.search !== void 0 || input.search.length === 0 || claim.normalizeTo.includes("?") || templateProtocol(claim.normalizeTo) !== input.protocol) {
+  if (claim.kind !== "uriPattern" || claim.normalizeTo === void 0 || input.search.length === 0) {
+    return normalized;
+  }
+  if (claim.preserveQuery === true) {
+    const fragment = normalized.indexOf("#");
+    return fragment === -1 ? `${normalized}?${input.search}` : `${normalized.slice(0, fragment)}?${input.search}${normalized.slice(fragment)}`;
+  }
+  if (pattern.search !== void 0 || claim.normalizeTo.includes("?") || templateProtocol(claim.normalizeTo) !== input.protocol) {
     return normalized;
   }
   return `${normalized}?${input.search}`;

package/package.json

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