@yaklabs-ai/plugin-sdk 0.55.1 → 0.55.3

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.3"
   }
 }
 ```
@@ -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.3" },
   "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.3`).
 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.3`).
 
 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.3`. 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.3",
   "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,15 @@ 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.
+ *
+ * 0.55.3 lets a signal carry the item's own text. `PluginSignal` gains an optional `body`: plain
+ * text, at most `PLUGIN_SIGNAL_BODY_MAX` (20,000) characters. Gmail puts a mail's text there, so
+ * Flows can keep the messages a task came from. Additive: a plugin that publishes a body declares
+ * ^0.55.3.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.55.1";
+declare const KAY_PLUGIN_SDK_VERSION: "0.55.3";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -10225,7 +10232,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 +10243,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,15 @@ 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.
+ *
+ * 0.55.3 lets a signal carry the item's own text. `PluginSignal` gains an optional `body`: plain
+ * text, at most `PLUGIN_SIGNAL_BODY_MAX` (20,000) characters. Gmail puts a mail's text there, so
+ * Flows can keep the messages a task came from. Additive: a plugin that publishes a body declares
+ * ^0.55.3.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.55.1";
+declare const KAY_PLUGIN_SDK_VERSION: "0.55.3";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -5763,6 +5770,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 +6058,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 +11860,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 +11871,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,15 @@ 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.
+ *
+ * 0.55.3 lets a signal carry the item's own text. `PluginSignal` gains an optional `body`: plain
+ * text, at most `PLUGIN_SIGNAL_BODY_MAX` (20,000) characters. Gmail puts a mail's text there, so
+ * Flows can keep the messages a task came from. Additive: a plugin that publishes a body declares
+ * ^0.55.3.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.55.1";
+declare const KAY_PLUGIN_SDK_VERSION: "0.55.3";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -11753,7 +11760,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 +11771,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-session-summary.d.ts

