@yaklabs-ai/plugin-sdk 0.29.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.29.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.29.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.29.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";
@@ -2347,8 +2351,14 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.29.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.30.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 

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";
@@ -2401,8 +2405,14 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.29.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.30.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -4745,6 +4755,7 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
             appDataSource: "appDataSource";
             whiteboardType: "whiteboardType";
             approvalType: "approvalType";
+            workflow: "workflow";
             contextContributor: "contextContributor";
             transcriptionProvider: "transcriptionProvider";
             deviceDelegation: "deviceDelegation";
@@ -5516,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";
@@ -2676,8 +2680,14 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.29.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.30.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -4348,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}.
  */
@@ -4388,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;
     /**
@@ -4438,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";
@@ -2633,8 +2637,14 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.29.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.30.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -5276,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 {
@@ -8032,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.
  *
@@ -8145,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>;
 }
 
 /**
@@ -8173,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[];
@@ -8214,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>;

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