@yaklabs-ai/plugin-sdk 0.29.0 → 0.31.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.31.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.31.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.31.0",
   "target": "npm",
   "firstPartyLicense": "MIT",
   "bundled": [

package/dist/canonical-transcript.d.ts

@@ -1722,39 +1722,48 @@ declare type GrammarVariants = Partial<Record<GrammarFormat, string>>;
  */
 declare type HerdHarnessEvent = {
     readonly type: "agent_start";
+    readonly kernelRunId?: string;
 } | {
     readonly type: "agent_end";
     readonly messages: readonly AgentMessage[];
 } | {
     readonly type: "turn_start";
+    readonly kernelRunId?: string;
 } | {
     readonly type: "turn_end";
+    readonly kernelRunId?: string;
     readonly message: AssistantMessage;
     readonly toolResults: readonly ToolResultMessage[];
 } | {
     readonly type: "message_start";
+    readonly kernelRunId?: string;
     readonly message: AgentMessage;
 } | {
     readonly type: "message_update";
+    readonly kernelRunId?: string;
     readonly message: AgentMessage;
     readonly assistantMessageEvent: AssistantMessageEvent;
 } | {
     readonly type: "message_end";
+    readonly kernelRunId?: string;
     readonly message: AgentMessage;
     readonly entryId?: string;
 } | {
     readonly type: "tool_execution_start";
+    readonly kernelRunId?: string;
     readonly toolCallId: string;
     readonly toolName: string;
     readonly args: unknown;
 } | {
     readonly type: "tool_execution_update";
+    readonly kernelRunId?: string;
     readonly toolCallId: string;
     readonly toolName: string;
     readonly args: unknown;
     readonly partialResult: unknown;
 } | {
     readonly type: "tool_execution_end";
+    readonly kernelRunId?: string;
     readonly toolCallId: string;
     readonly toolName: string;
     readonly result: unknown;

package/dist/canonical-transcript.js

@@ -396,7 +396,7 @@ var boundedDeltaPlacement = z4.json().refine((delta) => {
 var HerdSessionProjection = z4.discriminatedUnion("type", [
   z4.strictObject({
     type: z4.literal("herd.message.delta"),
-    runId: z4.string().min(1).optional(),
+    kernelRunId: z4.string().min(1).optional(),
     messageId: z4.string().min(1).optional(),
     timestamp: z4.iso.datetime(),
     delta: boundedDeltaPlacement
@@ -671,7 +671,17 @@ var TOOL_CALL_FAILURE_CODES = [
   "edit.text_not_unique",
   "edit.empty_old_text",
   "edit.overlapping_edits",
-  "edit.no_change"
+  "edit.no_change",
+  // Situation codes for two lumped codes above. Each reads exactly as its
+  // parent (same category, retryable and action); the parent stays for every
+  // case without the evidence. An app older than these codes rejects a stored
+  // record that carries one.
+  "uri.not_connected.pick_account",
+  "uri.not_connected.account_not_allowed",
+  "uri.not_connected.sign_in_expired",
+  "tool.blocked.by_user",
+  "tool.blocked.by_rule",
+  "tool.blocked.by_bonsai"
 ];
 var count = z5.number().int().nonnegative();
 var toolCallFailureDetailsSchema = z5.strictObject({

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,19 @@ 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.
+ *
+ * 0.31.0 lets a plugin declare its rail entries as data (#15896). `railEntries` under `kay.ui`
+ * `contributes` names each entry's title, page, shortcut and icon file. It replaces `activityRail` on a
+ * UI app, which is stripped from a manifest that still carries it, so that manifest loses only the
+ * rail button. A plugin that declares a rail entry declares ^0.31.0.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.29.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.31.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -7601,7 +7616,7 @@ declare type TOmitInstantiate<Context extends TProperties, State extends TState,
  * classification (the engine records the rejection on an unexplained failure),
  * and a stored record with one reads as none.
  */
-declare const TOOL_CALL_FAILURE_CODES: readonly ["tool.invalid_input", "tool.blocked", "tool.cancelled", "tool.timeout", "tool.not_found", "tool.unavailable", "tool.execution_failed", "tool.auth_unavailable", "tool.replies_owed", "provider.http", "provider.api", "provider.transport", "uri.not_found", "uri.unsupported_operation", "uri.not_connected", "uri.auth_unavailable", "permission.denied", "edit.empty_edits", "edit.text_not_found", "edit.text_not_unique", "edit.empty_old_text", "edit.overlapping_edits", "edit.no_change"];
+declare const TOOL_CALL_FAILURE_CODES: readonly ["tool.invalid_input", "tool.blocked", "tool.cancelled", "tool.timeout", "tool.not_found", "tool.unavailable", "tool.execution_failed", "tool.auth_unavailable", "tool.replies_owed", "provider.http", "provider.api", "provider.transport", "uri.not_found", "uri.unsupported_operation", "uri.not_connected", "uri.auth_unavailable", "permission.denied", "edit.empty_edits", "edit.text_not_found", "edit.text_not_unique", "edit.empty_old_text", "edit.overlapping_edits", "edit.no_change", "uri.not_connected.pick_account", "uri.not_connected.account_not_allowed", "uri.not_connected.sign_in_expired", "tool.blocked.by_user", "tool.blocked.by_rule", "tool.blocked.by_bonsai"];
 
 /**
  * ---

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,19 @@ 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.
+ *
+ * 0.31.0 lets a plugin declare its rail entries as data (#15896). `railEntries` under `kay.ui`
+ * `contributes` names each entry's title, page, shortcut and icon file. It replaces `activityRail` on a
+ * UI app, which is stripped from a manifest that still carries it, so that manifest loses only the
+ * rail button. A plugin that declares a rail entry declares ^0.31.0.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.29.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.31.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -4745,6 +4760,7 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
             appDataSource: "appDataSource";
             whiteboardType: "whiteboardType";
             approvalType: "approvalType";
+            workflow: "workflow";
             contextContributor: "contextContributor";
             transcriptionProvider: "transcriptionProvider";
             deviceDelegation: "deviceDelegation";
@@ -5516,6 +5532,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;
@@ -5631,16 +5659,6 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
         globalId: z.ZodString;
         displayName: z.ZodString;
         contextOnly: z.ZodOptional<z.ZodLiteral<true>>;
-        activityRail: z.ZodOptional<z.ZodObject<{
-            section: z.ZodOptional<z.ZodEnum<{
-                primary: "primary";
-                plugins: "plugins";
-            }>>;
-            order: z.ZodOptional<z.ZodNumber>;
-            icon: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
-                svg: z.ZodString;
-            }, z.core.$strict>]>>;
-        }, z.core.$strict>>;
         description: z.ZodOptional<z.ZodString>;
         icon: z.ZodOptional<z.ZodString>;
         runtime: z.ZodLiteral<"kay.react-app.v1">;
@@ -8664,7 +8682,7 @@ declare type TOmitInstantiate<Context extends TProperties, State extends TState,
  * classification (the engine records the rejection on an unexplained failure),
  * and a stored record with one reads as none.
  */
-declare const TOOL_CALL_FAILURE_CODES: readonly ["tool.invalid_input", "tool.blocked", "tool.cancelled", "tool.timeout", "tool.not_found", "tool.unavailable", "tool.execution_failed", "tool.auth_unavailable", "tool.replies_owed", "provider.http", "provider.api", "provider.transport", "uri.not_found", "uri.unsupported_operation", "uri.not_connected", "uri.auth_unavailable", "permission.denied", "edit.empty_edits", "edit.text_not_found", "edit.text_not_unique", "edit.empty_old_text", "edit.overlapping_edits", "edit.no_change"];
+declare const TOOL_CALL_FAILURE_CODES: readonly ["tool.invalid_input", "tool.blocked", "tool.cancelled", "tool.timeout", "tool.not_found", "tool.unavailable", "tool.execution_failed", "tool.auth_unavailable", "tool.replies_owed", "provider.http", "provider.api", "provider.transport", "uri.not_found", "uri.unsupported_operation", "uri.not_connected", "uri.auth_unavailable", "permission.denied", "edit.empty_edits", "edit.text_not_found", "edit.text_not_unique", "edit.empty_old_text", "edit.overlapping_edits", "edit.no_change", "uri.not_connected.pick_account", "uri.not_connected.account_not_allowed", "uri.not_connected.sign_in_expired", "tool.blocked.by_user", "tool.blocked.by_rule", "tool.blocked.by_bonsai"];
 
 /**
  * ---

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,19 @@ 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.
+ *
+ * 0.31.0 lets a plugin declare its rail entries as data (#15896). `railEntries` under `kay.ui`
+ * `contributes` names each entry's title, page, shortcut and icon file. It replaces `activityRail` on a
+ * UI app, which is stripped from a manifest that still carries it, so that manifest loses only the
+ * rail button. A plugin that declares a rail entry declares ^0.31.0.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.29.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.31.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -4348,8 +4363,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 +4403,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 +4449,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;
 }
 
@@ -8819,7 +8827,7 @@ declare type TOmitInstantiate<Context extends TProperties, State extends TState,
  * classification (the engine records the rejection on an unexplained failure),
  * and a stored record with one reads as none.
  */
-declare const TOOL_CALL_FAILURE_CODES: readonly ["tool.invalid_input", "tool.blocked", "tool.cancelled", "tool.timeout", "tool.not_found", "tool.unavailable", "tool.execution_failed", "tool.auth_unavailable", "tool.replies_owed", "provider.http", "provider.api", "provider.transport", "uri.not_found", "uri.unsupported_operation", "uri.not_connected", "uri.auth_unavailable", "permission.denied", "edit.empty_edits", "edit.text_not_found", "edit.text_not_unique", "edit.empty_old_text", "edit.overlapping_edits", "edit.no_change"];
+declare const TOOL_CALL_FAILURE_CODES: readonly ["tool.invalid_input", "tool.blocked", "tool.cancelled", "tool.timeout", "tool.not_found", "tool.unavailable", "tool.execution_failed", "tool.auth_unavailable", "tool.replies_owed", "provider.http", "provider.api", "provider.transport", "uri.not_found", "uri.unsupported_operation", "uri.not_connected", "uri.auth_unavailable", "permission.denied", "edit.empty_edits", "edit.text_not_found", "edit.text_not_unique", "edit.empty_old_text", "edit.overlapping_edits", "edit.no_change", "uri.not_connected.pick_account", "uri.not_connected.account_not_allowed", "uri.not_connected.sign_in_expired", "tool.blocked.by_user", "tool.blocked.by_rule", "tool.blocked.by_bonsai"];
 
 /**
  * ---

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,
@@ -1055,18 +1056,16 @@ declare interface DeferredHandle {
 }
 
 /**
- * Register an ordinary workflow that polls connected accounts with independent JSON cursors.
+ * Supply the run of a described workflow that polls its handed accounts with independent JSON
+ * cursors. The manifest describes the workflow: its name, how often it runs, and which accounts.
  * First polls initialize silently. Failed or skipped accounts retain their cursor; removed
  * accounts are pruned. Publication finishes before replacement state is returned.
  *
- * Each account's credential comes from `app.backgroundAuth` with no named scopes, so the host picks
- * one from the manifest's `background-job` grant. Credential resolution and provider reads share a
- * step so credentials are never step outputs.
- * Poll callbacks must keep secrets out of their returned cursor, events, and summary. Resolution
- * errors fail the run with a sanitized message; provider poll errors isolate the account.
- * Key events at their source: a step can repeat before its result commits or after an engine update.
+ * Poll callbacks must keep secrets out of their returned cursor, events, and summary. A failed poll
+ * or a missing credential stays that account's.
+ * Key events at their source: a run can repeat before its state commits.
  */
-export declare function definePoller<Cursor extends JsonValue>(app: Pick<KayAppPluginApi, "workflows" | "auth" | "backgroundAuth" | "events">, localId: string, options: KayAppPollerOptions<Cursor>): void;
+export declare function definePoller<Cursor extends JsonValue>(app: Pick<KayAppPluginApi, "implementWorkflow" | "events">, localId: string, options: KayAppPollerOptions<Cursor>): void;
 
 /** Creates a Dependent type */
 declare function Dependent<If extends TSchema, Then extends TSchema, Else extends TSchema>(if_: If, then_: Then, else_: Else, options?: TSchemaOptions): TDependent<If, Then, Else>;
@@ -2057,6 +2056,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 +2635,19 @@ 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.
+ *
+ * 0.31.0 lets a plugin declare its rail entries as data (#15896). `railEntries` under `kay.ui`
+ * `contributes` names each entry's title, page, shortcut and icon file. It replaces `activityRail` on a
+ * UI app, which is stripped from a manifest that still carries it, so that manifest loses only the
+ * rail button. A plugin that declares a rail entry declares ^0.31.0.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.29.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.31.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -4334,9 +4347,12 @@ export declare interface KayAppImageModelInfo {
 export declare interface KayAppKnowledge {
     registerSource(localId: string, source: KayAppKnowledgeSource): KayAppKnowledgeSourceHandle;
     /**
-     * Search the daemon's knowledge index within the schemes this plugin owns. Present only when
-     * the plugin's `kay.app` target declares the `knowledgeSearch` (`own-schemes`) permission and
-     * the daemon composed an index. A handle kept past disable or replacement never returns hits:
+     * Search the daemon's knowledge index within the schemes this plugin owns, and within the URIs
+     * its granted knowledge sources observe (an `output://` prefix while this plugin holds the
+     * outputs grant, which `artifacts.outputs()` requests). A prefix outside both rejects the call;
+     * a hit outside both is dropped; the host re-reads the source grant before and after the search, and a grant lost during the call answers `unavailable`.
+     * Present only when the plugin's `kay.app` target declares the `knowledgeSearch` (`own-schemes`)
+     * permission and the daemon composed an index. A handle kept past disable or replacement never returns hits:
      * the call rejects while the extension is disabled and resolves `unavailable` once a newer
      * activation has replaced it.
      */
@@ -4734,6 +4750,12 @@ export declare type KayAppModelSelection = {
     readonly kind: "tier";
     readonly tierId: KayAppModelTierId;
     readonly provider?: string | undefined;
+    readonly constraints?: KayAppRouteConstraints | undefined;
+} | {
+    /** One model by its bare id (`gpt-6-astra`), on whichever provider route serves it. */
+    readonly kind: "model";
+    readonly model: string;
+    readonly constraints?: KayAppRouteConstraints | undefined;
 };
 
 /** `app.modelSelection`: registering the policy the daemon consults. */
@@ -5276,6 +5298,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 {
@@ -5308,12 +5338,6 @@ export declare interface KayAppPollerEvent {
 }
 
 export declare interface KayAppPollerOptions<Cursor extends JsonValue> {
-    readonly name: string;
-    readonly description: string;
-    /** Interval in milliseconds; the workflow engine enforces its scheduling floor. */
-    readonly every: number;
-    readonly serviceId: string;
-    readonly schemeId?: string;
     /** Cursor, events, and summary must contain no credentials or other secrets. */
     readonly poll: (input: {
         readonly account: KayAppAccountSummary;
@@ -5520,6 +5544,16 @@ export declare interface KayAppResolvedCredential {
     readonly fields?: Readonly<Record<string, string>>;
 }
 
+/** Hard limits on the routes a `tier` or `model` selection may use. */
+export declare interface KayAppRouteConstraints {
+    /** Only this provider (a family such as `openai` covers its routes). */
+    readonly provider?: string | undefined;
+    /** Only models this vendor made. */
+    readonly vendor?: string | undefined;
+    /** No models this vendor made; an unknown vendor is excluded too. */
+    readonly notVendor?: string | undefined;
+}
+
 /**
  * What one run's work came to: `{ result: "deferred", reason: "catalog_not_ready" }`. Optional;
  * Bonsai keeps it on the run's record and does not show it to a person.
@@ -8032,6 +8066,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 is missing a declared scope, arrives with that status
+ * instead of a token. With no declared scopes, it needs one scope from the plugin's grant.
+ */
+export declare interface KayAppWorkflowAccount {
+    readonly account: KayAppAccountSummary;
+    readonly credential: KayAppBackgroundCredentialResult;
+}
+
 /**
  * What your `run` callback is handed when the trigger fires.
  *
@@ -8145,16 +8189,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 +8208,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 +8252,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>;
@@ -13522,7 +13596,7 @@ declare interface Tool<TParameters extends TSchema = TSchema> {
  * classification (the engine records the rejection on an unexplained failure),
  * and a stored record with one reads as none.
  */
-declare const TOOL_CALL_FAILURE_CODES: readonly ["tool.invalid_input", "tool.blocked", "tool.cancelled", "tool.timeout", "tool.not_found", "tool.unavailable", "tool.execution_failed", "tool.auth_unavailable", "tool.replies_owed", "provider.http", "provider.api", "provider.transport", "uri.not_found", "uri.unsupported_operation", "uri.not_connected", "uri.auth_unavailable", "permission.denied", "edit.empty_edits", "edit.text_not_found", "edit.text_not_unique", "edit.empty_old_text", "edit.overlapping_edits", "edit.no_change"];
+declare const TOOL_CALL_FAILURE_CODES: readonly ["tool.invalid_input", "tool.blocked", "tool.cancelled", "tool.timeout", "tool.not_found", "tool.unavailable", "tool.execution_failed", "tool.auth_unavailable", "tool.replies_owed", "provider.http", "provider.api", "provider.transport", "uri.not_found", "uri.unsupported_operation", "uri.not_connected", "uri.auth_unavailable", "permission.denied", "edit.empty_edits", "edit.text_not_found", "edit.text_not_unique", "edit.empty_old_text", "edit.overlapping_edits", "edit.no_change", "uri.not_connected.pick_account", "uri.not_connected.account_not_allowed", "uri.not_connected.sign_in_expired", "tool.blocked.by_user", "tool.blocked.by_rule", "tool.blocked.by_bonsai"];
 
 /**
  * ---

package/dist/kay-app.js

@@ -634,9 +634,6 @@ function accountCursors(state) {
     };
   });
 }
-function ordinal(left, right) {
-  return left < right ? -1 : left > right ? 1 : 0;
-}
 function plainText(value, max) {
   let text = "";
   for (const character of value) {
@@ -649,125 +646,70 @@ function plainText(value, max) {
   return text;
 }
 function definePoller(app, localId, options) {
-  const { workflows, auth, backgroundAuth, events } = app;
-  if (!workflows)
-    throw new Error("Poller requires workflows");
-  if (!Number.isSafeInteger(options.every) || options.every <= 0) {
-    throw new TypeError("Poller interval must be a positive integer in milliseconds");
-  }
-  workflows.define(localId, {
-    name: options.name,
-    description: options.description,
-    trigger: {
-      kind: "time",
-      schedule: { kind: "every", intervalMs: options.every, anchorAtMs: 0 }
-    },
-    async run(ctx) {
-      if (!auth)
-        throw new Error("Poller requires account listing");
-      if (!backgroundAuth)
-        throw new Error("Poller requires background auth");
-      const previous = accountCursors(ctx.state);
-      const accounts = await ctx.runStep(async () => {
-        const listed = await auth.listAccounts({
-          serviceId: options.serviceId,
-          ...options.schemeId === void 0 ? {} : { schemeId: options.schemeId }
-        });
-        return [...listed].sort((a, b) => ordinal(a.schemeId, b.schemeId) || ordinal(a.accountId, b.accountId));
-      }, { name: "list-poller-accounts" });
-      const next = [];
-      const details = [];
-      let published = 0;
-      let initialized = 0;
-      let skipped = 0;
-      let failed = 0;
-      for (const account of accounts) {
-        const saved = previous.find((entry) => entry.schemeId === account.schemeId && entry.accountId === account.accountId);
-        const outcome = await ctx.runStep(async () => {
-          if (account.status === "needs_reauth" || account.status === "refresh_failed" || account.status === "revoked") {
-            return {
-              status: "skipped",
-              summary: `Sign-in required (${account.status})`
-            };
-          }
-          let credential;
-          try {
-            credential = await backgroundAuth.resolveCredential({
-              serviceId: options.serviceId,
-              schemeId: account.schemeId,
-              accountId: account.accountId,
-              jobId: ctx.runId
-            });
-          } catch {
-            throw new Error("Poller credential resolution failed");
-          }
-          if (credential.status !== "resolved") {
-            return {
-              status: "skipped",
-              summary: credential.status === "requires-auth" ? "Sign-in or required scope missing" : "Credential missing"
-            };
-          }
-          try {
-            const result = await options.poll({
-              account,
-              cursor: structuredClone(saved?.cursor),
-              credential,
-              runId: ctx.runId
-            });
-            return {
-              status: "polled",
-              result: {
-                cursor: result.cursor,
-                ...saved === void 0 || result.events === void 0 ? {} : { events: result.events },
-                ...result.summary === void 0 ? {} : { summary: plainText(result.summary, 600) }
-              }
-            };
-          } catch {
-            return {
-              status: "failed",
-              summary: "Provider poll failed; cursor retained"
-            };
-          }
-        }, { name: "poll-account" });
-        if (outcome.status !== "polled") {
-          if (saved !== void 0)
-            next.push(saved);
-          if (outcome.status === "skipped")
-            skipped++;
-          else
-            failed++;
-          details.push(`${account.schemeId}/${account.accountId}: ${outcome.summary}`);
-          continue;
-        }
-        await ctx.runStep(async () => {
-          for (const event of outcome.result.events ?? []) {
-            events.publish(event.localId, {
-              ...event.input,
-              source: { poller: localId, runId: ctx.runId }
-            });
-          }
-          return null;
-        }, { name: "publish-poller-events" });
-        published += outcome.result.events?.length ?? 0;
-        if (saved === void 0)
-          initialized++;
-        next.push({
-          schemeId: account.schemeId,
-          accountId: account.accountId,
-          cursor: outcome.result.cursor
+  const { events } = app;
+  app.implementWorkflow(localId, async ({ state, runId, accounts, runStep }) => {
+    const previous = accountCursors(state);
+    const next = [];
+    const details = [];
+    let published = 0;
+    let initialized = 0;
+    let skipped = 0;
+    let failed = 0;
+    for (const { account, credential } of accounts) {
+      const saved = previous.find((entry) => entry.schemeId === account.schemeId && entry.accountId === account.accountId);
+      const name = `${account.schemeId}/${account.accountId}`;
+      const keepSaved = (summary) => {
+        if (saved !== void 0)
+          next.push(saved);
+        details.push(`${name}: ${summary}`);
+      };
+      if (credential.status !== "resolved") {
+        skipped++;
+        keepSaved(credential.status === "requires-auth" ? "Sign-in or required scope missing" : "Credential missing");
+        continue;
+      }
+      let result;
+      try {
+        result = await options.poll({
+          account,
+          cursor: structuredClone(saved?.cursor),
+          credential,
+          runId
         });
-        if (outcome.result.summary)
-          details.push(`${account.schemeId}/${account.accountId}: ${outcome.result.summary}`);
+      } catch {
+        failed++;
+        keepSaved("Provider poll failed; cursor retained");
+        continue;
       }
-      return {
-        state: { accounts: next },
-        summary: {
-          headline: plainText(`${published} events; ${initialized} initialized; ${skipped} skipped; ${failed} failed`, 100),
-          ...details.length === 0 ? {} : { details: plainText(details.join("; "), 600) },
-          author: "automation"
+      const toPublish = saved === void 0 ? [] : result.events ?? [];
+      await runStep(async () => {
+        for (const event of toPublish) {
+          events.publish(event.localId, {
+            ...event.input,
+            source: { poller: localId, runId }
+          });
         }
-      };
+      });
+      published += toPublish.length;
+      if (saved === void 0)
+        initialized++;
+      next.push({
+        schemeId: account.schemeId,
+        accountId: account.accountId,
+        cursor: result.cursor
+      });
+      if (result.summary) {
+        details.push(`${name}: ${plainText(result.summary, 600)}`);
+      }
     }
+    return {
+      state: { accounts: next },
+      summary: {
+        headline: plainText(`${published} events; ${initialized} initialized; ${skipped} skipped; ${failed} failed`, 100),
+        ...details.length === 0 ? {} : { details: plainText(details.join("; "), 600) },
+        author: "automation"
+      }
+    };
   });
 }
 

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.31.0",
   "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

@@ -127,15 +127,18 @@ self-contained module: unlike the daemon targets, `ui.tsx` cannot import sibling
 plugin UI contributes through `api.slots` (`registerPage`, `registerSidebarItem`,
 `registerPaneAction`, and the rest of `buildSlots` in
 `packages/kay-renderer/src/renderer/src/extension-loader/build-extension-api.ts`). A page gets its own
-activity-rail button when a `registerSidebarItem({ pageId, placement: "activityRail" })` from the
-same plugin points at it.
+activity-rail button when the manifest declares it: `railEntries` under `targets.kay.ui.contributes`,
+with `id`, `title` and `page`, and optionally `icon`, `shortcut`, `order` and `section`. That
+declaration works with no `ui.tsx` at all.
 
 **Icons: declare one plugin icon, override only where you mean it.** Set the manifest `icon` (a
 package-relative SVG) and every surface the plugin contributes inherits it: reference pills, its
 rail button, and its pages' tabs, pane headers and palette entries (shown as your full-colour mark
-on a small white tile). Set `icon` on a `registerSidebarItem` or `registerPage` descriptor only to
-show a monochrome glyph there instead (a glyph name such as `"git-branch"`, or `{ svg }`); a page
-and its rail item borrow each other's glyph, so one declaration covers the destination. Full
+on a small white tile). Set `icon` on a rail entry to show a single-colour glyph on the rail: a path to an SVG in
+the plugin (`"./assets/rail.svg"`). Only its shape is used, painted in the rail's colour, so colours
+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 unless `registerPage`'s `icon` says otherwise. Full
 precedence: `packages/kay-frontend-sdk/ARCHITECTURE.md`, "Plugin icon".
 
 `ui.tsx` has no `node_modules` of its own. The renderer bundles it and rewrites its `react` and