@yaklabs-ai/plugin-sdk 0.14.0 → 0.14.1

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.14.0"
+    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.14.1"
   }
 }
 ```
@@ -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.14.0" },
+  "compatibility": { "sdk": "^0.14.1" },
   "targets": {
     "kay": {
       "agent": {

package/THIRD-PARTY-INVENTORY.json

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

package/dist/kay-agent.d.ts

@@ -3254,6 +3254,7 @@ declare const KayPluginManifestV1: z.ZodObject<{
                     schemes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     operations: z.ZodArray<z.ZodEnum<{
                         status: "status";
+                        list: "list";
                         connect: "connect";
                         disconnect: "disconnect";
                         resolve: "resolve";
@@ -3348,6 +3349,7 @@ declare const KayPluginManifestV1: z.ZodObject<{
                     schemes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     operations: z.ZodArray<z.ZodEnum<{
                         status: "status";
+                        list: "list";
                         connect: "connect";
                         disconnect: "disconnect";
                         resolve: "resolve";
@@ -3442,6 +3444,7 @@ declare const KayPluginManifestV1: z.ZodObject<{
                     schemes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     operations: z.ZodArray<z.ZodEnum<{
                         status: "status";
+                        list: "list";
                         connect: "connect";
                         disconnect: "disconnect";
                         resolve: "resolve";
@@ -4277,9 +4280,10 @@ export declare interface OsascriptFailureAdvice {
 }
 
 /**
- * The activation options every osascript plugin's agent factory accepts
- * (`createAppleCalendarKayAgent(options)`), so the daemon's simulator roster sets each the same
- * way. Absent `simulator`, the plugin is exactly the shipped one.
+ * The activation options every osascript plugin's agent factory accepted, so the daemon's
+ * simulator roster set each the same way. Absent `simulator`, the plugin is exactly the shipped one.
+ *
+ * @deprecated See {@link OsascriptSimulatorOptions}.
  */
 export declare interface OsascriptKayAgentOptions {
     readonly simulator?: OsascriptSimulatorOptions;
@@ -4316,6 +4320,10 @@ export declare interface OsascriptRunner {
     /**
      * The runners a module's verbs use: the host's exactly when `simulator` is absent, or the
      * simulator's in its place, per dispatch, after the host's connection gate.
+     *
+     * @deprecated A Bonsai daemon substitutes the runner itself, so a module uses
+     * {@link requireExternalCli} and `ctx.auth?.externalCli` directly. Kept so a plugin built against
+     * an earlier SDK keeps compiling.
      */
     readonly dispatch: (simulator: OsascriptSimulatedRunner | undefined) => OsascriptDispatch;
     /**
@@ -4361,7 +4369,11 @@ export declare interface OsascriptRunnerOptions {
     readonly appNotRunning?: OsascriptFailureAdvice;
 }
 
-/** A plugin's simulator, as the runner sees it: the runner one dispatch uses in the host's place. */
+/**
+ * A simulated runner, as a module sees it: the runner one dispatch uses in the host's place. A
+ * Bonsai daemon that simulates an osascript plugin hands `runnerFor(ctx)` to the module as
+ * `ctx.auth.externalCli`; `@bonsai/uri-simulator-kit/osascript` builds one.
+ */
 export declare interface OsascriptSimulatedRunner {
     readonly runnerFor: (ctx: UriResolveContext) => UriExternalCliRunner;
 }
@@ -4370,6 +4382,10 @@ export declare interface OsascriptSimulatedRunner {
  * How a plugin is told to serve its module from its simulator instead of osascript: the one
  * option shape every osascript plugin's agent factory accepts as `simulator`. Only the daemon's
  * URI simulator roster sets it, for evals and dev; an ordinary install never does.
+ *
+ * @deprecated A Bonsai daemon now hands the module a simulated runner as `ctx.auth.externalCli`,
+ * so a plugin needs no simulator option; no Bonsai plugin sets this. Kept so a plugin built against
+ * an earlier SDK keeps compiling.
  */
 export declare interface OsascriptSimulatorOptions {
     /** The directory holding the simulator's world; the daemon's process config names it. */

package/dist/kay-app.d.ts

@@ -2093,6 +2093,23 @@ export declare interface KayAppAccountProfileUpdate {
     readonly displayName: string;
 }
 
+/** Owned services use local IDs; omitted scheme searches all admitted schemes. */
+export declare interface KayAppAccountRequest {
+    readonly serviceId: string;
+    readonly schemeId?: string;
+}
+
+/** Stored account state, without resolving or refreshing its credential. */
+export declare interface KayAppAccountSummary {
+    readonly accountId: string;
+    /** Global scheme ID, matching a resolved credential's schemeId. */
+    readonly schemeId: string;
+    readonly label?: string;
+    readonly scopes?: readonly string[];
+    /** Last recorded health; unknown means no health observation was stored. */
+    readonly status: "ok" | "needs_reauth" | "refresh_failed" | "revoked" | "unknown";
+}
+
 /**
  * A plugin's `kay.app` activation — receives only the brokered {@link KayAppPluginApi}. Runs ONCE at
  * host start, fully awaited before any session starts.
@@ -2343,22 +2360,20 @@ export declare interface KayAppAssistantMessageSessionEvent extends KayAppSessio
 
 /** The brokered credential capability. Present only when granted. */
 export declare interface KayAppAuth {
+    /** Resolve a granted credential for a declared purpose. */
+    resolve(request: KayAppResolveCredentialRequest): Promise<KayAppResolvedCredential>;
     /**
-     * Resolve the credential for a declared, granted service+scheme. Rejects when the grant is absent,
-     * the account is not connected, or the purpose is not one the service declared.
+     * Enumerate an owned service under an explicit list grant. Includes accounts needing repair.
+     * Never resolves, decrypts secret material, refreshes, or calls a provider. Invalid or
+     * unauthorized requests reject; an authorized service with no accounts returns an empty list.
      */
-    resolve(request: KayAppResolveCredentialRequest): Promise<KayAppResolvedCredential>;
+    listAccounts(request: KayAppAccountRequest): Promise<readonly KayAppAccountSummary[]>;
     /**
-     * Whether a credential is currently resolvable. Intended for availability-style probes a
-     * settings screen calls repeatedly.
-     *
-     * Answers `false` rather than throwing when nothing is connected, and never returns material to
-     * the caller. It does NOT yet answer without resolving: today it runs the full resolve internally
-     * and discards the result, so it can decrypt a secret — and, for a refreshable scheme, take the
-     * network — to produce a boolean. Do not read this as a cheap probe. Tracked in #1048; the fix is
-     * a `list`-scoped grant plus `listAccounts`, which answers from record metadata alone.
+     * Stored availability, not proof that a provider request will authenticate. False for no
+     * matching account or only revoked/needs-reauth accounts. Accepts list permission or existing
+     * resolve permission within its account bounds. Storage and authorization failures reject.
      */
-    has(request: Omit<KayAppResolveCredentialRequest, "purpose">): Promise<boolean>;
+    has(request: KayAppAccountRequest): Promise<boolean>;
 }
 
 /**
@@ -3887,7 +3902,7 @@ export declare interface KayAppPluginApi {
     readonly permissions?: KayAppPermissions;
     /**
      * Credential resolution for an auth service this plugin declares. PRESENT ONLY for plugins whose
-     * manifest wires `auth.operations: ["resolve"]` on this target (deny-by-default); `undefined`
+     * manifest wires `auth.operations` including `"list"` or `"resolve"` on this target (deny-by-default); `undefined`
      * otherwise. Auth is manifest WIRING (the host binds the credential vault before any code runs),
      * so its presence is declaration-driven, unlike the claim-checked capabilities above.
      */
@@ -4137,7 +4152,7 @@ export declare interface KayAppResolveCredentialRequest {
  * ## Deny-by-default
  *
  * `KayAppPluginApi.auth` is **present only for plugins the host grants** (`auth.operations`
- * containing `"resolve"` in `permissions.byTarget["kay.app"]`, against a service the manifest
+ * containing `"list"` or `"resolve"` in `permissions.byTarget["kay.app"]`, against a service the manifest
  * declares) and `undefined` otherwise — an ungranted plugin cannot even reference the capability.
  * This mirrors `KayAppPluginApi.corpus`, and it is the rule for every capability behind a grant:
  * never hand a plugin an object whose grant is decorative.

package/package.json

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