@yaklabs-ai/plugin-sdk 0.27.0 → 0.28.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.0"
+    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.28.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.0" },
+  "compatibility": { "sdk": "^0.28.0" },
   "targets": {
     "kay": {
       "agent": {

package/THIRD-PARTY-INVENTORY.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@yaklabs-ai/plugin-sdk",
-  "version": "0.27.0",
+  "version": "0.28.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
@@ -2312,8 +2326,23 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * `write`. `app.approvals`, its `prepare`, `finalize` and `resolveResource` are gone, and a write can
  * refuse in the person's words with `UriProviderError.refusalMessage`. No plugin outside this repo
  * declared a card, so 0.26.3 stays served. A plugin that declares a card declares ^0.27.0.
+ *
+ * 0.27.1 lets a manifest URI module name the exact sign-in scheme its calls use, as a tool can
+ * (#14928): `authScheme`, a scheme of the module's `authService`, local or another plugin's. A
+ * 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.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.27.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.28.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -2691,16 +2720,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`).
-         */
-        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`
@@ -3324,6 +3349,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>;
 
@@ -4178,13 +4212,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";
@@ -4645,28 +4676,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>;
 
@@ -10207,26 +10216,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
@@ -2366,8 +2380,23 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * `write`. `app.approvals`, its `prepare`, `finalize` and `resolveResource` are gone, and a write can
  * refuse in the person's words with `UriProviderError.refusalMessage`. No plugin outside this repo
  * declared a card, so 0.26.3 stays served. A plugin that declares a card declares ^0.27.0.
+ *
+ * 0.27.1 lets a manifest URI module name the exact sign-in scheme its calls use, as a tool can
+ * (#14928): `authScheme`, a scheme of the module's `authService`, local or another plugin's. A
+ * 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.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.27.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.28.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -2742,16 +2771,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`).
-         */
-        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`
@@ -3375,6 +3400,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>;
 
@@ -4196,13 +4230,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";
@@ -4757,10 +4788,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">;
@@ -4789,8 +4817,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;
@@ -4831,7 +4858,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>;
@@ -5366,6 +5393,7 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
         schemes: z.ZodArray<z.ZodString>;
         displayName: z.ZodOptional<z.ZodString>;
         authServiceId: z.ZodOptional<z.ZodString>;
+        authSchemeId: z.ZodOptional<z.ZodString>;
         knownResources: z.ZodOptional<z.ZodLiteral<true>>;
         describesOperations: z.ZodOptional<z.ZodLiteral<true>>;
     }, z.core.$strict>>>;
@@ -5680,28 +5708,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;
@@ -11273,26 +11279,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
@@ -2641,8 +2655,23 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * `write`. `app.approvals`, its `prepare`, `finalize` and `resolveResource` are gone, and a write can
  * refuse in the person's words with `UriProviderError.refusalMessage`. No plugin outside this repo
  * declared a card, so 0.26.3 stays served. A plugin that declares a card declares ^0.27.0.
+ *
+ * 0.27.1 lets a manifest URI module name the exact sign-in scheme its calls use, as a tool can
+ * (#14928): `authScheme`, a scheme of the module's `authService`, local or another plugin's. A
+ * 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.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.27.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.28.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -3049,16 +3078,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`).
+         * 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`
@@ -3741,6 +3766,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>;
 
@@ -4815,13 +4849,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. */
@@ -5727,28 +5769,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;
@@ -11682,30 +11702,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

@@ -2612,8 +2612,23 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * `write`. `app.approvals`, its `prepare`, `finalize` and `resolveResource` are gone, and a write can
  * refuse in the person's words with `UriProviderError.refusalMessage`. No plugin outside this repo
  * declared a card, so 0.26.3 stays served. A plugin that declares a card declares ^0.27.0.
+ *
+ * 0.27.1 lets a manifest URI module name the exact sign-in scheme its calls use, as a tool can
+ * (#14928): `authScheme`, a scheme of the module's `authService`, local or another plugin's. A
+ * 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.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.27.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.28.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaklabs-ai/plugin-sdk",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "The Kay plugin SDK — types and helpers for authoring a Kay directory plugin.",
   "author": "YakLabs",
   "type": "module",