@yaklabs-ai/plugin-protocol 0.13.9 → 0.14.0

package/README.md

@@ -11,7 +11,7 @@ flow.
 ```json
 {
   "dependencies": {
-    "@bonsai/plugin-protocol": "npm:@yaklabs-ai/plugin-protocol@^0.13.9"
+    "@bonsai/plugin-protocol": "npm:@yaklabs-ai/plugin-protocol@^0.14.0"
   }
 }
 ```

package/THIRD-PARTY-INVENTORY.json

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

package/dist/index.d.ts

@@ -133,9 +133,9 @@ export declare type AppEventSubscription = z.infer<typeof AppEventSubscription>;
  * `kay.agent` registration seam only).
  */
 export declare const AppUriModuleContribution: z.ZodObject<{
+    displayName: z.ZodOptional<z.ZodString>;
     schemes: z.ZodArray<z.ZodString>;
     localId: z.ZodString;
-    displayName: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 
 export declare type AppUriModuleContribution = z.infer<typeof AppUriModuleContribution>;
@@ -1249,6 +1249,28 @@ export declare const AuthAccountSelector: z.ZodDiscriminatedUnion<[z.ZodObject<{
 
 export declare type AuthAccountSelector = z.infer<typeof AuthAccountSelector>;
 
+/**
+ * The product a person connects a shared identity through (SDK 0.13.10): a capability front door. A
+ * plugin that consumes another plugin's sign-in (Gmail consuming `google.account`) names the
+ * `service_connect` id and label its product is offered under, and connecting it expands the shared
+ * record with this grant's scopes instead of minting a credential of its own. The door owns no
+ * credential, so it is display data; the shared identity it expands is `auth.shared-identity`'s.
+ */
+export declare const AuthGrantFrontDoor: z.ZodObject<{
+    id: z.ZodString;
+    displayName: z.ZodString;
+    resourcePicker: z.ZodOptional<z.ZodObject<{
+        effect: z.ZodEnum<{
+            selection: "selection";
+            "resource-grant": "resource-grant";
+        }>;
+        mimeTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        successNote: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+
+export declare type AuthGrantFrontDoor = z.infer<typeof AuthGrantFrontDoor>;
+
 export declare const AuthGrantOperation: z.ZodEnum<{
     status: "status";
     connect: "connect";
@@ -1295,6 +1317,18 @@ export declare const AuthGrantRequest: z.ZodObject<{
         kind: z.ZodLiteral<"record-id">;
         recordId: z.ZodString;
     }, z.core.$strict>], "kind">>>;
+    frontDoor: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        displayName: z.ZodString;
+        resourcePicker: z.ZodOptional<z.ZodObject<{
+            effect: z.ZodEnum<{
+                selection: "selection";
+                "resource-grant": "resource-grant";
+            }>;
+            mimeTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            successNote: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 
 export declare type AuthGrantRequest = z.infer<typeof AuthGrantRequest>;
@@ -1435,8 +1469,8 @@ export declare type CliBinaryName = z.infer<typeof CliBinaryName>;
  *   only `external-cli` schemes. `buildCliBindingRoster` throws on either violation.
  *   What the binding still contributes is the read/write split (already ungated —
  *   classifier rows compose off the ungated roster) and, via the `external-cli`
- *   scheme's own `probeArgs`/`installHint`, a reachability probe the agent uses to
- *   decide whether to install the tool.
+ *   scheme's own connect facts (`cli.probe.args`, `cli.hints.install`), a reachability
+ *   probe the agent uses to decide whether to install the tool.
  *
  * Catalog membership is required for `vendored` and skipped for `path`; roster
  * uniqueness across every binary/alias applies to both.
@@ -1846,6 +1880,8 @@ export declare type FileExtensionToken = z.infer<typeof FileExtensionToken>;
  */
 export declare function finalizeArtifactProvenanceEnvelope(capture: ArtifactProvenanceCaptureContext, artifacts: readonly ArtifactProvenanceMutation[]): ArtifactProvenanceEnvelopeV1;
 
+export declare function findSkillSuggestionCitations(text: string, options?: SkillSuggestionEvidenceOptions): readonly SkillSuggestionCitation[];
+
 /**
  * The Basic-auth USERNAME a git host expects beside an injected token
  * (`x-access-token` for GitHub, `oauth2` for GitLab). The token is the password
@@ -2059,7 +2095,7 @@ export declare const KAY_EVENT_PUBLISHER_ID: "kay";
 declare const KAY_PLUGIN_COMPATIBILITY_REFUSAL_CODES: readonly ["unsupported-protocol", "sdk-range-unsatisfied", "sdk-range-unsupported", "host-sdk-version-invalid"];
 
 /** Released SDK contracts still implemented by the host, alongside its current SDK. */
-export declare const KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS: readonly ["0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.9.0", "0.9.1", "0.10.0", "0.11.0", "0.11.1", "0.12.0", "0.12.1", "0.12.2", "0.12.3", "0.12.4", "0.12.5", "0.13.0", "0.13.1", "0.13.2", "0.13.3", "0.13.4", "0.13.5", "0.13.6", "0.13.7", "0.13.8"];
+export declare const KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS: readonly ["0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.9.0", "0.9.1", "0.10.0", "0.11.0", "0.11.1", "0.12.0", "0.12.1", "0.12.2", "0.12.3", "0.12.4", "0.12.5", "0.13.0", "0.13.1", "0.13.2", "0.13.3", "0.13.4", "0.13.5", "0.13.6", "0.13.7", "0.13.8", "0.13.9", "0.13.10"];
 
 /** The file whose presence makes a directory a plugin. A directory without one is not a plugin. */
 export declare const KAY_PLUGIN_MANIFEST_FILENAME = "kay-plugin.json";
@@ -2365,8 +2401,26 @@ export declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * code a `kay.ui` page also loads (`kay-agent` exports the same `z`). Additive: a plugin compiled
  * against 0.13.8 never imports it. A plugin that imports it declares `^0.13.9`, so an older host
  * refuses a directory or repository plugin at load instead of the import failing.
+ *
+ * 0.13.10 adds two optional manifest fields. An `external-cli` auth scheme's `cli` says how the host
+ * connects it (the binary, its probe and sign-in argv, the hints, the install command), which the
+ * host read from its own tables before. An auth grant's `frontDoor` names the product a person
+ * connects a shared identity through (`gmail` over `google.account`), with an optional file picker.
+ * Additive: a manifest without them parses unchanged. A plugin that declares one declares
+ * `^0.13.10`, so an older host refuses it at load with that reason rather than a schema error.
+ *
+ * 0.14.0 removes `withJev`: `api.withJev` on `kay.agent`, `app.withJev` on `kay.app`, the
+ * `@bonsai/plugin-sdk/jev` subpath and every `Jev*` type it exported. A plugin uses `api.systemOne`
+ * / `app.systemOne` (`@bonsai/plugin-sdk/system-one`) instead. The `jev.use` capability claim is
+ * renamed `systemOne.use`, and stored grants are rewritten to the new slug. The signals subpath
+ * types its own surface now: observe options by `KayAppSignalObserveOptions`, state by
+ * `KayAppSignalState`, and questions and answers by `DecideQuestions` and `DecideAnswer`. For the
+ * api surface this is a clean break with no shim and deliberately NOT a load refusal, like 0.13.0:
+ * every earlier release stays in the retention list, so a plugin compiled against 0.13.x that
+ * reads `api.withJev` gets `undefined` at the call, and one that imports a value from
+ * `@bonsai/plugin-sdk/jev` fails at load. No plugin used either.
  */
-export declare const KAY_PLUGIN_SDK_VERSION: "0.13.9";
+export declare const KAY_PLUGIN_SDK_VERSION: "0.14.0";
 
 export declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -2529,9 +2583,9 @@ export declare const KayAppTargetManifest: z.ZodObject<{
             responseSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>>;
         }, z.core.$strict>>>;
         uriModules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            displayName: z.ZodOptional<z.ZodString>;
             schemes: z.ZodArray<z.ZodString>;
             localId: z.ZodString;
-            displayName: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>>;
         dataSources: z.ZodOptional<z.ZodArray<z.ZodObject<{
             localId: z.ZodString;
@@ -2911,9 +2965,9 @@ export declare const KayPluginManifestV1: z.ZodObject<{
                         responseSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>>;
                     }, z.core.$strict>>>;
                     uriModules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        displayName: z.ZodOptional<z.ZodString>;
                         schemes: z.ZodArray<z.ZodString>;
                         localId: z.ZodString;
-                        displayName: z.ZodOptional<z.ZodString>;
                     }, z.core.$strict>>>;
                     dataSources: z.ZodOptional<z.ZodArray<z.ZodObject<{
                         localId: z.ZodString;
@@ -3254,6 +3308,26 @@ export declare const KayPluginManifestV1: z.ZodObject<{
                 localId: z.ZodString;
                 kind: z.ZodLiteral<"external-cli">;
                 scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                cli: z.ZodOptional<z.ZodObject<{
+                    binary: z.ZodString;
+                    probe: z.ZodObject<{
+                        args: z.ZodArray<z.ZodString>;
+                        timeoutMs: z.ZodOptional<z.ZodNumber>;
+                        signedOutMarker: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strict>;
+                    login: z.ZodOptional<z.ZodObject<{
+                        args: z.ZodArray<z.ZodString>;
+                        timeoutMs: z.ZodOptional<z.ZodNumber>;
+                    }, z.core.$strict>>;
+                    install: z.ZodOptional<z.ZodObject<{
+                        command: z.ZodString;
+                        args: z.ZodArray<z.ZodString>;
+                    }, z.core.$strict>>;
+                    hints: z.ZodObject<{
+                        install: z.ZodString;
+                        login: z.ZodString;
+                    }, z.core.$strict>;
+                }, z.core.$strict>>;
                 displayName: z.ZodOptional<z.ZodString>;
                 agentHint: z.ZodOptional<z.ZodString>;
                 summary: z.ZodOptional<z.ZodString>;
@@ -3321,6 +3395,18 @@ export declare const KayPluginManifestV1: z.ZodObject<{
                         kind: z.ZodLiteral<"record-id">;
                         recordId: z.ZodString;
                     }, z.core.$strict>], "kind">>>;
+                    frontDoor: z.ZodOptional<z.ZodObject<{
+                        id: z.ZodString;
+                        displayName: z.ZodString;
+                        resourcePicker: z.ZodOptional<z.ZodObject<{
+                            effect: z.ZodEnum<{
+                                selection: "selection";
+                                "resource-grant": "resource-grant";
+                            }>;
+                            mimeTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                            successNote: z.ZodOptional<z.ZodString>;
+                        }, z.core.$strict>>;
+                    }, z.core.$strict>>;
                 }, z.core.$strict>>>;
                 storage: z.ZodOptional<z.ZodArray<z.ZodObject<{
                     kind: z.ZodEnum<{
@@ -3403,6 +3489,18 @@ export declare const KayPluginManifestV1: z.ZodObject<{
                         kind: z.ZodLiteral<"record-id">;
                         recordId: z.ZodString;
                     }, z.core.$strict>], "kind">>>;
+                    frontDoor: z.ZodOptional<z.ZodObject<{
+                        id: z.ZodString;
+                        displayName: z.ZodString;
+                        resourcePicker: z.ZodOptional<z.ZodObject<{
+                            effect: z.ZodEnum<{
+                                selection: "selection";
+                                "resource-grant": "resource-grant";
+                            }>;
+                            mimeTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                            successNote: z.ZodOptional<z.ZodString>;
+                        }, z.core.$strict>>;
+                    }, z.core.$strict>>;
                 }, z.core.$strict>>>;
                 storage: z.ZodOptional<z.ZodArray<z.ZodObject<{
                     kind: z.ZodEnum<{
@@ -3485,6 +3583,18 @@ export declare const KayPluginManifestV1: z.ZodObject<{
                         kind: z.ZodLiteral<"record-id">;
                         recordId: z.ZodString;
                     }, z.core.$strict>], "kind">>>;
+                    frontDoor: z.ZodOptional<z.ZodObject<{
+                        id: z.ZodString;
+                        displayName: z.ZodString;
+                        resourcePicker: z.ZodOptional<z.ZodObject<{
+                            effect: z.ZodEnum<{
+                                selection: "selection";
+                                "resource-grant": "resource-grant";
+                            }>;
+                            mimeTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                            successNote: z.ZodOptional<z.ZodString>;
+                        }, z.core.$strict>>;
+                    }, z.core.$strict>>;
                 }, z.core.$strict>>>;
                 storage: z.ZodOptional<z.ZodArray<z.ZodObject<{
                     kind: z.ZodEnum<{
@@ -3965,7 +4075,7 @@ export declare function parseResolvedPluginContractV1(value: unknown): ResolvedP
 export declare function parseSemver(value: string): ParsedSemver | undefined;
 
 /** Every capability slug {@link PluginCapabilityClaimV1} can express, for exhaustive table checks. */
-export declare const PLUGIN_CAPABILITY_SLUGS: readonly ["sessions.run", "network.connect", "web-session.request", "web-session.download", "process.spawn", "corpus.read", "signals.read", "skills.read", "tools.describe", "workspace.command", "sessions.create", "sessions.update", "models.complete", "jev.use", "automations.write", "automations.run", "workflows.define", "session-events.subscribe", "agents.run", "dynamic-context.register", "app-data.register", "account.assert", "account.update", "agents.permissions", "tool-interception.register", "interaction.surface", "config.declare-section", "auth.own-service", "auth.shared-identity", "cli.bind", "mcp.host-server", "prompt.resident", "skills.declared-source", "whiteboard.discover", "whiteboard.read", "whiteboard.create", "whiteboard.update", "whiteboard.remove"];
+export declare const PLUGIN_CAPABILITY_SLUGS: readonly ["sessions.run", "network.connect", "web-session.request", "web-session.download", "process.spawn", "corpus.read", "signals.read", "skills.read", "tools.describe", "workspace.command", "sessions.create", "sessions.update", "models.complete", "systemOne.use", "automations.write", "automations.run", "workflows.define", "session-events.subscribe", "agents.run", "dynamic-context.register", "app-data.register", "account.assert", "account.update", "agents.permissions", "tool-interception.register", "interaction.surface", "config.declare-section", "auth.own-service", "auth.shared-identity", "cli.bind", "mcp.host-server", "prompt.resident", "skills.declared-source", "whiteboard.discover", "whiteboard.read", "whiteboard.create", "whiteboard.update", "whiteboard.remove"];
 
 /** Diagnostic messages carry plugin-controlled text (parse errors, module errors); bound it so a
  *  hostile or accidental multi-megabyte error can never blow up a log line or a render surface. */
@@ -4095,6 +4205,26 @@ export declare const PluginAuthManifest: z.ZodObject<{
             localId: z.ZodString;
             kind: z.ZodLiteral<"external-cli">;
             scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            cli: z.ZodOptional<z.ZodObject<{
+                binary: z.ZodString;
+                probe: z.ZodObject<{
+                    args: z.ZodArray<z.ZodString>;
+                    timeoutMs: z.ZodOptional<z.ZodNumber>;
+                    signedOutMarker: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>;
+                login: z.ZodOptional<z.ZodObject<{
+                    args: z.ZodArray<z.ZodString>;
+                    timeoutMs: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strict>>;
+                install: z.ZodOptional<z.ZodObject<{
+                    command: z.ZodString;
+                    args: z.ZodArray<z.ZodString>;
+                }, z.core.$strict>>;
+                hints: z.ZodObject<{
+                    install: z.ZodString;
+                    login: z.ZodString;
+                }, z.core.$strict>;
+            }, z.core.$strict>>;
             displayName: z.ZodOptional<z.ZodString>;
             agentHint: z.ZodOptional<z.ZodString>;
             summary: z.ZodOptional<z.ZodString>;
@@ -4206,6 +4336,26 @@ export declare const PluginAuthScheme: z.ZodDiscriminatedUnion<[z.ZodDiscriminat
     localId: z.ZodString;
     kind: z.ZodLiteral<"external-cli">;
     scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    cli: z.ZodOptional<z.ZodObject<{
+        binary: z.ZodString;
+        probe: z.ZodObject<{
+            args: z.ZodArray<z.ZodString>;
+            timeoutMs: z.ZodOptional<z.ZodNumber>;
+            signedOutMarker: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        login: z.ZodOptional<z.ZodObject<{
+            args: z.ZodArray<z.ZodString>;
+            timeoutMs: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        install: z.ZodOptional<z.ZodObject<{
+            command: z.ZodString;
+            args: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+        hints: z.ZodObject<{
+            install: z.ZodString;
+            login: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
     displayName: z.ZodOptional<z.ZodString>;
     agentHint: z.ZodOptional<z.ZodString>;
     summary: z.ZodOptional<z.ZodString>;
@@ -4297,6 +4447,26 @@ export declare const PluginAuthService: z.ZodObject<{
         localId: z.ZodString;
         kind: z.ZodLiteral<"external-cli">;
         scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        cli: z.ZodOptional<z.ZodObject<{
+            binary: z.ZodString;
+            probe: z.ZodObject<{
+                args: z.ZodArray<z.ZodString>;
+                timeoutMs: z.ZodOptional<z.ZodNumber>;
+                signedOutMarker: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            login: z.ZodOptional<z.ZodObject<{
+                args: z.ZodArray<z.ZodString>;
+                timeoutMs: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>>;
+            install: z.ZodOptional<z.ZodObject<{
+                command: z.ZodString;
+                args: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>>;
+            hints: z.ZodObject<{
+                install: z.ZodString;
+                login: z.ZodString;
+            }, z.core.$strict>;
+        }, z.core.$strict>>;
         displayName: z.ZodOptional<z.ZodString>;
         agentHint: z.ZodOptional<z.ZodString>;
         summary: z.ZodOptional<z.ZodString>;
@@ -4422,7 +4592,7 @@ export declare const PluginCapabilityClaimV1: z.ZodDiscriminatedUnion<[z.ZodObje
     envelope: z.ZodObject<{}, z.core.$strict>;
 }, z.core.$strict>, z.ZodObject<{
     target: z.ZodLiteral<"kay.app">;
-    slug: z.ZodLiteral<"jev.use">;
+    slug: z.ZodLiteral<"systemOne.use">;
     envelope: z.ZodObject<{}, z.core.$strict>;
 }, z.core.$strict>, z.ZodObject<{
     target: z.ZodLiteral<"kay.app">;
@@ -4658,7 +4828,7 @@ export declare const PluginCapabilityDecisionV1: z.ZodDiscriminatedUnion<[z.ZodO
         envelope: z.ZodObject<{}, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         target: z.ZodLiteral<"kay.app">;
-        slug: z.ZodLiteral<"jev.use">;
+        slug: z.ZodLiteral<"systemOne.use">;
         envelope: z.ZodObject<{}, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         target: z.ZodLiteral<"kay.app">;
@@ -4889,7 +5059,7 @@ export declare const PluginCapabilityDecisionV1: z.ZodDiscriminatedUnion<[z.ZodO
             envelope: z.ZodObject<{}, z.core.$strict>;
         }, z.core.$strict>, z.ZodObject<{
             target: z.ZodLiteral<"kay.app">;
-            slug: z.ZodLiteral<"jev.use">;
+            slug: z.ZodLiteral<"systemOne.use">;
             envelope: z.ZodObject<{}, z.core.$strict>;
         }, z.core.$strict>, z.ZodObject<{
             target: z.ZodLiteral<"kay.app">;
@@ -5183,7 +5353,7 @@ export declare const PluginCapabilityRefusalV1: z.ZodObject<{
         envelope: z.ZodObject<{}, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         target: z.ZodLiteral<"kay.app">;
-        slug: z.ZodLiteral<"jev.use">;
+        slug: z.ZodLiteral<"systemOne.use">;
         envelope: z.ZodObject<{}, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         target: z.ZodLiteral<"kay.app">;
@@ -5453,6 +5623,39 @@ export declare const PluginEventDefinitionContribution: z.ZodObject<{
 
 export declare type PluginEventDefinitionContribution = z.infer<typeof PluginEventDefinitionContribution>;
 
+/**
+ * How the host connects an `external-cli` scheme (SDK 0.13.10). Bonsai reads it for its own plugins
+ * only; any other plugin's is ignored, with a load diagnostic.
+ *
+ * Connecting runs `binary probe.args`, and a zero exit is the connection. A failed probe surfaces the
+ * hints, and when `login` is declared and the failure carries `probe.signedOutMarker`, connect hands
+ * the sign-in to the CLI itself (`binary login.args`, which opens the CLI's own browser flow) and
+ * probes again. The credential stays in the CLI's own store; the host records only that the probe
+ * passed. Each `timeoutMs` is a budget the host enforces and may clamp to a shorter one.
+ */
+export declare const PluginExternalCliConnect: z.ZodObject<{
+    binary: z.ZodString;
+    probe: z.ZodObject<{
+        args: z.ZodArray<z.ZodString>;
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+        signedOutMarker: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    login: z.ZodOptional<z.ZodObject<{
+        args: z.ZodArray<z.ZodString>;
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    install: z.ZodOptional<z.ZodObject<{
+        command: z.ZodString;
+        args: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    hints: z.ZodObject<{
+        install: z.ZodString;
+        login: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+
+export declare type PluginExternalCliConnect = z.infer<typeof PluginExternalCliConnect>;
+
 /**
  * How a plugin icon asks to be drawn.
  *
@@ -5623,6 +5826,18 @@ export declare const PluginPermissionManifest: z.ZodObject<{
                     kind: z.ZodLiteral<"record-id">;
                     recordId: z.ZodString;
                 }, z.core.$strict>], "kind">>>;
+                frontDoor: z.ZodOptional<z.ZodObject<{
+                    id: z.ZodString;
+                    displayName: z.ZodString;
+                    resourcePicker: z.ZodOptional<z.ZodObject<{
+                        effect: z.ZodEnum<{
+                            selection: "selection";
+                            "resource-grant": "resource-grant";
+                        }>;
+                        mimeTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                        successNote: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strict>>;
+                }, z.core.$strict>>;
             }, z.core.$strict>>>;
             storage: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 kind: z.ZodEnum<{
@@ -5705,6 +5920,18 @@ export declare const PluginPermissionManifest: z.ZodObject<{
                     kind: z.ZodLiteral<"record-id">;
                     recordId: z.ZodString;
                 }, z.core.$strict>], "kind">>>;
+                frontDoor: z.ZodOptional<z.ZodObject<{
+                    id: z.ZodString;
+                    displayName: z.ZodString;
+                    resourcePicker: z.ZodOptional<z.ZodObject<{
+                        effect: z.ZodEnum<{
+                            selection: "selection";
+                            "resource-grant": "resource-grant";
+                        }>;
+                        mimeTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                        successNote: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strict>>;
+                }, z.core.$strict>>;
             }, z.core.$strict>>>;
             storage: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 kind: z.ZodEnum<{
@@ -5787,6 +6014,18 @@ export declare const PluginPermissionManifest: z.ZodObject<{
                     kind: z.ZodLiteral<"record-id">;
                     recordId: z.ZodString;
                 }, z.core.$strict>], "kind">>>;
+                frontDoor: z.ZodOptional<z.ZodObject<{
+                    id: z.ZodString;
+                    displayName: z.ZodString;
+                    resourcePicker: z.ZodOptional<z.ZodObject<{
+                        effect: z.ZodEnum<{
+                            selection: "selection";
+                            "resource-grant": "resource-grant";
+                        }>;
+                        mimeTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                        successNote: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strict>>;
+                }, z.core.$strict>>;
             }, z.core.$strict>>>;
             storage: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 kind: z.ZodEnum<{
@@ -6165,6 +6404,15 @@ export declare const RegistrableDomain: z.ZodString;
 
 export declare type RegistrableDomain = z.infer<typeof RegistrableDomain>;
 
+/**
+ * Capability slugs renamed since release, old slug to new. A stored grant naming an old slug is
+ * rewritten to the new one (a read folds it; the boot migration rewrites the stored row), never
+ * ignored: unlike a retired slug it still confers the capability.
+ */
+export declare const RENAMED_PLUGIN_CAPABILITY_SLUGS: {
+    readonly "jev.use": "systemOne.use";
+};
+
 /**
  * Id namespaces a directory plugin may never claim. `herd.` is the kernel's first-party namespace
  * (`HERD_RESERVED_ID_PREFIX`: the kernel's extension loader throws on it without a first-party
@@ -6218,6 +6466,18 @@ export declare const ResolvedAuthGrantRequest: z.ZodObject<{
         description: z.ZodString;
         documentationUrl: z.ZodOptional<z.ZodURL>;
     }, z.core.$strict>>>;
+    frontDoor: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        displayName: z.ZodString;
+        resourcePicker: z.ZodOptional<z.ZodObject<{
+            effect: z.ZodEnum<{
+                selection: "selection";
+                "resource-grant": "resource-grant";
+            }>;
+            mimeTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            successNote: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
     service: z.ZodString;
     schemes: z.ZodOptional<z.ZodArray<z.ZodString>>;
     accountSelectors: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -6585,6 +6845,26 @@ export declare const ResolvedPluginAuthScheme: z.ZodDiscriminatedUnion<[z.ZodDis
     globalId: z.ZodString;
     kind: z.ZodLiteral<"external-cli">;
     scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    cli: z.ZodOptional<z.ZodObject<{
+        binary: z.ZodString;
+        probe: z.ZodObject<{
+            args: z.ZodArray<z.ZodString>;
+            timeoutMs: z.ZodOptional<z.ZodNumber>;
+            signedOutMarker: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        login: z.ZodOptional<z.ZodObject<{
+            args: z.ZodArray<z.ZodString>;
+            timeoutMs: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        install: z.ZodOptional<z.ZodObject<{
+            command: z.ZodString;
+            args: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+        hints: z.ZodObject<{
+            install: z.ZodString;
+            login: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
     displayName: z.ZodOptional<z.ZodString>;
     agentHint: z.ZodOptional<z.ZodString>;
     summary: z.ZodOptional<z.ZodString>;
@@ -6692,6 +6972,26 @@ export declare const ResolvedPluginAuthService: z.ZodObject<{
         globalId: z.ZodString;
         kind: z.ZodLiteral<"external-cli">;
         scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        cli: z.ZodOptional<z.ZodObject<{
+            binary: z.ZodString;
+            probe: z.ZodObject<{
+                args: z.ZodArray<z.ZodString>;
+                timeoutMs: z.ZodOptional<z.ZodNumber>;
+                signedOutMarker: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            login: z.ZodOptional<z.ZodObject<{
+                args: z.ZodArray<z.ZodString>;
+                timeoutMs: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>>;
+            install: z.ZodOptional<z.ZodObject<{
+                command: z.ZodString;
+                args: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>>;
+            hints: z.ZodObject<{
+                install: z.ZodString;
+                login: z.ZodString;
+            }, z.core.$strict>;
+        }, z.core.$strict>>;
         displayName: z.ZodOptional<z.ZodString>;
         agentHint: z.ZodOptional<z.ZodString>;
         summary: z.ZodOptional<z.ZodString>;
@@ -6861,6 +7161,26 @@ export declare const ResolvedPluginContractV1: z.ZodObject<{
             globalId: z.ZodString;
             kind: z.ZodLiteral<"external-cli">;
             scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            cli: z.ZodOptional<z.ZodObject<{
+                binary: z.ZodString;
+                probe: z.ZodObject<{
+                    args: z.ZodArray<z.ZodString>;
+                    timeoutMs: z.ZodOptional<z.ZodNumber>;
+                    signedOutMarker: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>;
+                login: z.ZodOptional<z.ZodObject<{
+                    args: z.ZodArray<z.ZodString>;
+                    timeoutMs: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strict>>;
+                install: z.ZodOptional<z.ZodObject<{
+                    command: z.ZodString;
+                    args: z.ZodArray<z.ZodString>;
+                }, z.core.$strict>>;
+                hints: z.ZodObject<{
+                    install: z.ZodString;
+                    login: z.ZodString;
+                }, z.core.$strict>;
+            }, z.core.$strict>>;
             displayName: z.ZodOptional<z.ZodString>;
             agentHint: z.ZodOptional<z.ZodString>;
             summary: z.ZodOptional<z.ZodString>;
@@ -6916,6 +7236,18 @@ export declare const ResolvedPluginContractV1: z.ZodObject<{
                         description: z.ZodString;
                         documentationUrl: z.ZodOptional<z.ZodURL>;
                     }, z.core.$strict>>>;
+                    frontDoor: z.ZodOptional<z.ZodObject<{
+                        id: z.ZodString;
+                        displayName: z.ZodString;
+                        resourcePicker: z.ZodOptional<z.ZodObject<{
+                            effect: z.ZodEnum<{
+                                selection: "selection";
+                                "resource-grant": "resource-grant";
+                            }>;
+                            mimeTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                            successNote: z.ZodOptional<z.ZodString>;
+                        }, z.core.$strict>>;
+                    }, z.core.$strict>>;
                     service: z.ZodString;
                     schemes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     accountSelectors: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -6998,6 +7330,18 @@ export declare const ResolvedPluginContractV1: z.ZodObject<{
                         description: z.ZodString;
                         documentationUrl: z.ZodOptional<z.ZodURL>;
                     }, z.core.$strict>>>;
+                    frontDoor: z.ZodOptional<z.ZodObject<{
+                        id: z.ZodString;
+                        displayName: z.ZodString;
+                        resourcePicker: z.ZodOptional<z.ZodObject<{
+                            effect: z.ZodEnum<{
+                                selection: "selection";
+                                "resource-grant": "resource-grant";
+                            }>;
+                            mimeTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                            successNote: z.ZodOptional<z.ZodString>;
+                        }, z.core.$strict>>;
+                    }, z.core.$strict>>;
                     service: z.ZodString;
                     schemes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     accountSelectors: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -7080,6 +7424,18 @@ export declare const ResolvedPluginContractV1: z.ZodObject<{
                         description: z.ZodString;
                         documentationUrl: z.ZodOptional<z.ZodURL>;
                     }, z.core.$strict>>>;
+                    frontDoor: z.ZodOptional<z.ZodObject<{
+                        id: z.ZodString;
+                        displayName: z.ZodString;
+                        resourcePicker: z.ZodOptional<z.ZodObject<{
+                            effect: z.ZodEnum<{
+                                selection: "selection";
+                                "resource-grant": "resource-grant";
+                            }>;
+                            mimeTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                            successNote: z.ZodOptional<z.ZodString>;
+                        }, z.core.$strict>>;
+                    }, z.core.$strict>>;
                     service: z.ZodString;
                     schemes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     accountSelectors: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -7401,6 +7757,18 @@ export declare const ResolvedPluginGrants: z.ZodObject<{
                     description: z.ZodString;
                     documentationUrl: z.ZodOptional<z.ZodURL>;
                 }, z.core.$strict>>>;
+                frontDoor: z.ZodOptional<z.ZodObject<{
+                    id: z.ZodString;
+                    displayName: z.ZodString;
+                    resourcePicker: z.ZodOptional<z.ZodObject<{
+                        effect: z.ZodEnum<{
+                            selection: "selection";
+                            "resource-grant": "resource-grant";
+                        }>;
+                        mimeTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                        successNote: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strict>>;
+                }, z.core.$strict>>;
                 service: z.ZodString;
                 schemes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 accountSelectors: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -7483,6 +7851,18 @@ export declare const ResolvedPluginGrants: z.ZodObject<{
                     description: z.ZodString;
                     documentationUrl: z.ZodOptional<z.ZodURL>;
                 }, z.core.$strict>>>;
+                frontDoor: z.ZodOptional<z.ZodObject<{
+                    id: z.ZodString;
+                    displayName: z.ZodString;
+                    resourcePicker: z.ZodOptional<z.ZodObject<{
+                        effect: z.ZodEnum<{
+                            selection: "selection";
+                            "resource-grant": "resource-grant";
+                        }>;
+                        mimeTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                        successNote: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strict>>;
+                }, z.core.$strict>>;
                 service: z.ZodString;
                 schemes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 accountSelectors: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -7565,6 +7945,18 @@ export declare const ResolvedPluginGrants: z.ZodObject<{
                     description: z.ZodString;
                     documentationUrl: z.ZodOptional<z.ZodURL>;
                 }, z.core.$strict>>>;
+                frontDoor: z.ZodOptional<z.ZodObject<{
+                    id: z.ZodString;
+                    displayName: z.ZodString;
+                    resourcePicker: z.ZodOptional<z.ZodObject<{
+                        effect: z.ZodEnum<{
+                            selection: "selection";
+                            "resource-grant": "resource-grant";
+                        }>;
+                        mimeTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                        successNote: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strict>>;
+                }, z.core.$strict>>;
                 service: z.ZodString;
                 schemes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 accountSelectors: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -7754,6 +8146,18 @@ export declare const ResolvedTargetGrantSet: z.ZodObject<{
             description: z.ZodString;
             documentationUrl: z.ZodOptional<z.ZodURL>;
         }, z.core.$strict>>>;
+        frontDoor: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            displayName: z.ZodString;
+            resourcePicker: z.ZodOptional<z.ZodObject<{
+                effect: z.ZodEnum<{
+                    selection: "selection";
+                    "resource-grant": "resource-grant";
+                }>;
+                mimeTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                successNote: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
         service: z.ZodString;
         schemes: z.ZodOptional<z.ZodArray<z.ZodString>>;
         accountSelectors: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -8396,6 +8800,44 @@ export declare const SkillContribution: z.ZodObject<{
 
 export declare type SkillContribution = z.infer<typeof SkillContribution>;
 
+export declare interface SkillSuggestionCitation {
+    readonly start: number;
+    readonly end: number;
+    readonly ref: SkillSuggestionEvidenceRef;
+}
+
+export declare type SkillSuggestionEvidenceItem = SkillSuggestionEvidenceRef | {
+    readonly kind: "text";
+    readonly text: string;
+};
+
+export declare function skillSuggestionEvidenceItems(evidence: unknown, options?: SkillSuggestionEvidenceOptions): readonly SkillSuggestionEvidenceItem[];
+
+export declare function skillSuggestionEvidenceKey(item: SkillSuggestionEvidenceItem): string;
+
+export declare interface SkillSuggestionEvidenceOptions {
+    readonly sessionIds?: readonly string[];
+}
+
+export declare type SkillSuggestionEvidenceRef = {
+    readonly kind: "message";
+    readonly sessionId: string;
+    readonly entryId: string;
+    readonly raw: string;
+} | {
+    readonly kind: "session";
+    readonly sessionId: string;
+    readonly raw: string;
+} | {
+    readonly kind: "friction";
+    readonly reference: string;
+    readonly raw: string;
+} | {
+    readonly kind: "uri";
+    readonly uri: string;
+    readonly raw: string;
+};
+
 export declare const StorageGrantRequest: z.ZodObject<{
     kind: z.ZodEnum<{
         sqlite: "sqlite";
@@ -8463,6 +8905,18 @@ export declare const TargetPermissionSet: z.ZodPreprocess<z.ZodObject<{
             kind: z.ZodLiteral<"record-id">;
             recordId: z.ZodString;
         }, z.core.$strict>], "kind">>>;
+        frontDoor: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            displayName: z.ZodString;
+            resourcePicker: z.ZodOptional<z.ZodObject<{
+                effect: z.ZodEnum<{
+                    selection: "selection";
+                    "resource-grant": "resource-grant";
+                }>;
+                mimeTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                successNote: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
     }, z.core.$strict>>>;
     storage: z.ZodOptional<z.ZodArray<z.ZodObject<{
         kind: z.ZodEnum<{
@@ -8577,6 +9031,18 @@ export declare const TargetPermissionWiring: z.ZodObject<{
             kind: z.ZodLiteral<"record-id">;
             recordId: z.ZodString;
         }, z.core.$strict>], "kind">>>;
+        frontDoor: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            displayName: z.ZodString;
+            resourcePicker: z.ZodOptional<z.ZodObject<{
+                effect: z.ZodEnum<{
+                    selection: "selection";
+                    "resource-grant": "resource-grant";
+                }>;
+                mimeTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                successNote: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
     }, z.core.$strict>>>;
     storage: z.ZodOptional<z.ZodArray<z.ZodObject<{
         kind: z.ZodEnum<{

package/dist/index.js

@@ -136,7 +136,7 @@ var JsonSchema = z2.record(z2.string(), JsonValue);
 // packages/plugin-protocol/dist/common.js
 var KAY_PLUGIN_PROTOCOL_VERSION = "kay.plugin.v1";
 var KAY_PLUGIN_PROTOCOL_PACKAGE_NAME = "@bonsai/plugin-protocol";
-var KAY_PLUGIN_SDK_VERSION = "0.13.9";
+var KAY_PLUGIN_SDK_VERSION = "0.14.0";
 var KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS = [
   "0.8.0",
   "0.8.1",
@@ -163,7 +163,9 @@ var KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS = [
   "0.13.5",
   "0.13.6",
   "0.13.7",
-  "0.13.8"
+  "0.13.8",
+  "0.13.9",
+  "0.13.10"
 ];
 var KAY_PLUGIN_TARGET_NAMES = [
   "kay.agent",
@@ -1093,6 +1095,31 @@ import { z as z8 } from "zod";
 
 // packages/plugin-protocol/dist/permissions.js
 import { z as z7 } from "zod";
+
+// packages/plugin-protocol/dist/ids.js
+function resolvePluginNamespace(pluginId, namespace) {
+  return namespace ?? pluginId;
+}
+function resolveGlobalContributionId(namespace, localId) {
+  return `${namespace}.${localId}`;
+}
+function deriveDirectoryPluginToolName(namespace, localId) {
+  return `${namespace.replaceAll(".", "_")}_${localId}`;
+}
+function resolvePluginEventType(namespace, localId) {
+  return resolveGlobalContributionId(namespace, localId);
+}
+function isQualifiedAuthServiceRef(ref) {
+  return ref.includes(".");
+}
+function isQualifiedAuthSchemeRef(ref) {
+  return ref.includes(".");
+}
+function resolveAdapterId(globalId, declaredAdapterId) {
+  return declaredAdapterId ?? globalId;
+}
+
+// packages/plugin-protocol/dist/permissions.js
 var AuthGrantOperation = z7.enum([
   "status",
   "connect",
@@ -1121,6 +1148,26 @@ var ScopeRequirement = z7.strictObject({
   purpose: NonEmptyString,
   alternatives: z7.array(ScopeAlternative).min(1)
 });
+var AuthGrantFrontDoor = z7.strictObject({
+  /**
+   * The door id: the id `service_connect` takes (`gmail`). Never a registered auth service's id, and
+   * not the grant's `service`, which names the shared sign-in the door expands.
+   */
+  id: LocalContributionId,
+  displayName: NonEmptyString.max(120),
+  /**
+   * A file picker the connect runs. `resource-grant`: the scope reaches only picked files, so a
+   * first connect chains into a pick. `selection`: the scope already reaches every file of the
+   * type, and the pick only records which ones the person meant.
+   */
+  resourcePicker: z7.strictObject({
+    effect: z7.enum(["selection", "resource-grant"]),
+    /** The file types the picker offers. */
+    mimeTypes: z7.array(NonEmptyString.max(255)).min(1).max(32).optional(),
+    /** What the agent is told about the picked set once the pick lands. */
+    successNote: NonEmptyString.max(2048).optional()
+  }).optional()
+});
 var AuthGrantRequestBase = z7.strictObject({
   // A local (undotted) service must be declared in this same manifest; a
   // qualified (dotted) service names another plugin's global id and is an
@@ -1145,9 +1192,17 @@ var AuthGrantRequestBase = z7.strictObject({
   connectScopes: z7.array(NonEmptyString).min(1).optional(),
   scopeRequirement: ScopeRequirement.optional(),
   scopeDefinitions: z7.array(AuthScopeDefinition).min(1).optional(),
-  accountSelectors: z7.array(AuthAccountSelector).min(1).optional()
+  accountSelectors: z7.array(AuthAccountSelector).min(1).optional(),
+  frontDoor: AuthGrantFrontDoor.optional()
 });
 function validateAuthGrantRequest(grant, ctx) {
+  if (grant.frontDoor !== void 0 && !isQualifiedAuthServiceRef(grant.service)) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["frontDoor"],
+      message: "frontDoor needs a shared service (a qualified ref such as google.account): a door expands another plugin's sign-in"
+    });
+  }
   if (grant.allowedScopes !== void 0 && grant.requiredScopes !== void 0) {
     ctx.addIssue({
       code: "custom",
@@ -1590,16 +1645,16 @@ var PluginCapabilityClaimV1 = z8.discriminatedUnion("slug", [
     envelope: z8.strictObject({})
   }),
   z8.strictObject({
-    // Held to `kay.app`, the daemon-lifetime tier, even though the same wrapper is exposed on
+    // Held to `kay.app`, the daemon-lifetime tier, even though the same System One client is exposed on
     // BOTH the `kay.app` and `kay.agent` plugin SDKs (and to host composition directly): a slug
     // pins exactly one target (see this file's module doc), so one shared claim is simpler and
     // more honest than a second, `kay.agent`-scoped sibling slug for the identical capability.
-    // `kay.agent`'s `api.withJev` authorizes against this SAME claim through the calling
+    // `kay.agent`'s `api.systemOne` authorizes against this SAME claim through the calling
     // plugin's own pinned authority, which already spans both targets for every other capability
     // (`network.connect`/`tool-interception.register` are decided by the identical per-plugin
-    // handle `kay.app`-target claims use).
+    // handle `kay.app`-target claims use). `app.systemOne` authorizes against it the same way.
     target: z8.literal("kay.app"),
-    slug: z8.literal("jev.use"),
+    slug: z8.literal("systemOne.use"),
     envelope: z8.strictObject({})
   }),
   z8.strictObject({
@@ -1722,6 +1777,9 @@ var RETIRED_PLUGIN_CAPABILITY_SLUGS = [
   "filesystem.read",
   "filesystem.write"
 ];
+var RENAMED_PLUGIN_CAPABILITY_SLUGS = {
+  "jev.use": "systemOne.use"
+};
 var PLUGIN_CAPABILITY_SLUGS = [
   "sessions.run",
   "network.connect",
@@ -1736,7 +1794,7 @@ var PLUGIN_CAPABILITY_SLUGS = [
   "sessions.create",
   "sessions.update",
   "models.complete",
-  "jev.use",
+  "systemOne.use",
   "automations.write",
   "automations.run",
   "workflows.define",
@@ -1844,7 +1902,7 @@ function sameClaim(a, b) {
     case "tools.describe":
     case "workspace.command":
     case "models.complete":
-    case "jev.use":
+    case "systemOne.use":
     case "automations.write":
     case "automations.run":
     case "workflows.define":
@@ -1914,7 +1972,7 @@ function envelopePairs(a, b) {
     case "tools.describe":
     case "workspace.command":
     case "models.complete":
-    case "jev.use":
+    case "systemOne.use":
     case "automations.write":
     case "automations.run":
     case "workflows.define":
@@ -2814,29 +2872,6 @@ function pluginIconShape(svg) {
   return "mark";
 }
 
-// packages/plugin-protocol/dist/ids.js
-function resolvePluginNamespace(pluginId, namespace) {
-  return namespace ?? pluginId;
-}
-function resolveGlobalContributionId(namespace, localId) {
-  return `${namespace}.${localId}`;
-}
-function deriveDirectoryPluginToolName(namespace, localId) {
-  return `${namespace.replaceAll(".", "_")}_${localId}`;
-}
-function resolvePluginEventType(namespace, localId) {
-  return resolveGlobalContributionId(namespace, localId);
-}
-function isQualifiedAuthServiceRef(ref) {
-  return ref.includes(".");
-}
-function isQualifiedAuthSchemeRef(ref) {
-  return ref.includes(".");
-}
-function resolveAdapterId(globalId, declaredAdapterId) {
-  return declaredAdapterId ?? globalId;
-}
-
 // packages/plugin-protocol/dist/manifest.js
 import { z as z10 } from "zod";
 
@@ -3117,11 +3152,60 @@ var PluginAuthSchemeDelegated = z10.strictObject({
   kind: z10.literal("delegated"),
   scopes: z10.array(NonEmptyString).optional()
 });
+var ExternalCliArgument = z10.string().min(1).max(16384).refine((value) => ![...value].some(isUnsafeArgumentCharacter), {
+  message: "an argument may hold tabs and line breaks, but no other control character, no invisible character and no bidirectional override"
+});
+function isUnsafeArgumentCharacter(character) {
+  const code = character.codePointAt(0) ?? 0;
+  return code <= 31 && code !== 9 && code !== 10 || code >= 127 && code <= 159 || code === 1564 || code >= 8203 && code <= 8207 || code === 8232 || code === 8233 || code >= 8234 && code <= 8238 || code >= 8288 && code <= 8297 || code === 65279;
+}
+var ExternalCliCommand = z10.string().max(128).regex(/^[A-Za-z0-9][A-Za-z0-9._+-]*$/, {
+  message: "a command is an executable's basename (letters, digits, '.', '_', '+', '-'), never a path"
+});
+var ExternalCliHint = NonEmptyString.max(2048);
+var ExternalCliArguments = z10.array(ExternalCliArgument).max(64);
+var PluginExternalCliConnect = z10.strictObject({
+  /** A basename the host finds on `PATH` (`osascript`, `wrangler`), never a path. */
+  binary: ExternalCliCommand,
+  probe: z10.strictObject({
+    args: ExternalCliArguments.min(1),
+    timeoutMs: z10.number().int().min(1).max(12e4).optional(),
+    /**
+     * The CLI's own signed-out marker: text a failed probe's output (stderr, else stdout) contains
+     * when the CLI is signed out. A failure that carries it is a sign-in problem, and only such a
+     * failure runs `login`; a failure without it (a timeout, a provider outage) is reported as
+     * unavailable. Required when `login` is declared, so a timeout never starts a sign-in.
+     */
+    signedOutMarker: ExternalCliArgument.refine((value) => value.trim() !== "", { message: "a signed-out marker needs text beyond whitespace" }).optional()
+  }),
+  /** The CLI's interactive sign-in. Absent: connect only probes and reports. */
+  login: z10.strictObject({
+    args: ExternalCliArguments.min(1),
+    timeoutMs: z10.number().int().min(1).max(6e5).optional()
+  }).optional(),
+  /**
+   * The command that installs `binary`, as an argv. Bonsai never runs it: a surface shows it, joined
+   * for display, or hands it to an agent session that runs it behind the ordinary bash approval.
+   * Absent for a binary the OS ships (`osascript`).
+   */
+  install: z10.strictObject({ command: ExternalCliCommand, args: ExternalCliArguments }).optional(),
+  /** Prose for a person: `install` when the binary is missing, `login` when the probe fails. */
+  hints: z10.strictObject({ install: ExternalCliHint, login: ExternalCliHint })
+}).superRefine((cli, ctx) => {
+  if (cli.login !== void 0 && cli.probe.signedOutMarker === void 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["probe", "signedOutMarker"],
+      message: "a CLI connect that declares login needs probe.signedOutMarker, so only a signed-out probe runs login"
+    });
+  }
+});
 var PluginAuthSchemeExternalCli = z10.strictObject({
   ...PluginAuthSchemeDescriptionFields,
   localId: LocalContributionId,
   kind: z10.literal("external-cli"),
-  scopes: z10.array(NonEmptyString).optional()
+  scopes: z10.array(NonEmptyString).optional(),
+  cli: PluginExternalCliConnect.optional()
 });
 var PluginAuthScheme = z10.discriminatedUnion("kind", [
   PluginAuthSchemeOAuth2,
@@ -3706,6 +3790,21 @@ var KayPluginManifestV1 = z10.strictObject({
           message: `permission references unknown auth service ${grant.service}`
         });
       }
+      if (grant.frontDoor !== void 0) {
+        if (target !== "kay.agent") {
+          ctx.addIssue({
+            code: "custom",
+            path: ["permissions", "byTarget", target, "auth"],
+            message: "frontDoor is read only on a kay.agent auth grant"
+          });
+        } else if (manifest.namespace !== void 0 && grant.service.startsWith(`${manifest.namespace}.`) && authServices.has(grant.service.slice(manifest.namespace.length + 1))) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["permissions", "byTarget", target, "auth"],
+            message: `frontDoor needs another plugin's sign-in; ${grant.service} is this plugin's own`
+          });
+        }
+      }
       if (!isQualifiedAuthServiceRef(grant.service)) {
         const declaredSchemes = authSchemeIdsByService.get(grant.service);
         for (const scheme of grant.schemes ?? []) {
@@ -4095,7 +4194,9 @@ var ResolvedPluginAuthSchemeExternalCli = z11.strictObject({
   localId: LocalContributionId,
   globalId: GlobalContributionId,
   kind: z11.literal("external-cli"),
-  scopes: z11.array(z11.string()).optional()
+  scopes: z11.array(z11.string()).optional(),
+  /** The manifest's connect facts, verbatim. */
+  cli: PluginExternalCliConnect.optional()
 });
 var ResolvedPluginAuthScheme = z11.discriminatedUnion("kind", [
   ResolvedPluginAuthSchemeOAuth2,
@@ -4396,7 +4497,8 @@ function resolveAuthServices(namespace, manifest) {
         kind: scheme.kind,
         ...scopesField,
         ...descriptionFields,
-        ...provisioningField
+        ...provisioningField,
+        ...scheme.kind === "external-cli" && scheme.cli !== void 0 ? { cli: structuredClone(scheme.cli) } : {}
       };
     })
   }));
@@ -4887,6 +4989,180 @@ var CorpusResourceInvocationQuery = z14.strictObject({
   message: "since must precede until"
 });
 
+// packages/plugin-protocol/dist/skill-suggestion-evidence.js
+var UUID = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
+var UUID_ID = new RegExp(`^${UUID}$`, "i");
+var ENTRY = "[a-z0-9_-]+";
+var ENTRY_ID = new RegExp(`^${ENTRY}$`, "i");
+var FRICTION_URI = /^friction:\/\/([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+var normalizeId = (value) => UUID_ID.test(value) ? value.toLowerCase() : value;
+function sessionPattern(options) {
+  const known = (options.sessionIds ?? []).filter((id) => ENTRY_ID.test(id) && !UUID_ID.test(id)).map((id) => id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+  return `(?:${[UUID, ...new Set(known)].join("|")})`;
+}
+function sessionRef(sessionId, entryId, raw) {
+  return entryId === void 0 ? { kind: "session", sessionId: normalizeId(sessionId), raw } : {
+    kind: "message",
+    sessionId: normalizeId(sessionId),
+    entryId: normalizeId(entryId),
+    raw
+  };
+}
+function parseToken(raw, sessions) {
+  if (/^sessions?:\/\//i.test(raw)) {
+    const match = /^sessions?:\/\/([^/?#]+)([^?#]*)(?:\?([^#]*))?(?:#(.*))?$/i.exec(raw);
+    if (match === null)
+      return void 0;
+    const sessionId = match[1].replace(/\.jsonl$/i, "");
+    if (!new RegExp(`^${sessions}$`, "i").test(sessionId))
+      return void 0;
+    const path = match[2];
+    if (path !== "" && path !== "/" && !new RegExp(`^/${ENTRY}$`, "i").test(path))
+      return void 0;
+    const query = new URLSearchParams(match[3]);
+    const entryId = query.get("entry") ?? query.get("span") ?? query.get("from") ?? (path.length > 1 ? path.slice(1) : match[4]);
+    if (entryId !== void 0 && !ENTRY_ID.test(entryId))
+      return void 0;
+    return sessionRef(sessionId, entryId, raw);
+  }
+  if (/^friction:\/\//i.test(raw)) {
+    const reference = FRICTION_URI.exec(raw)?.[1];
+    return reference === void 0 || reference === "summary" ? void 0 : { kind: "friction", reference, raw };
+  }
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(raw)) {
+    return { kind: "uri", uri: raw, raw };
+  }
+  const message = new RegExp(`^(${sessions})(?:\\.jsonl)?(?:[/#](${ENTRY})(?:#[0-9]+)?)?$`, "i").exec(raw);
+  return message === null ? void 0 : sessionRef(message[1], message[2], raw);
+}
+function findSkillSuggestionCitations(text, options = {}) {
+  const sessions = sessionPattern(options);
+  const tokens = new RegExp(`(?<![\\w/.:#-])(?:[a-z][a-z0-9+.-]*://[^\\s<>\`"'|\\[\\]()]+|${sessions}(?:\\.jsonl)?(?:[/#]${ENTRY}(?:#[0-9]+)?)?(?![\\w/#-]))`, "gi");
+  const citations = [];
+  for (const match of text.matchAll(tokens)) {
+    const raw = match[0].replace(/[.,;:!?]+$/u, "");
+    if (new RegExp(`^${UUID}(?:#[0-9]+)?$`, "i").test(raw) && /\b(?:call|result)(?:\s*:\s*|\s+)$/i.test(text.slice(0, match.index)))
+      continue;
+    const ref = parseToken(raw, sessions);
+    if (ref !== void 0)
+      citations.push({
+        start: match.index,
+        end: match.index + raw.length,
+        ref
+      });
+  }
+  const sessionIds = new Set(citations.flatMap(({ ref }) => ref.kind === "message" || ref.kind === "session" && ref.raw.indexOf("://") >= 0 ? [ref.sessionId] : []));
+  if (sessionIds.size === 1) {
+    const sessionId = [...sessionIds][0];
+    const relative = new RegExp(`\\b(?:call|result)(?:\\s*:\\s*|\\s+)((?:${UUID}|[0-9a-f]{8,32}|[0-9]+)|${ENTRY}(?=#[0-9]+))(?:#[0-9]+)?(?![\\w/#-])`, "gi");
+    for (const match of text.matchAll(relative)) {
+      const start = match.index;
+      const end = start + match[0].length;
+      if (citations.some((item) => start < item.end && end > item.start))
+        continue;
+      citations.push({
+        start,
+        end,
+        ref: sessionRef(sessionId, match[1], match[0])
+      });
+    }
+  }
+  return citations.sort((a, b) => a.start - b.start);
+}
+function skillSuggestionEvidenceKey(item) {
+  switch (item.kind) {
+    case "message":
+      return `message:${item.sessionId}/${item.entryId}`;
+    case "session":
+      return `session:${item.sessionId}`;
+    case "friction":
+      return `friction:${item.reference}`;
+    case "uri":
+      return `uri:${item.uri}`;
+    case "text":
+      return `text:${item.text.trim()}`;
+  }
+}
+function skillSuggestionEvidenceItems(evidence, options = {}) {
+  const items = [];
+  const keys = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new WeakSet();
+  const add = (item) => {
+    const key = skillSuggestionEvidenceKey(item);
+    if (keys.has(key))
+      return;
+    keys.add(key);
+    items.push(item);
+  };
+  const text = (value) => {
+    const citations = findSkillSuggestionCitations(value, options);
+    if (citations.length === 0) {
+      if (value.trim() !== "")
+        add({ kind: "text", text: value });
+      return;
+    }
+    let cursor = 0;
+    const rest = [];
+    for (const citation of citations) {
+      rest.push(value.slice(cursor, citation.start));
+      cursor = citation.end;
+    }
+    rest.push(value.slice(cursor));
+    const note = rest.join(" ").trim();
+    if (citations.every(({ ref }) => ref.kind === "uri") && /[\p{L}\p{N}]/u.test(note)) {
+      add({ kind: "text", text: value });
+      return;
+    }
+    for (const citation of citations)
+      add(citation.ref);
+    if (/[\p{L}\p{N}]/u.test(note.replace(/\b(?:call|result|view|pointer|and)\b/gi, "")))
+      add({ kind: "text", text: note.replace(/^[\s|,;`]+|[\s|,;`]+$/g, "") });
+  };
+  const visit = (value, depth) => {
+    if (value === null || value === void 0)
+      return;
+    if (typeof value === "string")
+      return text(value);
+    if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint")
+      return text(String(value));
+    if (typeof value !== "object" || visited.has(value))
+      return;
+    visited.add(value);
+    if (depth >= 32) {
+      add({ kind: "text", text: "[evidence nested too deeply]" });
+      return;
+    }
+    if (Array.isArray(value)) {
+      for (const entry of value)
+        visit(entry, depth + 1);
+      return;
+    }
+    const object = value;
+    const sessionId = object.sessionId;
+    const entryId = object.entryId ?? object.messageId;
+    if (typeof sessionId === "string" && ENTRY_ID.test(sessionId) && (entryId === void 0 || typeof entryId === "string" && ENTRY_ID.test(entryId))) {
+      add(sessionRef(sessionId, entryId, `sessions://${sessionId}${entryId === void 0 ? "" : `/${entryId}`}`));
+      return;
+    }
+    if (object.kind === "text" && typeof object.text === "string") {
+      text(object.text);
+      return;
+    }
+    if (object.kind === "friction" && typeof object.reference === "string") {
+      text(`friction://${object.reference}`);
+      return;
+    }
+    if (object.kind === "uri" && typeof object.uri === "string") {
+      text(object.uri);
+      return;
+    }
+    for (const entry of Object.values(object))
+      visit(entry, depth + 1);
+  };
+  visit(evidence, 0);
+  return items;
+}
+
 // packages/plugin-protocol/dist/ui-app-package.js
 import { z as z15 } from "zod";
 var KAY_UI_APP_PACKAGE_PROTOCOL = "kay.ui.app-package.v1";
@@ -5041,6 +5317,7 @@ export {
   ArtifactProvenanceSource,
   ArtifactUriModuleContribution,
   AuthAccountSelector,
+  AuthGrantFrontDoor,
   AuthGrantOperation,
   AuthGrantRequest,
   AuthSchemeReference,
@@ -5130,6 +5407,7 @@ export {
   PluginConfigSectionManifest,
   PluginContributionKind,
   PluginEventDefinitionContribution,
+  PluginExternalCliConnect,
   PluginId,
   PluginNamespace,
   PluginNotificationRuleContribution,
@@ -5144,6 +5422,7 @@ export {
   PluginToolName,
   PluginWebSessionDeclaration,
   PluginWebSessionProbe,
+  RENAMED_PLUGIN_CAPABILITY_SLUGS,
   RESERVED_DIRECTORY_PLUGIN_ID_PREFIXES,
   RETIRED_COMPATIBILITY_KEYS,
   RETIRED_PERMISSION_ASK_KEYS,
@@ -5241,6 +5520,7 @@ export {
   dedupeClaims,
   deriveDirectoryPluginToolName,
   finalizeArtifactProvenanceEnvelope,
+  findSkillSuggestionCitations,
   hasClaim,
   hostWithinDomain,
   isCompatible,
@@ -5277,6 +5557,8 @@ export {
   satisfiesSemverRange,
   sessionHealthEntrySchema,
   sessionHealthPWellDecile,
+  skillSuggestionEvidenceItems,
+  skillSuggestionEvidenceKey,
   turnMessageOrigin,
   turnPacket,
   urlHostWithinDomain,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaklabs-ai/plugin-protocol",
-  "version": "0.13.9",
+  "version": "0.14.0",
   "description": "The Kay plugin manifest schema (`kay.plugin.v1`) — parse and validate a kay-plugin.json.",
   "author": "YakLabs",
   "type": "module",