@@ -2230,6 +2230,14 @@ declare interface KayAppSessions {
      * against `sessions.read`. Unsupported hosts may omit it.
      */
     listSessionPage?(request: KayAppSessionListRequest): Promise<KayAppSessionList>;
+    /**
+     * Called after a stored session's index row changes (its title, folder or project, or its
+     * removal); a change without `sessionId` means any session may have changed. Checked against
+     * `sessions.read`. Returns the unsubscribe. Unsupported hosts may omit it.
+     */
+    subscribeChanges?(listener: (change: {
+        readonly sessionId?: string;
+    }) => void): () => void;
     /**
      * Read a cheap transcript change marker without loading the entry log. Unknown or deleted
      * sessions yield `undefined`.

package/dist/kay-app.d.ts

@@ -4390,8 +4390,15 @@ 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.
+ *
+ * 0.55.3 lets a signal carry the item's own text. `PluginSignal` gains an optional `body`: plain
+ * text, at most `PLUGIN_SIGNAL_BODY_MAX` (20,000) characters. Gmail puts a mail's text there, so
+ * Flows can keep the messages a task came from. Additive: a plugin that publishes a body declares
+ * ^0.55.3.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.55.1";
+declare const KAY_PLUGIN_SDK_VERSION: "0.55.3";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -6142,6 +6149,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. */
@@ -6977,8 +6986,19 @@ export declare interface KayAppPluginApi {
     implementWorkflow(localId: string, run: KayAppWorkflowImplementation): void;
 }
 
+/** What `kay.app` code may add to one publish beyond the event itself. */
+export declare interface KayAppPluginEventPublishOptions {
+    /**
+     * A session this plugin created through `sessions.create`: the host records it as the event's
+     * session, so a notification rule's `session-unfocused` stays quiet while that session is the
+     * focused pane. The host refuses a session this plugin did not create. Absent publishes an
+     * app-lifetime event, as before.
+     */
+    readonly sessionId?: string;
+}
+
 export declare interface KayAppPluginEvents {
-    publish(localId: string, input: PluginEventPublishInput): void;
+    publish(localId: string, input: PluginEventPublishInput, options?: KayAppPluginEventPublishOptions): void;
 }
 
 /**
@@ -7923,6 +7943,14 @@ export declare interface KayAppSessions {
      * against `sessions.read`. Unsupported hosts may omit it.
      */
     listSessionPage?(request: KayAppSessionListRequest): Promise<KayAppSessionList>;
+    /**
+     * Called after a stored session's index row changes (its title, folder or project, or its
+     * removal); a change without `sessionId` means any session may have changed. Checked against
+     * `sessions.read`. Returns the unsubscribe. Unsupported hosts may omit it.
+     */
+    subscribeChanges?(listener: (change: {
+        readonly sessionId?: string;
+    }) => void): () => void;
     /**
      * Read a cheap transcript change marker without loading the entry log. Unknown or deleted
      * sessions yield `undefined`.
@@ -10051,13 +10079,20 @@ export declare interface KayAppWorkingDocuments {
  * recovery data.
  */
 export declare interface KayAppWorkspace {
+    /**
+     * Called after the window publishes a new snapshot (tabs, groups, panes or titles changed). Read
+     * `snapshot()` for the new state. Returns the unsubscribe.
+     */
+    subscribe(listener: () => void): () => void;
     snapshot(): Promise<{
         readonly kind: "snapshot";
         readonly snapshot: KayAppWorkspaceSnapshot;
     } | {
         readonly kind: "unavailable";
     }>;
-    execute(command: KayAppWorkspaceCommand, ctx: KayAppWorkspaceExecuteContext): Promise<{
+    execute(command: KayAppWorkspaceCommand, 
+    /** The session the command is issued for; absent for a plugin's own background work. */
+    ctx?: KayAppWorkspaceExecuteContext): Promise<{
         readonly kind: "outcome";
         readonly outcome: KayAppWorkspaceCommandOutcome;
         readonly validPageIds?: readonly string[];
@@ -10101,6 +10136,23 @@ export declare type KayAppWorkspaceCommand = {
 } | {
     verb: "tabs.ungroup";
     tabIds: readonly string[];
+} | {
+    /**
+     * Set the membership and look of this plugin's own linked tab groups, computed from the
+     * snapshot numbered `rev` (`stale` when the tabs changed since). Each listed group ends up
+     * holding exactly `tabIds` plus its guests, created when missing; only ungrouped Tabs join.
+     * One of this plugin's groups left unlisted keeps only its guests. Never recorded as the
+     * person's own edit.
+     */
+    verb: "tabs.syncLinkedGroups";
+    rev: number;
+    groups: readonly {
+        readonly key: string;
+        readonly name: string;
+        readonly color?: KayAppWorkspaceTabGroupColor | undefined;
+        readonly icon?: string | undefined;
+        readonly tabIds: readonly string[];
+    }[];
 } | {
     verb: "panes.split";
     tabId: string;
@@ -10259,15 +10311,21 @@ export declare type KayAppWorkspacePlaceContent = {
 };
 
 /** The full workspace tree, app-wide (every tab, not one session's). */
-export declare interface KayAppWorkspaceSnapshot {
-    readonly rev: number;
-    readonly activeTabId: string;
-    readonly tabs: readonly KayAppWorkspaceTabSnapshot[];
-}
+/**
+ * The workspace as the window last published it: every Tab, the tab groups (`link` present only on
+ * a linked tab group), and the person's linked-group guests and dismissals in this window.
+ */
+export declare type KayAppWorkspaceSnapshot = ReadonlyContract<WorkspaceSnapshot>;
 
 /** The tab-group colour palette, by name (Chrome's nine); mirrors the wire schema's enum. */
 export declare type KayAppWorkspaceTabGroupColor = "grey" | "blue" | "red" | "yellow" | "green" | "pink" | "purple" | "cyan" | "orange";
 
+/** The plugin a linked tab group belongs to and the key that plugin chose for it. */
+export declare type KayAppWorkspaceTabGroupLink = NonNullable<KayAppWorkspaceTabGroupSnapshot["link"]>;
+
+/** One tab group in the strip. */
+export declare type KayAppWorkspaceTabGroupSnapshot = NonNullable<KayAppWorkspaceSnapshot["groups"]>[number];
+
 export declare type KayAppWorkspaceTabSnapshot = ReadonlyContract<WorkspaceTabSnapshot>;
 
 /**
@@ -11530,6 +11588,12 @@ export declare const PLUGIN_SIGNAL_ATTACHMENT_TYPE_MAX = 127;
 /** At most this many entries in a signal's `attachments`; a source lists the first ones. */
 export declare const PLUGIN_SIGNAL_ATTACHMENTS_MAX = 10;
 
+/**
+ * A signal's `body`, the item's own text, at most this many characters: a source cuts longer text
+ * and marks the cut. Enough for a long email with its quoted history.
+ */
+export declare const PLUGIN_SIGNAL_BODY_MAX = 20000;
+
 /** 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"];
 
@@ -11711,6 +11775,7 @@ export declare const PluginSignal: z.ZodObject<{
     }>>;
     title: z.ZodOptional<z.ZodString>;
     snippet: z.ZodOptional<z.ZodString>;
+    body: z.ZodOptional<z.ZodString>;
     actor: z.ZodOptional<z.ZodObject<{
         name: z.ZodOptional<z.ZodString>;
         uri: z.ZodString;
@@ -11755,6 +11820,7 @@ export declare const PluginSignalPublish: z.ZodObject<{
         }>>;
         title: z.ZodOptional<z.ZodString>;
         snippet: z.ZodOptional<z.ZodString>;
+        body: z.ZodOptional<z.ZodString>;
         actor: z.ZodOptional<z.ZodObject<{
             name: z.ZodOptional<z.ZodString>;
             uri: z.ZodString;
@@ -18261,7 +18327,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 +18338,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.
@@ -19162,6 +19232,7 @@ declare const WorkspaceCommandOutcome: z.ZodEnum<{
     "no-window": "no-window";
     "not-found": "not-found";
     applied: "applied";
+    stale: "stale";
 }>;
 
 declare type WorkspaceCommandOutcome = z.infer<typeof WorkspaceCommandOutcome>;
@@ -19214,11 +19285,64 @@ declare type WorkspacePaneNode = {
 
 declare const WorkspacePaneNode: z.ZodType<WorkspacePaneNode>;
 
+/**
+ * The full workspace tree, app-wide (every tab, not one session's). `rev` is a monotonic counter the
+ * renderer stamps on push (mirroring the `<kay_tab_context>` block's `rev`), so a reader can tell a
+ * pulled snapshot apart from one already in hand.
+ */
+declare const WorkspaceSnapshot: z.ZodObject<{
+    rev: z.ZodNumber;
+    activeTabId: z.ZodString;
+    tabs: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        active: z.ZodBoolean;
+        variable: z.ZodOptional<z.ZodBoolean>;
+        preview: z.ZodOptional<z.ZodBoolean>;
+        groupId: z.ZodOptional<z.ZodString>;
+        sessionIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        focusedPaneId: z.ZodString;
+        maximizedPaneId: z.ZodNullable<z.ZodString>;
+        root: z.ZodType<WorkspacePaneNode, unknown, z.core.$ZodTypeInternals<WorkspacePaneNode, unknown>>;
+    }, z.core.$strict>>;
+    groups: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        color: z.ZodEnum<{
+            grey: "grey";
+            blue: "blue";
+            red: "red";
+            yellow: "yellow";
+            green: "green";
+            pink: "pink";
+            purple: "purple";
+            cyan: "cyan";
+            orange: "orange";
+        }>;
+        collapsed: z.ZodOptional<z.ZodBoolean>;
+        icon: z.ZodOptional<z.ZodString>;
+        link: z.ZodOptional<z.ZodObject<{
+            pluginId: z.ZodString;
+            key: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>;
+    linkedGroupGuests: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    linkedGroupsDismissed: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        pluginId: z.ZodString;
+        key: z.ZodString;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+
+declare type WorkspaceSnapshot = z.infer<typeof WorkspaceSnapshot>;
+
 declare const WorkspaceTabSnapshot: z.ZodObject<{
     id: z.ZodString;
     label: z.ZodString;
     active: z.ZodBoolean;
     variable: z.ZodOptional<z.ZodBoolean>;
+    preview: z.ZodOptional<z.ZodBoolean>;
+    groupId: z.ZodOptional<z.ZodString>;
+    sessionIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
     focusedPaneId: z.ZodString;
     maximizedPaneId: z.ZodNullable<z.ZodString>;
     root: z.ZodType<WorkspacePaneNode, unknown, z.core.$ZodTypeInternals<WorkspacePaneNode, unknown>>;

package/dist/kay-app.js

@@ -371,6 +371,7 @@ var PLUGIN_SIGNAL_KINDS = [
 ];
 var PLUGIN_SIGNAL_TITLE_MAX = 300;
 var PLUGIN_SIGNAL_SNIPPET_MAX = 500;
+var PLUGIN_SIGNAL_BODY_MAX = 2e4;
 var PLUGIN_SIGNAL_LABELS_MAX = 20;
 var PLUGIN_SIGNAL_LABEL_MAX = 64;
 var PLUGIN_SIGNAL_ATTACHMENTS_MAX = 10;
@@ -1205,6 +1206,7 @@ export {
   PLUGIN_SIGNAL_ATTACHMENTS_MAX,
   PLUGIN_SIGNAL_ATTACHMENT_NAME_MAX,
   PLUGIN_SIGNAL_ATTACHMENT_TYPE_MAX,
+  PLUGIN_SIGNAL_BODY_MAX,
   PLUGIN_SIGNAL_KINDS,
   PLUGIN_SIGNAL_LABELS_MAX,
   PLUGIN_SIGNAL_LABEL_MAX,

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.3",
   "description": "The Kay plugin SDK — types and helpers for authoring a Kay directory plugin.",
   "author": "YakLabs",
   "type": "module",