@yaklabs-ai/plugin-sdk 0.55.3 → 0.55.4

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.3"
+    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.55.4"
   }
 }
 ```
@@ -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.3" },
+  "compatibility": { "sdk": "^0.55.4" },
   "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.3`).
+A plugin that imports these subpaths declares the current supported SDK range (`^0.55.4`).
 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.3`).
+`VendoredMcpPort` and `VendoredMcpOutcome` (declare `^0.55.4`).
 
 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.3`. The current host also serves the 0.49.0 resource contract.
+refused; migrate and declare `^0.55.4`. 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.3",
+  "version": "0.55.4",
   "target": "npm",
   "firstPartyLicense": "MIT",
   "bundled": [

package/dist/canonical-transcript.d.ts

@@ -805,6 +805,13 @@ declare interface CollaborationMessageDetails {
     readonly kind: "message" | "progress";
 }
 
+/**
+ * Why a compaction committed the code-written fallback text instead of a model-written summary:
+ * the standalone executor's reasons, with every provider failure folded into `provider`. A closed
+ * set, so the reason can leave the device; `other` holds anything the executor adds later.
+ */
+declare const COMPACTION_FALLBACK_REASONS: readonly ["deadline", "invalid-cut", "no-callable-model", "insufficient-context", "provider", "unusable-output", "unsupported-stop-directive", "preparation", "model-resolution", "prompt-preparation", "output-validation", "other"];
+
 declare interface CompactionEntry extends EntryBase {
     type: "compaction";
     summary: string;
@@ -826,6 +833,8 @@ declare interface CompactionFailedSessionEvent {
     readonly durationMs: number;
 }
 
+declare type CompactionFallbackReason = (typeof COMPACTION_FALLBACK_REASONS)[number];
+
 /**
  * Why a session-initiated compaction ran. `threshold` is the pluggable-policy
  * usage check, now consulted at TWO points - every tool-batch boundary inside a
@@ -1841,6 +1850,12 @@ declare type HerdHarnessEvent = {
     readonly type: "session_compact";
     readonly compactionEntry: CompactionEntry;
     readonly fromHook: boolean;
+    /** The measurements `herd.context.compacted` carries; see its payload. */
+    readonly tokensBefore?: number;
+    readonly durationMs?: number;
+    readonly fallbackReason?: CompactionFallbackReason;
+    readonly fallbackProviderReason?: RunFailureReason;
+    readonly operationId?: string;
 } | {
     readonly type: "summary_operation_settled";
 } | {

package/dist/disclosure.d.ts

@@ -227,7 +227,7 @@ export declare interface AuditPluginDisclosureInput {
 
 /**
  * The codegen-pair equivalence check every bundled-skill plugin hand-rolled (see
- * `plugins/ARCHITECTURE.md` -> "Bundled skills", step 4): every exported `PluginSkillDefinition`
+ * `plugins/gmail/test/gmail-plugin.test.ts`): every exported `PluginSkillDefinition`
  * must have a matching manifest declaration (same `localId`, same `description`), and the
  * declared `SKILL.md` file's decoded YAML name and description must match the export.
  * The body is compared byte-for-byte after trimming surrounding whitespace.
@@ -2687,8 +2687,13 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.
+ *
+ * 0.55.4 adds `app.plugins.listServices()` under the new `plugins.read` claim: every auth service
+ * of the installed, enabled plugins, with the plugin's id and display name and whether the person
+ * has connected it. No account, identity or scope. Built-ins hold the claim; any other plugin needs
+ * a grant. Additive; plugins calling it declare ^0.55.4.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.55.3";
+declare const KAY_PLUGIN_SDK_VERSION: "0.55.4";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 

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

@@ -2741,8 +2741,13 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.
+ *
+ * 0.55.4 adds `app.plugins.listServices()` under the new `plugins.read` claim: every auth service
+ * of the installed, enabled plugins, with the plugin's id and display name and whether the person
+ * has connected it. No account, identity or scope. Built-ins hold the claim; any other plugin needs
+ * a grant. Additive; plugins calling it declare ^0.55.4.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.55.3";
+declare const KAY_PLUGIN_SDK_VERSION: "0.55.4";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 

package/dist/kay-agent.d.ts

@@ -3095,8 +3095,13 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.
+ *
+ * 0.55.4 adds `app.plugins.listServices()` under the new `plugins.read` claim: every auth service
+ * of the installed, enabled plugins, with the plugin's id and display name and whether the person
+ * has connected it. No account, identity or scope. Built-ins hold the claim; any other plugin needs
+ * a grant. Additive; plugins calling it declare ^0.55.4.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.55.3";
+declare const KAY_PLUGIN_SDK_VERSION: "0.55.4";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -5441,6 +5446,10 @@ declare const PluginCapabilityRefusalV1: z.ZodObject<{
         target: z.ZodLiteral<"kay.app">;
         slug: z.ZodLiteral<"plugins.set-enabled">;
         envelope: z.ZodObject<{}, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"kay.app">;
+        slug: z.ZodLiteral<"plugins.read">;
+        envelope: z.ZodObject<{}, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         target: z.ZodLiteral<"kay.app">;
         slug: z.ZodLiteral<"sessions.assign-project">;

package/dist/kay-app.d.ts

@@ -1045,7 +1045,7 @@ declare type AgentRuntimeSessionOutcomeConfidence = z.infer<typeof AgentRuntimeS
 
 /**
  * How a session's work is judged to have served the user (telemetry lane
- * PR 5, `docs/telemetry-lane-pr5-contracts.md` §2.1).
+ * PR 5, `docs/records/telemetry-lane-pr5-contracts.md` §2.1).
  *
  * `"unclear"` is a FIRST-CLASS verdict, not an error code: a judge that cannot
  * tell must say so rather than guess, and the share of `unclear` is itself a
@@ -4397,8 +4397,13 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.
+ *
+ * 0.55.4 adds `app.plugins.listServices()` under the new `plugins.read` claim: every auth service
+ * of the installed, enabled plugins, with the plugin's id and display name and whether the person
+ * has connected it. No account, identity or scope. Built-ins hold the claim; any other plugin needs
+ * a grant. Additive; plugins calling it declare ^0.55.4.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.55.3";
+declare const KAY_PLUGIN_SDK_VERSION: "0.55.4";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -6736,7 +6741,7 @@ export declare interface KayAppPluginApi {
      * in the daemon process and could walk the disk to find these directories anyway, so withholding
      * the path would buy friction rather than safety. It is not a containment boundary. Expect this
      * posture to tighten if plugin execution is ever isolated (deferred: D1 in
-     * `docs/plugins/trust-model-decisions.md`).
+     * `docs/decisions/2026-08-24-plugins-trust-model-decisions.md`).
      */
     readonly paths: KayAppPaths;
     /**
@@ -6912,9 +6917,11 @@ export declare interface KayAppPluginApi {
      */
     readonly soul?: KayAppSoul;
     /**
-     * Private API: only plugins Bonsai ships; refused for any other. Turns installed plugins on and
-     * off, each call checked against `plugins.set-enabled`. Absent when the host cannot change
-     * which plugins run.
+     * The installed plugins. `listServices()` answers each enabled plugin's auth services and whether
+     * each is connected, checked against `plugins.read`. `setEnabled()` is private API (only plugins
+     * Bonsai ships; refused for any other): it turns installed plugins on and off, checked against
+     * `plugins.set-enabled`. Absent when the host composed neither; a method the host did not
+     * compose rejects.
      */
     readonly plugins?: KayAppPlugins;
     /**
@@ -7002,16 +7009,14 @@ export declare interface KayAppPluginEvents {
 }
 
 /**
- * The `kay.app` plugins contract (`app.plugins`): the user's installed plugins.
- */
-/**
- * Private API: only plugins Bonsai ships; refused for any other. Each call is checked against
- * `plugins.set-enabled`. A refused call rejects with an `Error`.
+ * Each method is checked against its own claim at the call. A refused call rejects with an
+ * `Error`.
  */
 export declare interface KayAppPlugins {
     /**
-     * Turn an installed plugin on, which starts its code under the grants the user gave it, or off,
-     * which stops it. `changed` is false when it was already in that state.
+     * Private API: only plugins Bonsai ships; refused for any other. Checked against
+     * `plugins.set-enabled`. Turn an installed plugin on, which starts its code under the grants the
+     * user gave it, or off, which stops it. `changed` is false when it was already in that state.
      */
     setEnabled(request: {
         readonly pluginId: string;
@@ -7019,6 +7024,34 @@ export declare interface KayAppPlugins {
     }): Promise<{
         readonly changed: boolean;
     }>;
+    /**
+     * Checked against `plugins.read`. Every auth service of the installed, enabled plugins, one row
+     * per service, sorted by plugin name then service id. A plugin with no auth service is not
+     * listed. Never resolves, decrypts, refreshes or calls a provider.
+     */
+    listServices(): Promise<readonly KayAppPluginService[]>;
+}
+
+/**
+ * The `kay.app` plugins contract (`app.plugins`): the user's installed plugins.
+ */
+/**
+ * One auth service an installed, enabled plugin declares, and whether the person has connected
+ * it. Metadata only: no account, identity, scope or credential.
+ */
+export declare interface KayAppPluginService {
+    /** The plugin that declares the service: `com.kay.integration.ramp`. */
+    readonly pluginId: string;
+    /** The plugin's display name, as the person reads it: `Ramp`. */
+    readonly pluginName: string;
+    /** The service's global id, the one a connect card names: `ramp.account`. */
+    readonly serviceId: string;
+    /**
+     * True when any scheme of the service has a usable account. An account that needs reconnecting
+     * does not count, so a service with only such accounts reads as not connected. Not proof that a
+     * provider call will authenticate.
+     */
+    readonly connected: boolean;
 }
 
 export declare interface KayAppPollerEvent {

package/package.json

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

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

@@ -145,7 +145,7 @@ the plugin (`"./assets/rail.svg"`). Only its shape is used, painted in the rail'
 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. Full
-precedence: `packages/kay-frontend-sdk/ARCHITECTURE.md`, "Plugin icon".
+precedence: `packages/kay-renderer/src/renderer/src/shell/contribution-icons.ts`.
 
 `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`