@yaklabs-ai/plugin-sdk 0.30.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.30.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.30.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.30.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

@@ -2357,8 +2357,13 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.30.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.31.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -7611,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

@@ -2411,8 +2411,13 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.30.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.31.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -5654,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">;
@@ -8687,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

@@ -2686,8 +2686,13 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.30.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.31.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -8822,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

@@ -1056,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>;
@@ -2643,8 +2641,13 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.30.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.31.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -4344,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.
      */
@@ -4744,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. */
@@ -5326,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;
@@ -5538,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.
@@ -8052,8 +8068,8 @@ export declare interface KayAppWhiteboardTypes {
 
 /**
  * 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.
+ * 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;
@@ -13580,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/package.json

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