@yaklabs-ai/plugin-sdk 0.27.1 → 0.29.0

package/README.md

@@ -13,7 +13,7 @@ it under the name your plugin code actually imports:
 ```json
 {
   "dependencies": {
-    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.27.1"
+    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.29.0"
   }
 }
 ```
@@ -62,7 +62,7 @@ Every tool the entrypoint registers is declared in the manifest too:
   "description": "Greets people by name.",
   "version": "0.1.0",
   "namespace": "widgets",
-  "compatibility": { "sdk": "^0.27.1" },
+  "compatibility": { "sdk": "^0.29.0" },
   "targets": {
     "kay": {
       "agent": {

package/THIRD-PARTY-INVENTORY.json

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

package/dist/disclosure.d.ts

@@ -34,6 +34,20 @@ declare interface AccountIdentity {
     readonly providerSessionId?: string;
 }
 
+/**
+ * Whose credential this is: every provider account it reaches. One sign-in can reach several
+ * (Cloudflare), so the answer is always a list. A bad credential throws.
+ */
+declare type AccountLookup = (input: AccountLookupInput) => Promise<readonly LookedUpAccount[]>;
+
+/** What an account lookup is asked about: a fresh credential. */
+declare interface AccountLookupInput {
+    readonly accessToken: string;
+    /** Every declared field of a multi-field api-key scheme; empty for anything else. */
+    readonly fields: Readonly<Record<string, string>>;
+    readonly signal: AbortSignal;
+}
+
 /**
  * Structured, non-secret *provenance* for a connected account: which record on the provider's side
  * this credential points at. Says nothing about the human - a Notion `displayName` here is the
@@ -2318,8 +2332,23 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * hosted module's code and manifest must agree on it, and the daemon reads it to find an
  * external-CLI scheme without running the module. A module that runs in the daemon is unchanged,
  * so this is additive; a plugin whose manifest sets `authScheme` declares ^0.27.1.
+ *
+ * 0.28.0 makes "whose credential is this?" one call (#15714). `api.auth.registerAccountLookup`
+ * replaces `registerValidator` and `registerAccountResolver`: it takes the credential, its fields and
+ * a cancel signal, and returns every account the credential reaches. A manifest says `account:
+ * "lookup"` on any `oauth2` or `api-key` scheme the plugin answers for, in place of `validates: true`
+ * and the `"resolveAccountId"` and `"resolveAccounts"` values, and a `pkce` scheme on a client the
+ * host holds may name one too. A plugin using a removed member or value stops loading until it is
+ * rebuilt; a code search found none outside this repo. A plugin with a sign-in declares ^0.28.0. 0.26.3 and 0.27.1
+ * stay served for a plugin that uses none of these.
+ *
+ * 0.29.0 replaces `servedSimulators` (`KayServedSimulators`, a lookup by adapter id) with
+ * `simulator` on both targets (#14929): what the plugin's own simulator built, handed over once by
+ * whichever process runs the plugin. A plugin's simulator file exports `createPluginSimulator`
+ * (`KayPluginSimulatorFactory`). A clean break: only this repo's plugins read the old member, and
+ * a plugin with no simulator is unaffected, so 0.28.0 stays served.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.27.1";
+declare const KAY_PLUGIN_SDK_VERSION: "0.29.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -2555,11 +2584,11 @@ declare interface KayAgentPluginApi {
     /** Absent unless the `knownResources` grant is requested and effectively granted. */
     readonly knownResources?: KayAgentKnownResources;
     /**
-     * Optional: absent unless a simulating Bonsai daemon serves this plugin a simulator (SDK 0.18.1).
-     * A production daemon never does. In this version only plugins the release carries are served;
-     * any plugin may ship a `./simulator` later. See {@link KayServedSimulators}.
+     * What this plugin's own simulator built, in a simulated run only (SDK 0.29.0): absent in every
+     * other, so treat absence as the normal case. Use it in place of the real backend; its shape is
+     * the plugin's own, so narrow it before use. See {@link KayPluginSimulatorFactory}.
      */
-    readonly servedSimulators?: KayServedSimulators;
+    readonly simulator?: unknown;
     /**
      * Present when the host composes Whiteboard. Each operation is checked against its exact
      * `whiteboard.<operation> {scope}` claim; handle presence is not consent.
@@ -2697,16 +2726,12 @@ declare interface KayAgentPluginApi {
      */
     readonly auth: {
         /**
-         * The check for an `api-key` scheme the manifest marks `validates: true`. `serviceId` and
-         * `schemeId` are the manifest's global ids (`github.account`, `github.pat`).
+         * Whose credential this is, for a scheme whose manifest says `account: "lookup"`. `serviceId` and
+         * `schemeId` are the manifest's global ids (`github.account`, `github.pat`). On an `api-key`
+         * scheme it also checks the key before it is saved, and must name exactly one account. Refused
+         * on any other scheme.
          */
-        registerValidator(serviceId: string, schemeId: string, validate: ValidatePluginApiKeyCredential): void;
-        /**
-         * The account lookup for an `oauth2` scheme whose manifest names it as where the account comes
-         * from (`account: "resolveAccountId"` or `"resolveAccounts"`), registering that function only.
-         * Refused on any other scheme.
-         */
-        registerAccountResolver(serviceId: string, schemeId: string, resolver: PluginAccountResolver): void;
+        registerAccountLookup(serviceId: string, schemeId: string, lookup: PluginAccountLookup): void;
         /**
          * Declare a delegated scheme (plugin-provided connect/refresh over opaque material) for a
          * service. The host maps it onto the kernel's `DelegatedAuthScheme` and drives its `connect`
@@ -3203,24 +3228,6 @@ declare const KayPluginProtocolVersion: z.ZodLiteral<"kay.plugin.v1">;
 
 declare type KayPluginProtocolVersion = z.infer<typeof KayPluginProtocolVersion>;
 
-/**
- * The simulators a simulating Bonsai daemon (evals, dev, tests) serves this plugin, keyed by the
- * adapter id its simulated URI connection rows name. The daemon builds each from the plugin's own
- * dev-only `./simulator` subpath; the plugin never imports its simulator.
- *
- * The member that carries this, `servedSimulators` on both plugin APIs, is optional and absent
- * unless a simulating daemon serves it. A production daemon never does, so treat absence as the
- * normal case. In this version the daemon serves it only to plugins the release carries; the seam
- * is not specific to them, and any plugin may ship a `./simulator` later.
- */
-declare interface KayServedSimulators {
-    /**
-     * What this plugin's simulator built for `adapterId`, or `undefined` when none was served for
-     * that id. The shape is the plugin's own simulator contract; narrow it before use.
-     */
-    get(adapterId: string): unknown;
-}
-
 /** Applies a KeyOf action to the given type. */
 declare function KeyOf<Type extends TSchema>(type: Type, options?: TSchemaOptions): TKeyOf_2<Type>;
 
@@ -3330,6 +3337,15 @@ declare const LocalContributionId: z.ZodString;
 
 declare type LocalContributionId = z.infer<typeof LocalContributionId>;
 
+/** One provider account a credential reaches. */
+declare interface LookedUpAccount {
+    readonly accountId: string;
+    readonly label?: string;
+    readonly identity?: AccountIdentity;
+    /** Non-secret observations the host may surface without retaining credential material. */
+    readonly capabilityChecks?: readonly ApiKeyCapabilityCheck[];
+}
+
 /** Applies a Lowercase action to the given type. */
 declare function Lowercase_2<Type extends TSchema>(type: Type, options?: TSchemaOptions): TLowercase<Type>;
 
@@ -4184,13 +4200,10 @@ export declare const PLUGIN_DISCLOSURE_CONTRACT = 2;
 export declare const PLUGIN_DISCLOSURE_RULES: readonly ["agent-hint-missing", "agent-hint-summary-empty", "agent-hint-flows-empty", "agent-hint-triggers-missing", "scheme-claim-missing", "help-missing", "help-malformed", "help-throws", "help-uri-malformed", "help-uri-throws", "verb-coverage-missing", "template-operation-docs-missing", "verb-docs-missing", "template-accepts-missing", "template-address-unmatchable", "template-delete-effect-missing", "template-operations-missing", "template-parameter-unknown", "template-scheme-mismatch", "clamp-summary", "clamp-flow-label", "clamp-flow-when", "clamp-flow-example", "clamp-trigger-count", "clamp-trigger-item", "clamp-help-uri", "skill-link-dangling", "skill-link-missing-scheme", "skill-twin-count-mismatch", "skill-twin-missing-declaration", "skill-twin-description-mismatch", "skill-twin-file-unreadable", "skill-twin-frontmatter-name-mismatch", "skill-twin-frontmatter-description-mismatch", "skill-twin-body-mismatch"];
 
 /**
- * How a plugin learns which provider account a fresh OAuth token belongs to: one account, or every
- * account the grant reaches. Registered with `api.auth.registerAccountResolver`.
+ * Whose credential this is: every provider account it reaches, usually one. A bad credential throws.
+ * Registered with `api.auth.registerAccountLookup`.
  */
-declare interface PluginAccountResolver {
-    readonly resolveAccountId?: ResolvePluginAccountId;
-    readonly resolveAccounts?: ResolvePluginAccounts;
-}
+declare type PluginAccountLookup = AccountLookup;
 
 /** The kinds of capability a plugin service can advertise (mirrors the host capability taxonomy). */
 declare type PluginCapabilityKind = "uri-module" | "tool" | "search-provider";
@@ -4651,28 +4664,6 @@ declare interface ResolvedCredential {
     readonly fields?: Readonly<Record<string, string>>;
 }
 
-/**
- * Derive a stable provider account id (and optional label) from a freshly connected access token,
- * plus - when known - who the account belongs to.
- *
- * A resolver almost always calls the provider's profile endpoint to derive `accountId` at all, so
- * the identity fields are already in the response: return them rather than flattening the person
- * into `label`. Populating `identity` is what lets the agent know the user's handle/email for a
- * connected service without asking.
- */
-declare type ResolvePluginAccountId = (accessToken: string) => Promise<{
-    readonly accountId: string;
-    readonly label?: string;
-    readonly identity?: AccountIdentity;
-}>;
-
-/** Enumerate every provider account a fresh OAuth grant powers. */
-declare type ResolvePluginAccounts = (accessToken: string) => Promise<readonly {
-    readonly accountId: string;
-    readonly label?: string;
-    readonly identity?: AccountIdentity;
-}[]>;
-
 /** Match remaining characters in the buffer until end. If no characters are in buffer, no match */
 declare function Rest<Input extends string>(input: Input): TRest<Input>;
 
@@ -10213,26 +10204,6 @@ declare interface Usage {
     };
 }
 
-/** Validate freshly-entered material and resolve the provider account before persistence. */
-declare type ValidateApiKeyCredential = (input: ValidateApiKeyCredentialInput) => Promise<ValidateApiKeyCredentialResult>;
-
-declare interface ValidateApiKeyCredentialInput {
-    readonly accessToken: string;
-    /** Every declared field; empty for a classic single-secret scheme. */
-    readonly fields: Readonly<Record<string, string>>;
-    readonly signal: AbortSignal;
-}
-
-declare interface ValidateApiKeyCredentialResult {
-    readonly accountId: string;
-    readonly label?: string;
-    readonly identity?: AccountIdentity;
-    /** Non-secret observations the host may surface without retaining credential material. */
-    readonly capabilityChecks?: readonly ApiKeyCapabilityCheck[];
-}
-
-declare type ValidatePluginApiKeyCredential = ValidateApiKeyCredential;
-
 /**
  * ---
  * responsibility: The one interface through which a vendored-MCP plugin's code calls a tool on its

package/dist/disclosure.js

@@ -932,9 +932,7 @@ function collectUriModulesFromKayAgentActivate(activate) {
     registerConverter: () => {
     },
     auth: {
-      registerValidator: () => {
-      },
-      registerAccountResolver: () => {
+      registerAccountLookup: () => {
       },
       declareDelegatedScheme: () => {
       },

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

@@ -34,6 +34,20 @@ declare interface AccountIdentity {
     readonly providerSessionId?: string;
 }
 
+/**
+ * Whose credential this is: every provider account it reaches. One sign-in can reach several
+ * (Cloudflare), so the answer is always a list. A bad credential throws.
+ */
+declare type AccountLookup = (input: AccountLookupInput) => Promise<readonly LookedUpAccount[]>;
+
+/** What an account lookup is asked about: a fresh credential. */
+declare interface AccountLookupInput {
+    readonly accessToken: string;
+    /** Every declared field of a multi-field api-key scheme; empty for anything else. */
+    readonly fields: Readonly<Record<string, string>>;
+    readonly signal: AbortSignal;
+}
+
 /**
  * Structured, non-secret *provenance* for a connected account: which record on the provider's side
  * this credential points at. Says nothing about the human - a Notion `displayName` here is the
@@ -2372,8 +2386,23 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * hosted module's code and manifest must agree on it, and the daemon reads it to find an
  * external-CLI scheme without running the module. A module that runs in the daemon is unchanged,
  * so this is additive; a plugin whose manifest sets `authScheme` declares ^0.27.1.
+ *
+ * 0.28.0 makes "whose credential is this?" one call (#15714). `api.auth.registerAccountLookup`
+ * replaces `registerValidator` and `registerAccountResolver`: it takes the credential, its fields and
+ * a cancel signal, and returns every account the credential reaches. A manifest says `account:
+ * "lookup"` on any `oauth2` or `api-key` scheme the plugin answers for, in place of `validates: true`
+ * and the `"resolveAccountId"` and `"resolveAccounts"` values, and a `pkce` scheme on a client the
+ * host holds may name one too. A plugin using a removed member or value stops loading until it is
+ * rebuilt; a code search found none outside this repo. A plugin with a sign-in declares ^0.28.0. 0.26.3 and 0.27.1
+ * stay served for a plugin that uses none of these.
+ *
+ * 0.29.0 replaces `servedSimulators` (`KayServedSimulators`, a lookup by adapter id) with
+ * `simulator` on both targets (#14929): what the plugin's own simulator built, handed over once by
+ * whichever process runs the plugin. A plugin's simulator file exports `createPluginSimulator`
+ * (`KayPluginSimulatorFactory`). A clean break: only this repo's plugins read the old member, and
+ * a plugin with no simulator is unaffected, so 0.28.0 stays served.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.27.1";
+declare const KAY_PLUGIN_SDK_VERSION: "0.29.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -2606,11 +2635,11 @@ declare interface KayAgentPluginApi {
     /** Absent unless the `knownResources` grant is requested and effectively granted. */
     readonly knownResources?: KayAgentKnownResources;
     /**
-     * Optional: absent unless a simulating Bonsai daemon serves this plugin a simulator (SDK 0.18.1).
-     * A production daemon never does. In this version only plugins the release carries are served;
-     * any plugin may ship a `./simulator` later. See {@link KayServedSimulators}.
+     * What this plugin's own simulator built, in a simulated run only (SDK 0.29.0): absent in every
+     * other, so treat absence as the normal case. Use it in place of the real backend; its shape is
+     * the plugin's own, so narrow it before use. See {@link KayPluginSimulatorFactory}.
      */
-    readonly servedSimulators?: KayServedSimulators;
+    readonly simulator?: unknown;
     /**
      * Present when the host composes Whiteboard. Each operation is checked against its exact
      * `whiteboard.<operation> {scope}` claim; handle presence is not consent.
@@ -2748,16 +2777,12 @@ declare interface KayAgentPluginApi {
      */
     readonly auth: {
         /**
-         * The check for an `api-key` scheme the manifest marks `validates: true`. `serviceId` and
-         * `schemeId` are the manifest's global ids (`github.account`, `github.pat`).
+         * Whose credential this is, for a scheme whose manifest says `account: "lookup"`. `serviceId` and
+         * `schemeId` are the manifest's global ids (`github.account`, `github.pat`). On an `api-key`
+         * scheme it also checks the key before it is saved, and must name exactly one account. Refused
+         * on any other scheme.
          */
-        registerValidator(serviceId: string, schemeId: string, validate: ValidatePluginApiKeyCredential): void;
-        /**
-         * The account lookup for an `oauth2` scheme whose manifest names it as where the account comes
-         * from (`account: "resolveAccountId"` or `"resolveAccounts"`), registering that function only.
-         * Refused on any other scheme.
-         */
-        registerAccountResolver(serviceId: string, schemeId: string, resolver: PluginAccountResolver): void;
+        registerAccountLookup(serviceId: string, schemeId: string, lookup: PluginAccountLookup): void;
         /**
          * Declare a delegated scheme (plugin-provided connect/refresh over opaque material) for a
          * service. The host maps it onto the kernel's `DelegatedAuthScheme` and drives its `connect`
@@ -3254,24 +3279,6 @@ declare const KayPluginProtocolVersion: z.ZodLiteral<"kay.plugin.v1">;
 
 declare type KayPluginProtocolVersion = z.infer<typeof KayPluginProtocolVersion>;
 
-/**
- * The simulators a simulating Bonsai daemon (evals, dev, tests) serves this plugin, keyed by the
- * adapter id its simulated URI connection rows name. The daemon builds each from the plugin's own
- * dev-only `./simulator` subpath; the plugin never imports its simulator.
- *
- * The member that carries this, `servedSimulators` on both plugin APIs, is optional and absent
- * unless a simulating daemon serves it. A production daemon never does, so treat absence as the
- * normal case. In this version the daemon serves it only to plugins the release carries; the seam
- * is not specific to them, and any plugin may ship a `./simulator` later.
- */
-declare interface KayServedSimulators {
-    /**
-     * What this plugin's simulator built for `adapterId`, or `undefined` when none was served for
-     * that id. The shape is the plugin's own simulator contract; narrow it before use.
-     */
-    get(adapterId: string): unknown;
-}
-
 /** Applies a KeyOf action to the given type. */
 declare function KeyOf<Type extends TSchema>(type: Type, options?: TSchemaOptions): TKeyOf_2<Type>;
 
@@ -3381,6 +3388,15 @@ declare const LocalContributionId: z.ZodString;
 
 declare type LocalContributionId = z.infer<typeof LocalContributionId>;
 
+/** One provider account a credential reaches. */
+declare interface LookedUpAccount {
+    readonly accountId: string;
+    readonly label?: string;
+    readonly identity?: AccountIdentity;
+    /** Non-secret observations the host may surface without retaining credential material. */
+    readonly capabilityChecks?: readonly ApiKeyCapabilityCheck[];
+}
+
 /** Applies a Lowercase action to the given type. */
 declare function Lowercase_2<Type extends TSchema>(type: Type, options?: TSchemaOptions): TLowercase<Type>;
 
@@ -4202,13 +4218,10 @@ declare function Pick_2<Type extends TSchema, Indexer extends TSchema>(type: Typ
 declare function PickDeferred<Type extends TSchema, Indexer extends TSchema>(type: Type, indexer: Indexer, options?: TSchemaOptions): TPickDeferred<Type, Indexer>;
 
 /**
- * How a plugin learns which provider account a fresh OAuth token belongs to: one account, or every
- * account the grant reaches. Registered with `api.auth.registerAccountResolver`.
+ * Whose credential this is: every provider account it reaches, usually one. A bad credential throws.
+ * Registered with `api.auth.registerAccountLookup`.
  */
-declare interface PluginAccountResolver {
-    readonly resolveAccountId?: ResolvePluginAccountId;
-    readonly resolveAccounts?: ResolvePluginAccounts;
-}
+declare type PluginAccountLookup = AccountLookup;
 
 /** The kinds of capability a plugin service can advertise (mirrors the host capability taxonomy). */
 declare type PluginCapabilityKind = "uri-module" | "tool" | "search-provider";
@@ -4763,10 +4776,7 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
             }>>;
             clientId: z.ZodOptional<z.ZodString>;
             clientSecret: z.ZodOptional<z.ZodString>;
-            account: z.ZodOptional<z.ZodEnum<{
-                resolveAccountId: "resolveAccountId";
-                resolveAccounts: "resolveAccounts";
-            }>>;
+            account: z.ZodOptional<z.ZodLiteral<"lookup">>;
             localId: z.ZodString;
             globalId: z.ZodString;
             kind: z.ZodLiteral<"oauth2">;
@@ -4795,8 +4805,7 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
             exchange: z.ZodLiteral<"confidential">;
             clientSuppliers: z.ZodTuple<[z.ZodLiteral<"kay">], null>;
             account: z.ZodEnum<{
-                resolveAccountId: "resolveAccountId";
-                resolveAccounts: "resolveAccounts";
+                lookup: "lookup";
                 "sign-in": "sign-in";
             }>;
             localId: z.ZodString;
@@ -4837,7 +4846,7 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                 instructions: z.ZodString;
                 url: z.ZodURL;
             }, z.core.$strict>>;
-            validates: z.ZodOptional<z.ZodLiteral<true>>;
+            account: z.ZodOptional<z.ZodLiteral<"lookup">>;
             displayName: z.ZodOptional<z.ZodString>;
             agentHint: z.ZodOptional<z.ZodString>;
             summary: z.ZodOptional<z.ZodString>;
@@ -5687,28 +5696,6 @@ declare type ResolveExternalCliResult = {
     readonly accounts?: readonly AuthAccount[];
 };
 
-/**
- * Derive a stable provider account id (and optional label) from a freshly connected access token,
- * plus - when known - who the account belongs to.
- *
- * A resolver almost always calls the provider's profile endpoint to derive `accountId` at all, so
- * the identity fields are already in the response: return them rather than flattening the person
- * into `label`. Populating `identity` is what lets the agent know the user's handle/email for a
- * connected service without asking.
- */
-declare type ResolvePluginAccountId = (accessToken: string) => Promise<{
-    readonly accountId: string;
-    readonly label?: string;
-    readonly identity?: AccountIdentity;
-}>;
-
-/** Enumerate every provider account a fresh OAuth grant powers. */
-declare type ResolvePluginAccounts = (accessToken: string) => Promise<readonly {
-    readonly accountId: string;
-    readonly label?: string;
-    readonly identity?: AccountIdentity;
-}[]>;
-
 declare interface ResolveTokenFailure {
     readonly ok: false;
     readonly reason: ResolveTokenFailureReason;
@@ -11280,26 +11267,6 @@ declare interface Usage {
     };
 }
 
-/** Validate freshly-entered material and resolve the provider account before persistence. */
-declare type ValidateApiKeyCredential = (input: ValidateApiKeyCredentialInput) => Promise<ValidateApiKeyCredentialResult>;
-
-declare interface ValidateApiKeyCredentialInput {
-    readonly accessToken: string;
-    /** Every declared field; empty for a classic single-secret scheme. */
-    readonly fields: Readonly<Record<string, string>>;
-    readonly signal: AbortSignal;
-}
-
-declare interface ValidateApiKeyCredentialResult {
-    readonly accountId: string;
-    readonly label?: string;
-    readonly identity?: AccountIdentity;
-    /** Non-secret observations the host may surface without retaining credential material. */
-    readonly capabilityChecks?: readonly ApiKeyCapabilityCheck[];
-}
-
-declare type ValidatePluginApiKeyCredential = ValidateApiKeyCredential;
-
 /**
  * ---
  * responsibility: The one interface through which a vendored-MCP plugin's code calls a tool on its

package/dist/kay-agent.d.ts

@@ -35,6 +35,20 @@ export declare interface AccountIdentity {
     readonly providerSessionId?: string;
 }
 
+/**
+ * Whose credential this is: every provider account it reaches. One sign-in can reach several
+ * (Cloudflare), so the answer is always a list. A bad credential throws.
+ */
+declare type AccountLookup = (input: AccountLookupInput) => Promise<readonly LookedUpAccount[]>;
+
+/** What an account lookup is asked about: a fresh credential. */
+declare interface AccountLookupInput {
+    readonly accessToken: string;
+    /** Every declared field of a multi-field api-key scheme; empty for anything else. */
+    readonly fields: Readonly<Record<string, string>>;
+    readonly signal: AbortSignal;
+}
+
 /**
  * Structured, non-secret *provenance* for a connected account: which record on the provider's side
  * this credential points at. Says nothing about the human - a Notion `displayName` here is the
@@ -2647,8 +2661,23 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * hosted module's code and manifest must agree on it, and the daemon reads it to find an
  * external-CLI scheme without running the module. A module that runs in the daemon is unchanged,
  * so this is additive; a plugin whose manifest sets `authScheme` declares ^0.27.1.
+ *
+ * 0.28.0 makes "whose credential is this?" one call (#15714). `api.auth.registerAccountLookup`
+ * replaces `registerValidator` and `registerAccountResolver`: it takes the credential, its fields and
+ * a cancel signal, and returns every account the credential reaches. A manifest says `account:
+ * "lookup"` on any `oauth2` or `api-key` scheme the plugin answers for, in place of `validates: true`
+ * and the `"resolveAccountId"` and `"resolveAccounts"` values, and a `pkce` scheme on a client the
+ * host holds may name one too. A plugin using a removed member or value stops loading until it is
+ * rebuilt; a code search found none outside this repo. A plugin with a sign-in declares ^0.28.0. 0.26.3 and 0.27.1
+ * stay served for a plugin that uses none of these.
+ *
+ * 0.29.0 replaces `servedSimulators` (`KayServedSimulators`, a lookup by adapter id) with
+ * `simulator` on both targets (#14929): what the plugin's own simulator built, handed over once by
+ * whichever process runs the plugin. A plugin's simulator file exports `createPluginSimulator`
+ * (`KayPluginSimulatorFactory`). A clean break: only this repo's plugins read the old member, and
+ * a plugin with no simulator is unaffected, so 0.28.0 stays served.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.27.1";
+declare const KAY_PLUGIN_SDK_VERSION: "0.29.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -2913,11 +2942,11 @@ export declare interface KayAgentPluginApi {
     /** Absent unless the `knownResources` grant is requested and effectively granted. */
     readonly knownResources?: KayAgentKnownResources;
     /**
-     * Optional: absent unless a simulating Bonsai daemon serves this plugin a simulator (SDK 0.18.1).
-     * A production daemon never does. In this version only plugins the release carries are served;
-     * any plugin may ship a `./simulator` later. See {@link KayServedSimulators}.
+     * What this plugin's own simulator built, in a simulated run only (SDK 0.29.0): absent in every
+     * other, so treat absence as the normal case. Use it in place of the real backend; its shape is
+     * the plugin's own, so narrow it before use. See {@link KayPluginSimulatorFactory}.
      */
-    readonly servedSimulators?: KayServedSimulators;
+    readonly simulator?: unknown;
     /**
      * Present when the host composes Whiteboard. Each operation is checked against its exact
      * `whiteboard.<operation> {scope}` claim; handle presence is not consent.
@@ -3055,16 +3084,12 @@ export declare interface KayAgentPluginApi {
      */
     readonly auth: {
         /**
-         * The check for an `api-key` scheme the manifest marks `validates: true`. `serviceId` and
-         * `schemeId` are the manifest's global ids (`github.account`, `github.pat`).
-         */
-        registerValidator(serviceId: string, schemeId: string, validate: ValidatePluginApiKeyCredential): void;
-        /**
-         * The account lookup for an `oauth2` scheme whose manifest names it as where the account comes
-         * from (`account: "resolveAccountId"` or `"resolveAccounts"`), registering that function only.
-         * Refused on any other scheme.
+         * Whose credential this is, for a scheme whose manifest says `account: "lookup"`. `serviceId` and
+         * `schemeId` are the manifest's global ids (`github.account`, `github.pat`). On an `api-key`
+         * scheme it also checks the key before it is saved, and must name exactly one account. Refused
+         * on any other scheme.
          */
-        registerAccountResolver(serviceId: string, schemeId: string, resolver: PluginAccountResolver): void;
+        registerAccountLookup(serviceId: string, schemeId: string, lookup: PluginAccountLookup): void;
         /**
          * Declare a delegated scheme (plugin-provided connect/refresh over opaque material) for a
          * service. The host maps it onto the kernel's `DelegatedAuthScheme` and drives its `connect`
@@ -3580,21 +3605,19 @@ declare const KayPluginProtocolVersion: z.ZodLiteral<"kay.plugin.v1">;
 declare type KayPluginProtocolVersion = z.infer<typeof KayPluginProtocolVersion>;
 
 /**
- * The simulators a simulating Bonsai daemon (evals, dev, tests) serves this plugin, keyed by the
- * adapter id its simulated URI connection rows name. The daemon builds each from the plugin's own
- * dev-only `./simulator` subpath; the plugin never imports its simulator.
- *
- * The member that carries this, `servedSimulators` on both plugin APIs, is optional and absent
- * unless a simulating daemon serves it. A production daemon never does, so treat absence as the
- * normal case. In this version the daemon serves it only to plugins the release carries; the seam
- * is not specific to them, and any plugin may ship a `./simulator` later.
+ * What a plugin's dev-only simulator file exports as `createPluginSimulator`. Whichever process
+ * runs the plugin calls it once and hands the result to that plugin alone, as `simulator` on both
+ * plugin APIs. The result's shape is the plugin's own: nothing between the two reads it, and the
+ * plugin never imports its simulator.
  */
-export declare interface KayServedSimulators {
-    /**
-     * What this plugin's simulator built for `adapterId`, or `undefined` when none was served for
-     * that id. The shape is the plugin's own simulator contract; narrow it before use.
-     */
-    get(adapterId: string): unknown;
+export declare type KayPluginSimulatorFactory = (options: KayPluginSimulatorOptions) => unknown;
+
+/**
+ * What the launcher of a simulated run (evals, dev, tests) gives a plugin's simulator: the folder
+ * its worlds live under. The simulator picks its own folders inside it.
+ */
+export declare interface KayPluginSimulatorOptions {
+    readonly stateRoot: string;
 }
 
 /** Applies a KeyOf action to the given type. */
@@ -3747,6 +3770,15 @@ declare const LocalContributionId: z.ZodString;
 
 declare type LocalContributionId = z.infer<typeof LocalContributionId>;
 
+/** One provider account a credential reaches. */
+declare interface LookedUpAccount {
+    readonly accountId: string;
+    readonly label?: string;
+    readonly identity?: AccountIdentity;
+    /** Non-secret observations the host may surface without retaining credential material. */
+    readonly capabilityChecks?: readonly ApiKeyCapabilityCheck[];
+}
+
 /** Applies a Lowercase action to the given type. */
 declare function Lowercase_2<Type extends TSchema>(type: Type, options?: TSchemaOptions): TLowercase<Type>;
 
@@ -4821,13 +4853,21 @@ declare function Pick_2<Type extends TSchema, Indexer extends TSchema>(type: Typ
 declare function PickDeferred<Type extends TSchema, Indexer extends TSchema>(type: Type, indexer: Indexer, options?: TSchemaOptions): TPickDeferred<Type, Indexer>;
 
 /**
- * How a plugin learns which provider account a fresh OAuth token belongs to: one account, or every
- * account the grant reaches. Registered with `api.auth.registerAccountResolver`.
+ * One provider account a credential reaches. A lookup almost always calls the provider's profile
+ * endpoint to find `accountId`, so the identity fields are already in the response: return them
+ * rather than flattening the person into `label`. `identity` is what lets the agent know the user's
+ * handle or email for a connected service without asking.
  */
-export declare interface PluginAccountResolver {
-    readonly resolveAccountId?: ResolvePluginAccountId;
-    readonly resolveAccounts?: ResolvePluginAccounts;
-}
+export declare type PluginAccount = LookedUpAccount;
+
+/**
+ * Whose credential this is: every provider account it reaches, usually one. A bad credential throws.
+ * Registered with `api.auth.registerAccountLookup`.
+ */
+export declare type PluginAccountLookup = AccountLookup;
+
+/** What an account lookup is asked about: a fresh credential, its fields, and a cancel signal. */
+export declare type PluginAccountLookupInput = AccountLookupInput;
 
 /** Per-call options every method accepts. No construction-time credentials (see module doc) - an
  * `Authorization`/`Api-Key`/etc header goes here, per call, after `withResolvedAuth` resolves it. */
@@ -5733,28 +5773,6 @@ declare type ResolveExternalCliResult = {
     readonly accounts?: readonly AuthAccount[];
 };
 
-/**
- * Derive a stable provider account id (and optional label) from a freshly connected access token,
- * plus - when known - who the account belongs to.
- *
- * A resolver almost always calls the provider's profile endpoint to derive `accountId` at all, so
- * the identity fields are already in the response: return them rather than flattening the person
- * into `label`. Populating `identity` is what lets the agent know the user's handle/email for a
- * connected service without asking.
- */
-export declare type ResolvePluginAccountId = (accessToken: string) => Promise<{
-    readonly accountId: string;
-    readonly label?: string;
-    readonly identity?: AccountIdentity;
-}>;
-
-/** Enumerate every provider account a fresh OAuth grant powers. */
-export declare type ResolvePluginAccounts = (accessToken: string) => Promise<readonly {
-    readonly accountId: string;
-    readonly label?: string;
-    readonly identity?: AccountIdentity;
-}[]>;
-
 declare interface ResolveTokenFailure {
     readonly ok: false;
     readonly reason: ResolveTokenFailureReason;
@@ -11688,30 +11706,6 @@ declare interface Usage {
     };
 }
 
-/** Validate freshly-entered material and resolve the provider account before persistence. */
-declare type ValidateApiKeyCredential = (input: ValidateApiKeyCredentialInput) => Promise<ValidateApiKeyCredentialResult>;
-
-declare interface ValidateApiKeyCredentialInput {
-    readonly accessToken: string;
-    /** Every declared field; empty for a classic single-secret scheme. */
-    readonly fields: Readonly<Record<string, string>>;
-    readonly signal: AbortSignal;
-}
-
-declare interface ValidateApiKeyCredentialResult {
-    readonly accountId: string;
-    readonly label?: string;
-    readonly identity?: AccountIdentity;
-    /** Non-secret observations the host may surface without retaining credential material. */
-    readonly capabilityChecks?: readonly ApiKeyCapabilityCheck[];
-}
-
-export declare type ValidatePluginApiKeyCredential = ValidateApiKeyCredential;
-
-export declare type ValidatePluginApiKeyCredentialInput = ValidateApiKeyCredentialInput;
-
-export declare type ValidatePluginApiKeyCredentialResult = ValidateApiKeyCredentialResult;
-
 /**
  * ---
  * responsibility: The one interface through which a vendored-MCP plugin's code calls a tool on its

package/dist/kay-app.d.ts

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

package/dist/skills.d.ts

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

package/dist/skills.js

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

package/package.json

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