@yaklabs-ai/plugin-sdk 0.28.0 → 0.29.0

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.28.0"
+    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.29.0"
   }
 }
 ```
@@ -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.28.0" },
+  "compatibility": { "sdk": "^0.29.0" },
   "targets": {
     "kay": {
       "agent": {

package/THIRD-PARTY-INVENTORY.json

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

package/dist/disclosure.d.ts

@@ -2341,8 +2341,14 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * host holds may name one too. A plugin using a removed member or value stops loading until it is
  * rebuilt; a code search found none outside this repo. A plugin with a sign-in declares ^0.28.0. 0.26.3 and 0.27.1
  * stay served for a plugin that uses none of these.
+ *
+ * 0.29.0 replaces `servedSimulators` (`KayServedSimulators`, a lookup by adapter id) with
+ * `simulator` on both targets (#14929): what the plugin's own simulator built, handed over once by
+ * whichever process runs the plugin. A plugin's simulator file exports `createPluginSimulator`
+ * (`KayPluginSimulatorFactory`). A clean break: only this repo's plugins read the old member, and
+ * a plugin with no simulator is unaffected, so 0.28.0 stays served.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.28.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.29.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -2578,11 +2584,11 @@ declare interface KayAgentPluginApi {
     /** Absent unless the `knownResources` grant is requested and effectively granted. */
     readonly knownResources?: KayAgentKnownResources;
     /**
-     * Optional: absent unless a simulating Bonsai daemon serves this plugin a simulator (SDK 0.18.1).
-     * A production daemon never does. In this version only plugins the release carries are served;
-     * any plugin may ship a `./simulator` later. See {@link KayServedSimulators}.
+     * What this plugin's own simulator built, in a simulated run only (SDK 0.29.0): absent in every
+     * other, so treat absence as the normal case. Use it in place of the real backend; its shape is
+     * the plugin's own, so narrow it before use. See {@link KayPluginSimulatorFactory}.
      */
-    readonly servedSimulators?: KayServedSimulators;
+    readonly simulator?: unknown;
     /**
      * Present when the host composes Whiteboard. Each operation is checked against its exact
      * `whiteboard.<operation> {scope}` claim; handle presence is not consent.
@@ -3222,24 +3228,6 @@ declare const KayPluginProtocolVersion: z.ZodLiteral<"kay.plugin.v1">;
 
 declare type KayPluginProtocolVersion = z.infer<typeof KayPluginProtocolVersion>;
 
-/**
- * The simulators a simulating Bonsai daemon (evals, dev, tests) serves this plugin, keyed by the
- * adapter id its simulated URI connection rows name. The daemon builds each from the plugin's own
- * dev-only `./simulator` subpath; the plugin never imports its simulator.
- *
- * The member that carries this, `servedSimulators` on both plugin APIs, is optional and absent
- * unless a simulating daemon serves it. A production daemon never does, so treat absence as the
- * normal case. In this version the daemon serves it only to plugins the release carries; the seam
- * is not specific to them, and any plugin may ship a `./simulator` later.
- */
-declare interface KayServedSimulators {
-    /**
-     * What this plugin's simulator built for `adapterId`, or `undefined` when none was served for
-     * that id. The shape is the plugin's own simulator contract; narrow it before use.
-     */
-    get(adapterId: string): unknown;
-}
-
 /** Applies a KeyOf action to the given type. */
 declare function KeyOf<Type extends TSchema>(type: Type, options?: TSchemaOptions): TKeyOf_2<Type>;
 

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

@@ -2395,8 +2395,14 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * host holds may name one too. A plugin using a removed member or value stops loading until it is
  * rebuilt; a code search found none outside this repo. A plugin with a sign-in declares ^0.28.0. 0.26.3 and 0.27.1
  * stay served for a plugin that uses none of these.
+ *
+ * 0.29.0 replaces `servedSimulators` (`KayServedSimulators`, a lookup by adapter id) with
+ * `simulator` on both targets (#14929): what the plugin's own simulator built, handed over once by
+ * whichever process runs the plugin. A plugin's simulator file exports `createPluginSimulator`
+ * (`KayPluginSimulatorFactory`). A clean break: only this repo's plugins read the old member, and
+ * a plugin with no simulator is unaffected, so 0.28.0 stays served.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.28.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.29.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -2629,11 +2635,11 @@ declare interface KayAgentPluginApi {
     /** Absent unless the `knownResources` grant is requested and effectively granted. */
     readonly knownResources?: KayAgentKnownResources;
     /**
-     * Optional: absent unless a simulating Bonsai daemon serves this plugin a simulator (SDK 0.18.1).
-     * A production daemon never does. In this version only plugins the release carries are served;
-     * any plugin may ship a `./simulator` later. See {@link KayServedSimulators}.
+     * What this plugin's own simulator built, in a simulated run only (SDK 0.29.0): absent in every
+     * other, so treat absence as the normal case. Use it in place of the real backend; its shape is
+     * the plugin's own, so narrow it before use. See {@link KayPluginSimulatorFactory}.
      */
-    readonly servedSimulators?: KayServedSimulators;
+    readonly simulator?: unknown;
     /**
      * Present when the host composes Whiteboard. Each operation is checked against its exact
      * `whiteboard.<operation> {scope}` claim; handle presence is not consent.
@@ -3273,24 +3279,6 @@ declare const KayPluginProtocolVersion: z.ZodLiteral<"kay.plugin.v1">;
 
 declare type KayPluginProtocolVersion = z.infer<typeof KayPluginProtocolVersion>;
 
-/**
- * The simulators a simulating Bonsai daemon (evals, dev, tests) serves this plugin, keyed by the
- * adapter id its simulated URI connection rows name. The daemon builds each from the plugin's own
- * dev-only `./simulator` subpath; the plugin never imports its simulator.
- *
- * The member that carries this, `servedSimulators` on both plugin APIs, is optional and absent
- * unless a simulating daemon serves it. A production daemon never does, so treat absence as the
- * normal case. In this version the daemon serves it only to plugins the release carries; the seam
- * is not specific to them, and any plugin may ship a `./simulator` later.
- */
-declare interface KayServedSimulators {
-    /**
-     * What this plugin's simulator built for `adapterId`, or `undefined` when none was served for
-     * that id. The shape is the plugin's own simulator contract; narrow it before use.
-     */
-    get(adapterId: string): unknown;
-}
-
 /** Applies a KeyOf action to the given type. */
 declare function KeyOf<Type extends TSchema>(type: Type, options?: TSchemaOptions): TKeyOf_2<Type>;
 

package/dist/kay-agent.d.ts

@@ -2670,8 +2670,14 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * host holds may name one too. A plugin using a removed member or value stops loading until it is
  * rebuilt; a code search found none outside this repo. A plugin with a sign-in declares ^0.28.0. 0.26.3 and 0.27.1
  * stay served for a plugin that uses none of these.
+ *
+ * 0.29.0 replaces `servedSimulators` (`KayServedSimulators`, a lookup by adapter id) with
+ * `simulator` on both targets (#14929): what the plugin's own simulator built, handed over once by
+ * whichever process runs the plugin. A plugin's simulator file exports `createPluginSimulator`
+ * (`KayPluginSimulatorFactory`). A clean break: only this repo's plugins read the old member, and
+ * a plugin with no simulator is unaffected, so 0.28.0 stays served.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.28.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.29.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -2936,11 +2942,11 @@ export declare interface KayAgentPluginApi {
     /** Absent unless the `knownResources` grant is requested and effectively granted. */
     readonly knownResources?: KayAgentKnownResources;
     /**
-     * Optional: absent unless a simulating Bonsai daemon serves this plugin a simulator (SDK 0.18.1).
-     * A production daemon never does. In this version only plugins the release carries are served;
-     * any plugin may ship a `./simulator` later. See {@link KayServedSimulators}.
+     * What this plugin's own simulator built, in a simulated run only (SDK 0.29.0): absent in every
+     * other, so treat absence as the normal case. Use it in place of the real backend; its shape is
+     * the plugin's own, so narrow it before use. See {@link KayPluginSimulatorFactory}.
      */
-    readonly servedSimulators?: KayServedSimulators;
+    readonly simulator?: unknown;
     /**
      * Present when the host composes Whiteboard. Each operation is checked against its exact
      * `whiteboard.<operation> {scope}` claim; handle presence is not consent.
@@ -3599,21 +3605,19 @@ declare const KayPluginProtocolVersion: z.ZodLiteral<"kay.plugin.v1">;
 declare type KayPluginProtocolVersion = z.infer<typeof KayPluginProtocolVersion>;
 
 /**
- * The simulators a simulating Bonsai daemon (evals, dev, tests) serves this plugin, keyed by the
- * adapter id its simulated URI connection rows name. The daemon builds each from the plugin's own
- * dev-only `./simulator` subpath; the plugin never imports its simulator.
- *
- * The member that carries this, `servedSimulators` on both plugin APIs, is optional and absent
- * unless a simulating daemon serves it. A production daemon never does, so treat absence as the
- * normal case. In this version the daemon serves it only to plugins the release carries; the seam
- * is not specific to them, and any plugin may ship a `./simulator` later.
+ * What a plugin's dev-only simulator file exports as `createPluginSimulator`. Whichever process
+ * runs the plugin calls it once and hands the result to that plugin alone, as `simulator` on both
+ * plugin APIs. The result's shape is the plugin's own: nothing between the two reads it, and the
+ * plugin never imports its simulator.
  */
-export declare interface KayServedSimulators {
-    /**
-     * What this plugin's simulator built for `adapterId`, or `undefined` when none was served for
-     * that id. The shape is the plugin's own simulator contract; narrow it before use.
-     */
-    get(adapterId: string): unknown;
+export declare type KayPluginSimulatorFactory = (options: KayPluginSimulatorOptions) => unknown;
+
+/**
+ * What the launcher of a simulated run (evals, dev, tests) gives a plugin's simulator: the folder
+ * its worlds live under. The simulator picks its own folders inside it.
+ */
+export declare interface KayPluginSimulatorOptions {
+    readonly stateRoot: string;
 }
 
 /** Applies a KeyOf action to the given type. */

package/dist/kay-app.d.ts

@@ -2627,8 +2627,14 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * host holds may name one too. A plugin using a removed member or value stops loading until it is
  * rebuilt; a code search found none outside this repo. A plugin with a sign-in declares ^0.28.0. 0.26.3 and 0.27.1
  * stay served for a plugin that uses none of these.
+ *
+ * 0.29.0 replaces `servedSimulators` (`KayServedSimulators`, a lookup by adapter id) with
+ * `simulator` on both targets (#14929): what the plugin's own simulator built, handed over once by
+ * whichever process runs the plugin. A plugin's simulator file exports `createPluginSimulator`
+ * (`KayPluginSimulatorFactory`). A clean break: only this repo's plugins read the old member, and
+ * a plugin with no simulator is unaffected, so 0.28.0 stays served.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.28.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.29.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -5153,13 +5159,11 @@ export declare interface KayAppPluginApi {
     /** Exact-account credential resolution for declared background-job purposes. */
     readonly backgroundAuth?: KayAppBackgroundAuth;
     /**
-     * Optional: absent unless a simulating Bonsai daemon serves this plugin a simulator (SDK 0.18.1).
-     * A production daemon never does. In this version only plugins the release carries are served;
-     * any plugin may ship a `./simulator` later. The `kay.app` target reads the same simulators its
-     * `kay.agent` part does, so a background job runs on the simulator its URI target does. See
-     * {@link KayServedSimulators}.
+     * What this plugin's own simulator built, in a simulated run only (SDK 0.29.0): absent in every
+     * other. Its shape is the plugin's own, so narrow it before use. See
+     * {@link KayPluginSimulatorFactory}.
      */
-    readonly servedSimulators?: KayServedSimulators;
+    readonly simulator?: unknown;
     /**
      * Read and write this plugin's OWN manifest-declared config sections (value + provenance), and
      * observe changes. Present whenever the host has a config store and the plugin declares at least
@@ -8535,21 +8539,19 @@ declare const KayPluginProtocolVersion: z.ZodLiteral<"kay.plugin.v1">;
 declare type KayPluginProtocolVersion = z.infer<typeof KayPluginProtocolVersion>;
 
 /**
- * The simulators a simulating Bonsai daemon (evals, dev, tests) serves this plugin, keyed by the
- * adapter id its simulated URI connection rows name. The daemon builds each from the plugin's own
- * dev-only `./simulator` subpath; the plugin never imports its simulator.
- *
- * The member that carries this, `servedSimulators` on both plugin APIs, is optional and absent
- * unless a simulating daemon serves it. A production daemon never does, so treat absence as the
- * normal case. In this version the daemon serves it only to plugins the release carries; the seam
- * is not specific to them, and any plugin may ship a `./simulator` later.
+ * What a plugin's dev-only simulator file exports as `createPluginSimulator`. Whichever process
+ * runs the plugin calls it once and hands the result to that plugin alone, as `simulator` on both
+ * plugin APIs. The result's shape is the plugin's own: nothing between the two reads it, and the
+ * plugin never imports its simulator.
  */
-export declare interface KayServedSimulators {
-    /**
-     * What this plugin's simulator built for `adapterId`, or `undefined` when none was served for
-     * that id. The shape is the plugin's own simulator contract; narrow it before use.
-     */
-    get(adapterId: string): unknown;
+export declare type KayPluginSimulatorFactory = (options: KayPluginSimulatorOptions) => unknown;
+
+/**
+ * What the launcher of a simulated run (evals, dev, tests) gives a plugin's simulator: the folder
+ * its worlds live under. The simulator picks its own folders inside it.
+ */
+export declare interface KayPluginSimulatorOptions {
+    readonly stateRoot: string;
 }
 
 /** Applies a KeyOf action to the given type. */

package/dist/skills.d.ts

@@ -0,0 +1,4 @@
+/** Normalize underscores to hyphens; return undefined unless the result is a valid Agent Skills name (at most 64 characters). */
+export declare function skillInstallTargetName(sourceName: string): string | undefined;
+
+export { }

package/dist/skills.js

@@ -0,0 +1,12 @@
+// packages/plugin-sdk/dist/skills.js
+var AGENT_SKILL_NAME_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+function skillInstallTargetName(sourceName) {
+  const targetName = sourceName.replace(/_+/g, "-");
+  if (targetName.length > 64 || targetName.includes("--") || !AGENT_SKILL_NAME_PATTERN.test(targetName)) {
+    return void 0;
+  }
+  return targetName;
+}
+export {
+  skillInstallTargetName
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaklabs-ai/plugin-sdk",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "The Kay plugin SDK — types and helpers for authoring a Kay directory plugin.",
   "author": "YakLabs",
   "type": "module",
@@ -61,6 +61,10 @@
       "types": "./dist/whiteboard.d.ts",
       "default": "./dist/whiteboard.js"
     },
+    "./skills": {
+      "types": "./dist/skills.d.ts",
+      "default": "./dist/skills.js"
+    },
     "./transcript-review": {
       "types": "./dist/transcript-review.d.ts",
       "default": "./dist/transcript-review.js"