@yaklabs-ai/plugin-sdk 0.28.0 → 0.30.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.30.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.30.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.30.0",
   "target": "npm",
   "firstPartyLicense": "MIT",
   "bundled": [

package/dist/disclosure.d.ts

@@ -249,6 +249,7 @@ declare namespace authoringCommonSchemas {
         hostWithinDomain,
         urlHostWithinDomain,
         refineWebSessionScopeConfined,
+        KAY_PLUGIN_MANIFEST_SIZE_CAP_BYTES,
         KAY_PLUGIN_PROTOCOL_VERSION,
         KAY_PLUGIN_PROTOCOL_PACKAGE_NAME,
         KAY_PLUGIN_SDK_VERSION,
@@ -1771,6 +1772,9 @@ declare const KAY_EVENT_PUBLISHER_ID: "kay";
 /** Released SDK contracts still implemented by the host, alongside its current SDK. */
 declare const KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS: readonly string[];
 
+/** Manifest byte cap, including declared app-data schemas; larger files are refused unread. */
+declare const KAY_PLUGIN_MANIFEST_SIZE_CAP_BYTES: number;
+
 declare const KAY_PLUGIN_PROTOCOL_PACKAGE_NAME: "@bonsai/plugin-protocol";
 
 declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
@@ -2341,8 +2345,20 @@ 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.
+ *
+ * 0.30.0 lets a scheduled workflow be described as data (#15722). `contributes.workflows` under
+ * `kay.app` declares its name, schedule and sign-in, and `app.implementWorkflow(localId, run)`
+ * supplies what a run does: each run is handed the workflow's accounts and tokens, so the code
+ * runs the same in the daemon and in the plugin host. Additive: `app.workflows.define` stays, and
+ * a plugin that declares a workflow declares ^0.30.0.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.28.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.30.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -2578,11 +2594,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 +3238,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

@@ -224,6 +224,7 @@ declare namespace authoringCommonSchemas {
         hostWithinDomain,
         urlHostWithinDomain,
         refineWebSessionScopeConfined,
+        KAY_PLUGIN_MANIFEST_SIZE_CAP_BYTES,
         KAY_PLUGIN_PROTOCOL_VERSION,
         KAY_PLUGIN_PROTOCOL_PACKAGE_NAME,
         KAY_PLUGIN_SDK_VERSION,
@@ -1825,6 +1826,9 @@ declare const KAY_EVENT_PUBLISHER_ID: "kay";
 /** Released SDK contracts still implemented by the host, alongside its current SDK. */
 declare const KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS: readonly string[];
 
+/** Manifest byte cap, including declared app-data schemas; larger files are refused unread. */
+declare const KAY_PLUGIN_MANIFEST_SIZE_CAP_BYTES: number;
+
 declare const KAY_PLUGIN_PROTOCOL_PACKAGE_NAME: "@bonsai/plugin-protocol";
 
 declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
@@ -2395,8 +2399,20 @@ 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.
+ *
+ * 0.30.0 lets a scheduled workflow be described as data (#15722). `contributes.workflows` under
+ * `kay.app` declares its name, schedule and sign-in, and `app.implementWorkflow(localId, run)`
+ * supplies what a run does: each run is handed the workflow's accounts and tokens, so the code
+ * runs the same in the daemon and in the plugin host. Additive: `app.workflows.define` stays, and
+ * a plugin that declares a workflow declares ^0.30.0.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.28.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.30.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -2629,11 +2645,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 +3289,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>;
 
@@ -4757,6 +4755,7 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
             appDataSource: "appDataSource";
             whiteboardType: "whiteboardType";
             approvalType: "approvalType";
+            workflow: "workflow";
             contextContributor: "contextContributor";
             transcriptionProvider: "transcriptionProvider";
             deviceDelegation: "deviceDelegation";
@@ -5528,6 +5527,18 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
         moduleId: z.ZodString;
         authService: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>>;
+    kayAppWorkflows: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        localId: z.ZodString;
+        globalId: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodString;
+        everyMs: z.ZodNumber;
+        auth: z.ZodOptional<z.ZodObject<{
+            serviceId: z.ZodString;
+            schemeId: z.ZodString;
+            scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>;
     kayAppDataSources: z.ZodOptional<z.ZodArray<z.ZodObject<{
         localId: z.ZodString;
         globalId: z.ZodString;

package/dist/kay-agent.d.ts

@@ -317,6 +317,7 @@ declare namespace authoringCommonSchemas {
         hostWithinDomain,
         urlHostWithinDomain,
         refineWebSessionScopeConfined,
+        KAY_PLUGIN_MANIFEST_SIZE_CAP_BYTES,
         KAY_PLUGIN_PROTOCOL_VERSION,
         KAY_PLUGIN_PROTOCOL_PACKAGE_NAME,
         KAY_PLUGIN_SDK_VERSION,
@@ -2100,6 +2101,9 @@ declare const KAY_EVENT_PUBLISHER_ID: "kay";
 /** Released SDK contracts still implemented by the host, alongside its current SDK. */
 declare const KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS: readonly string[];
 
+/** Manifest byte cap, including declared app-data schemas; larger files are refused unread. */
+declare const KAY_PLUGIN_MANIFEST_SIZE_CAP_BYTES: number;
+
 declare const KAY_PLUGIN_PROTOCOL_PACKAGE_NAME: "@bonsai/plugin-protocol";
 
 declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
@@ -2670,8 +2674,20 @@ 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.
+ *
+ * 0.30.0 lets a scheduled workflow be described as data (#15722). `contributes.workflows` under
+ * `kay.app` declares its name, schedule and sign-in, and `app.implementWorkflow(localId, run)`
+ * supplies what a run does: each run is handed the workflow's accounts and tokens, so the code
+ * runs the same in the daemon and in the plugin host. Additive: `app.workflows.define` stays, and
+ * a plugin that declares a workflow declares ^0.30.0.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.28.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.30.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -2936,11 +2952,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 +3615,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. */
@@ -4344,8 +4358,8 @@ export declare interface OsascriptFailureAdvice {
 }
 
 /**
- * The activation options every osascript plugin's agent factory accepted, so the daemon's
- * simulator roster set each the same way. Absent `simulator`, the plugin is exactly the shipped one.
+ * The activation options every osascript plugin's agent factory accepted, each with the same
+ * `simulator` option. Absent `simulator`, the plugin is exactly the shipped one.
  *
  * @deprecated See {@link OsascriptSimulatorOptions}.
  */
@@ -4384,10 +4398,6 @@ export declare interface OsascriptRunner {
     /**
      * The runners a module's verbs use: the host's exactly when `simulator` is absent, or the
      * simulator's in its place, per dispatch, after the host's connection gate.
-     *
-     * @deprecated A Bonsai daemon substitutes the runner itself, so a module uses
-     * {@link requireExternalCli} and `ctx.auth?.externalCli` directly. Kept so a plugin built against
-     * an earlier SDK keeps compiling.
      */
     readonly dispatch: (simulator: OsascriptSimulatedRunner | undefined) => OsascriptDispatch;
     /**
@@ -4434,25 +4444,22 @@ export declare interface OsascriptRunnerOptions {
 }
 
 /**
- * A simulated runner, as a module sees it: the runner one dispatch uses in the host's place. A
- * Bonsai daemon that simulates an osascript plugin hands `runnerFor(ctx)` to the module as
- * `ctx.auth.externalCli`; `@bonsai/uri-simulator-kit/osascript` builds one.
+ * A simulated runner, as a module sees it: the runner one dispatch uses in the host's place. An
+ * osascript plugin's simulator holds one (`@bonsai/uri-simulator-kit/osascript` builds it), and the
+ * module passes it to {@link OsascriptRunner.dispatch}.
  */
 export declare interface OsascriptSimulatedRunner {
     readonly runnerFor: (ctx: UriResolveContext) => UriExternalCliRunner;
 }
 
 /**
- * How a plugin is told to serve its module from its simulator instead of osascript: the one
- * option shape every osascript plugin's agent factory accepts as `simulator`. Only the daemon's
- * URI simulator roster sets it, for evals and dev; an ordinary install never does.
+ * How a plugin was once told to serve its module from its simulator instead of osascript.
  *
- * @deprecated A Bonsai daemon now hands the module a simulated runner as `ctx.auth.externalCli`,
- * so a plugin needs no simulator option; no Bonsai plugin sets this. Kept so a plugin built against
- * an earlier SDK keeps compiling.
+ * @deprecated A plugin gets its simulator as `api.simulator`; no Bonsai plugin sets this. Kept so a
+ * plugin built against an earlier SDK keeps compiling.
  */
 export declare interface OsascriptSimulatorOptions {
-    /** The directory holding the simulator's world; the daemon's process config names it. */
+    /** The directory holding the simulator's world. */
     readonly stateDir: string;
 }
 

package/dist/kay-app.d.ts

@@ -266,6 +266,7 @@ declare namespace authoringCommonSchemas {
         hostWithinDomain,
         urlHostWithinDomain,
         refineWebSessionScopeConfined,
+        KAY_PLUGIN_MANIFEST_SIZE_CAP_BYTES,
         KAY_PLUGIN_PROTOCOL_VERSION,
         KAY_PLUGIN_PROTOCOL_PACKAGE_NAME,
         KAY_PLUGIN_SDK_VERSION,
@@ -2057,6 +2058,9 @@ declare const KAY_EVENT_PUBLISHER_ID: "kay";
 /** Released SDK contracts still implemented by the host, alongside its current SDK. */
 declare const KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS: readonly string[];
 
+/** Manifest byte cap, including declared app-data schemas; larger files are refused unread. */
+declare const KAY_PLUGIN_MANIFEST_SIZE_CAP_BYTES: number;
+
 declare const KAY_PLUGIN_PROTOCOL_PACKAGE_NAME: "@bonsai/plugin-protocol";
 
 declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
@@ -2627,8 +2631,20 @@ 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.
+ *
+ * 0.30.0 lets a scheduled workflow be described as data (#15722). `contributes.workflows` under
+ * `kay.app` declares its name, schedule and sign-in, and `app.implementWorkflow(localId, run)`
+ * supplies what a run does: each run is handed the workflow's accounts and tokens, so the code
+ * runs the same in the daemon and in the plugin host. Additive: `app.workflows.define` stays, and
+ * a plugin that declares a workflow declares ^0.30.0.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.28.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.30.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -5153,13 +5169,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
@@ -5272,6 +5286,14 @@ export declare interface KayAppPluginApi {
      * fail-closed at activation, exactly like {@link registerUriModule}.
      */
     registerTool(localId: string, definition: KayAppToolDefinition): void;
+    /**
+     * Supply the code of a workflow this plugin's manifest declares under
+     * `targets.kay.app.contributes.workflows` (SDK 0.30.0). The manifest says its name, schedule and
+     * sign-in, so Bonsai schedules it without this code running; each run is handed its accounts and
+     * tokens, so it runs the same wherever the plugin runs. Implementing an undeclared `localId`, or
+     * declaring one this activation does not implement, fails the plugin.
+     */
+    implementWorkflow(localId: string, run: KayAppWorkflowImplementation): void;
 }
 
 export declare interface KayAppPluginEvents {
@@ -8028,6 +8050,16 @@ export declare interface KayAppWhiteboardTypes {
     registerType(localId: string, behavior: KayAppWhiteboardTypeBehavior): void;
 }
 
+/**
+ * One connected account of a declared workflow's service, and its credential for this run. An
+ * account that needs signing in again, or holds none of the declared scopes, arrives with that
+ * status instead of a token.
+ */
+export declare interface KayAppWorkflowAccount {
+    readonly account: KayAppAccountSummary;
+    readonly credential: KayAppBackgroundCredentialResult;
+}
+
 /**
  * What your `run` callback is handed when the trigger fires.
  *
@@ -8141,16 +8173,7 @@ export declare interface KayAppWorkflowDefinition<Trigger extends KayAppWorkflow
      * suits an event trigger whose runs each handle their own event; it cannot return `state`.
      */
     readonly concurrency?: KayAppAutomationConcurrency;
-    readonly run: (context: KayAppWorkflowContext<Trigger>) => Promise<{
-        /**
-         * Replacement JSON state, at most 64 KiB; omission keeps the previous value. Only a
-         * sequential workflow may return it: a `parallel` run that does fails.
-         */
-        readonly state?: JsonValue | undefined;
-        readonly summary: KayAppRunSummary;
-        readonly produced?: KayAppRunProduced;
-        readonly effect?: KayAppRunEffect;
-    }>;
+    readonly run: (context: KayAppWorkflowContext<Trigger>) => Promise<KayAppWorkflowResult>;
 }
 
 /**
@@ -8169,6 +8192,9 @@ export declare class KayAppWorkflowFailure extends Error {
     constructor(summary: Omit<KayAppRunSummary, "author">, options?: ErrorOptions);
 }
 
+/** The code of a workflow the manifest declares under `contributes.workflows`. */
+export declare type KayAppWorkflowImplementation = (run: KayAppWorkflowRun) => Promise<KayAppWorkflowResult>;
+
 export declare interface KayAppWorkflowInspection {
     readonly binding: KayAppManagedAutomation | null;
     readonly runs: readonly KayAppAutomationRun[];
@@ -8210,6 +8236,42 @@ export declare type KayAppWorkflowMatch<Trigger extends KayAppWorkflowTrigger =
     readonly kind: "time";
 }>);
 
+/** What a workflow run returns. */
+export declare interface KayAppWorkflowResult {
+    /**
+     * Replacement JSON state, at most 64 KiB; omission keeps the previous value. Only a
+     * sequential workflow may return it: a `parallel` run that does fails.
+     */
+    readonly state?: JsonValue | undefined;
+    readonly summary: KayAppRunSummary;
+    readonly produced?: KayAppRunProduced;
+    readonly effect?: KayAppRunEffect;
+}
+
+/**
+ * What a declared workflow's code is handed each run (`app.implementWorkflow`).
+ *
+ * The whole run is one recorded step, so an interrupted run starts again from the last saved
+ * `state`: it may repeat provider reads and published events, so key events at their source.
+ */
+export declare interface KayAppWorkflowRun {
+    /** State from the last successful run; undefined until a run saves it. */
+    readonly state: JsonValue | undefined;
+    readonly runId: string;
+    /**
+     * Every connected account of the service and scheme the manifest's `auth` names, in a stable
+     * order. Empty when it names none.
+     */
+    readonly accounts: readonly KayAppWorkflowAccount[];
+    /**
+     * Just runs `fn`, and returns once every event it published has reached Bonsai. Nothing is
+     * recorded for now, so a repeated run runs it again. What it returns must be plain data.
+     */
+    readonly runStep: <T>(fn: () => Promise<T>, options?: {
+        readonly name?: string;
+    }) => Promise<T>;
+}
+
 export declare interface KayAppWorkflows {
     define<Trigger extends KayAppWorkflowTrigger>(localId: string, definition: KayAppWorkflowDefinition<Trigger>): void;
     inspect(localId: string, options?: KayAppWorkflowInspectOptions): Promise<KayAppWorkflowInspection>;
@@ -8535,21 +8597,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/dist/whiteboard.js

@@ -26,6 +26,7 @@ var JsonObject = z2.record(z2.string(), JsonValue);
 var JsonSchema = z2.record(z2.string(), JsonValue);
 
 // packages/plugin-protocol/dist/common.js
+var KAY_PLUGIN_MANIFEST_SIZE_CAP_BYTES = 1024 * 1024;
 var KAY_PLUGIN_PROTOCOL_VERSION = "kay.plugin.v1";
 var KAY_PLUGIN_TARGET_NAMES = [
   "kay.agent",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaklabs-ai/plugin-sdk",
-  "version": "0.28.0",
+  "version": "0.30.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"