@yaklabs-ai/plugin-sdk 0.44.0 → 0.45.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.44.0"
+    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.45.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.44.0" },
+  "compatibility": { "sdk": "^0.45.0" },
   "targets": {
     "kay": {
       "agent": {

package/THIRD-PARTY-INVENTORY.json

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

package/dist/disclosure.d.ts

@@ -2430,8 +2430,10 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  *
  * 0.44.0 adds `words.kinds` to a reference presentation (#15905): an ordered list of address patterns
  * and the kind each one names. Additive: a plugin that lists them declares ^0.44.0.
+ *
+ * 0.45.0 adds declared plugin cards and app.implementCard for their read/submit endpoints.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.44.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.45.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 

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

@@ -2484,8 +2484,10 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  *
  * 0.44.0 adds `words.kinds` to a reference presentation (#15905): an ordered list of address patterns
  * and the kind each one names. Additive: a plugin that lists them declares ^0.44.0.
+ *
+ * 0.45.0 adds declared plugin cards and app.implementCard for their read/submit endpoints.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.44.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.45.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -4870,6 +4872,7 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
             interactionDriver: "interactionDriver";
             entityResolver: "entityResolver";
             agentRenderer: "agentRenderer";
+            pluginCard: "pluginCard";
             eventDefinition: "eventDefinition";
             eventSubscription: "eventSubscription";
             appDataSource: "appDataSource";
@@ -5667,6 +5670,22 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
             scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>>;
     }, z.core.$strict>>>;
+    kayAppCards: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        localId: z.ZodString;
+        globalId: z.ZodString;
+        pluginId: z.ZodString;
+        description: z.ZodString;
+        inputs: z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>;
+        readEndpoint: z.ZodObject<{
+            localId: z.ZodString;
+            globalId: z.ZodString;
+        }, z.core.$strict>;
+        submitEndpoint: z.ZodObject<{
+            localId: z.ZodString;
+            globalId: z.ZodString;
+        }, z.core.$strict>;
+        authService: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
     kayAppDataSources: z.ZodOptional<z.ZodArray<z.ZodObject<{
         localId: z.ZodString;
         globalId: z.ZodString;

package/dist/kay-agent.d.ts

@@ -2759,8 +2759,10 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  *
  * 0.44.0 adds `words.kinds` to a reference presentation (#15905): an ordered list of address patterns
  * and the kind each one names. Additive: a plugin that lists them declares ^0.44.0.
+ *
+ * 0.45.0 adds declared plugin cards and app.implementCard for their read/submit endpoints.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.44.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.45.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 

package/dist/kay-app.d.ts

@@ -2744,8 +2744,10 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  *
  * 0.44.0 adds `words.kinds` to a reference presentation (#15905): an ordered list of address patterns
  * and the kind each one names. Additive: a plugin that lists them declares ^0.44.0.
+ *
+ * 0.45.0 adds declared plugin cards and app.implementCard for their read/submit endpoints.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.44.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.45.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -3970,6 +3972,17 @@ export declare interface KayAppBackgroundCredentialRequest {
     readonly jobId: string;
 }
 
+/** The background operations of a manifest-declared plugin card. */
+export declare interface KayAppCardImplementation<Input = unknown, Data = unknown, Values = unknown> {
+    read(inputs: Input): KayAppCardResult<Data> | Promise<KayAppCardResult<Data>>;
+    submit(request: {
+        readonly inputs: Input;
+        readonly values: Values;
+    }): KayAppCardResult<Data> | Promise<KayAppCardResult<Data>>;
+}
+
+export declare type KayAppCardResult<T> = PluginCardResult<T>;
+
 /**
  * The `kay.app` system-prompt contract (`app.systemPrompt`): text a plugin adds to every chat's
  * system prompt, rendered by the daemon from a few facts about the chat and reused across chats.
@@ -5384,6 +5397,12 @@ export declare interface KayAppPluginApi {
      * fail-closed at activation, exactly like {@link registerUriModule}.
      */
     registerTool(localId: string, definition: KayAppToolDefinition): void;
+    /**
+     * Implement a declared plugin card through its own declared read and submit endpoints.
+     * Undeclared, duplicate or missing implementations fail activation. The host routes
+     * both operations through the existing endpoint validation and plugin lifecycle.
+     */
+    implementCard<Input = unknown, Data = unknown, Values = unknown>(localId: string, implementation: KayAppCardImplementation<Input, Data, Values>): void;
     /**
      * Supply the code of a workflow this plugin's manifest declares under
      * `targets.kay.app.contributes.workflows` (SDK 0.30.0). The manifest says its name, schedule and
@@ -9798,6 +9817,15 @@ export declare const PluginAgentDefinitionPermissionRule: z.ZodObject<{
 
 export declare type PluginAgentDefinitionPermissionRule = z.infer<typeof PluginAgentDefinitionPermissionRule>;
 
+declare type PluginCardResult<T> = {
+    readonly ok: true;
+    readonly data: T;
+} | {
+    readonly ok: false;
+    readonly reason: "needs-auth" | "failed";
+    readonly message: string;
+};
+
 export declare const PluginEventEnvelope: z.ZodObject<{
     id: z.ZodString;
     localId: z.ZodString;

package/package.json

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