@yaklabs-ai/plugin-sdk 0.50.0 → 0.52.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.50.0"
+    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.52.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.50.0" },
+  "compatibility": { "sdk": "^0.52.0" },
   "targets": {
     "kay": {
       "agent": {
@@ -151,7 +151,7 @@ naming both versions, instead of loading it and finding no `activate`.
 | `@bonsai/plugin-sdk/system-one`         | The types and error class for `api.systemOne` / `app.systemOne`, from 0.13.8             |
 | `@bonsai/plugin-sdk/zod`                | `z` (the host's in the daemon), on an entry with no other import, from 0.13.9            |
 
-A plugin that imports these subpaths declares the current supported SDK range (`^0.50.0`).
+A plugin that imports these subpaths declares the current supported SDK range (`^0.52.0`).
 The rows record when each subpath appeared, not retained runtime compatibility. `vendored-mcp` builds the plugin's URI module (its link cards and help); hosting the
 vendor's MCP server itself is a separate host decision: Bonsai hosts it once a person approves
 the plugin's `mcp.host-server` grant for that server's name and URL. A server that needs an OAuth
@@ -159,7 +159,7 @@ sign-in names one of the plugin's auth services in `authService`; that service m
 one `delegated` scheme, which Bonsai uses to sign the person in to the server. Bonsai declares that
 scheme at runtime; the plugin's code must not declare it again. From 0.16.2 a plugin's code can also
 call the server's tools through `api.vendoredMcp.port(<server>)`, typed by this subpath's
-`VendoredMcpPort` and `VendoredMcpOutcome` (declare `^0.50.0`).
+`VendoredMcpPort` and `VendoredMcpOutcome` (declare `^0.52.0`).
 
 From 0.13.10 the manifest schema carries two facts Bonsai reads for its own plugins only; another
 plugin's are ignored, with a load diagnostic. An `external-cli` auth scheme's `cli` says how Bonsai
@@ -241,7 +241,7 @@ Provider schemas remain authoritative; declaring a dependency grants no authorit
 through `app.uri`, parse returned Markdown in the consuming plugin, and retain the read's
 revision (or `contentDigest` from `/uri`) for edits. The old `memory.read` and `memory.write`
 grants do not authorize the replacement scheme-and-verb calls. Contracts before 0.49.0 are
-refused; migrate and declare `^0.50.0`. The current host also serves the 0.49.0 resource contract.
+refused; migrate and declare `^0.52.0`. The current host also serves the 0.49.0 resource contract.
 
 ## What this package is, and is not, at runtime
 

package/THIRD-PARTY-INVENTORY.json

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

package/dist/disclosure.d.ts

@@ -2456,8 +2456,10 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  *
  * 0.50.0 adds explicit cross-plugin endpoint calls on both backend targets. The URI-only 0.49.0
  * contract remains served.
+ *
+ * 0.51.0 adds flag-dependent title, icon and panel presence on rail entries.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.50.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.52.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 

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

@@ -2510,8 +2510,10 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  *
  * 0.50.0 adds explicit cross-plugin endpoint calls on both backend targets. The URI-only 0.49.0
  * contract remains served.
+ *
+ * 0.51.0 adds flag-dependent title, icon and panel presence on rail entries.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.50.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.52.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -4935,6 +4937,20 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
     }, z.core.$strict>>;
     consumesAuthServices: z.ZodArray<z.ZodString>;
     explicitDependencies: z.ZodArray<z.ZodString>;
+    dataDirSharedWith: z.ZodOptional<z.ZodString>;
+    workloadPurposes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        purpose: z.ZodString;
+        workloadClass: z.ZodEnum<{
+            dreaming: "dreaming";
+            hindsight: "hindsight";
+        }>;
+    }, z.core.$strict>>>;
+    shellCommands: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        usage: z.ZodString;
+        endpointId: z.ZodString;
+    }, z.core.$strict>>>;
     authServices: z.ZodArray<z.ZodObject<{
         localId: z.ZodString;
         globalId: z.ZodString;
@@ -4942,6 +4958,30 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
         summary: z.ZodOptional<z.ZodString>;
         schemes: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodDiscriminatedUnion<[z.ZodObject<{
             exchange: z.ZodLiteral<"pkce">;
+            byoocProfile: z.ZodOptional<z.ZodObject<{
+                displayName: z.ZodString;
+                fields: z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                    label: z.ZodString;
+                    optional: z.ZodOptional<z.ZodBoolean>;
+                    validation: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                        kind: z.ZodLiteral<"uuid">;
+                    }, z.core.$strict>, z.ZodObject<{
+                        kind: z.ZodLiteral<"suffix">;
+                        value: z.ZodString;
+                    }, z.core.$strict>], "kind">>;
+                    failureMessage: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>>;
+                setup: z.ZodObject<{
+                    steps: z.ZodArray<z.ZodString>;
+                    notes: z.ZodArray<z.ZodString>;
+                    url: z.ZodURL;
+                }, z.core.$strict>;
+                endpointTemplates: z.ZodOptional<z.ZodObject<{
+                    authorizationUrl: z.ZodString;
+                    tokenUrl: z.ZodString;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
             clientSuppliers: z.ZodArray<z.ZodEnum<{
                 user: "user";
                 kay: "kay";
@@ -5140,6 +5180,19 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                             }>;
                             mimeTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                             successNote: z.ZodOptional<z.ZodString>;
+                            round: z.ZodOptional<z.ZodObject<{
+                                scopes: z.ZodArray<z.ZodString>;
+                                extraAuthorizeParams: z.ZodRecord<z.ZodString, z.ZodString>;
+                                redirectParam: z.ZodString;
+                                requiresGrantedScope: z.ZodString;
+                                supersededByScopes: z.ZodArray<z.ZodString>;
+                                purpose: z.ZodString;
+                                displayNoun: z.ZodString;
+                            }, z.core.$strict>>;
+                            completion: z.ZodOptional<z.ZodObject<{
+                                pluginId: z.ZodString;
+                                moduleId: z.ZodString;
+                            }, z.core.$strict>>;
                         }, z.core.$strict>>;
                     }, z.core.$strict>>;
                     service: z.ZodString;
@@ -5160,9 +5213,9 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                         dataDir: "dataDir";
                     }>;
                     operations: z.ZodArray<z.ZodEnum<{
-                        open: "open";
                         read: "read";
                         write: "write";
+                        open: "open";
                     }>>;
                 }, z.core.$strict>>>;
                 events: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -5174,8 +5227,8 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                 }, z.core.$strict>>>;
                 endpoints: z.ZodOptional<z.ZodArray<z.ZodObject<{
                     operations: z.ZodArray<z.ZodEnum<{
-                        register: "register";
                         invoke: "invoke";
+                        register: "register";
                     }>>;
                     endpoint: z.ZodString;
                 }, z.core.$strict>>>;
@@ -5235,6 +5288,19 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                             }>;
                             mimeTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                             successNote: z.ZodOptional<z.ZodString>;
+                            round: z.ZodOptional<z.ZodObject<{
+                                scopes: z.ZodArray<z.ZodString>;
+                                extraAuthorizeParams: z.ZodRecord<z.ZodString, z.ZodString>;
+                                redirectParam: z.ZodString;
+                                requiresGrantedScope: z.ZodString;
+                                supersededByScopes: z.ZodArray<z.ZodString>;
+                                purpose: z.ZodString;
+                                displayNoun: z.ZodString;
+                            }, z.core.$strict>>;
+                            completion: z.ZodOptional<z.ZodObject<{
+                                pluginId: z.ZodString;
+                                moduleId: z.ZodString;
+                            }, z.core.$strict>>;
                         }, z.core.$strict>>;
                     }, z.core.$strict>>;
                     service: z.ZodString;
@@ -5255,9 +5321,9 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                         dataDir: "dataDir";
                     }>;
                     operations: z.ZodArray<z.ZodEnum<{
-                        open: "open";
                         read: "read";
                         write: "write";
+                        open: "open";
                     }>>;
                 }, z.core.$strict>>>;
                 events: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -5269,8 +5335,8 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                 }, z.core.$strict>>>;
                 endpoints: z.ZodOptional<z.ZodArray<z.ZodObject<{
                     operations: z.ZodArray<z.ZodEnum<{
-                        register: "register";
                         invoke: "invoke";
+                        register: "register";
                     }>>;
                     endpoint: z.ZodString;
                 }, z.core.$strict>>>;
@@ -5330,6 +5396,19 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                             }>;
                             mimeTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                             successNote: z.ZodOptional<z.ZodString>;
+                            round: z.ZodOptional<z.ZodObject<{
+                                scopes: z.ZodArray<z.ZodString>;
+                                extraAuthorizeParams: z.ZodRecord<z.ZodString, z.ZodString>;
+                                redirectParam: z.ZodString;
+                                requiresGrantedScope: z.ZodString;
+                                supersededByScopes: z.ZodArray<z.ZodString>;
+                                purpose: z.ZodString;
+                                displayNoun: z.ZodString;
+                            }, z.core.$strict>>;
+                            completion: z.ZodOptional<z.ZodObject<{
+                                pluginId: z.ZodString;
+                                moduleId: z.ZodString;
+                            }, z.core.$strict>>;
                         }, z.core.$strict>>;
                     }, z.core.$strict>>;
                     service: z.ZodString;
@@ -5350,9 +5429,9 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                         dataDir: "dataDir";
                     }>;
                     operations: z.ZodArray<z.ZodEnum<{
-                        open: "open";
                         read: "read";
                         write: "write";
+                        open: "open";
                     }>>;
                 }, z.core.$strict>>>;
                 events: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -5364,8 +5443,8 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                 }, z.core.$strict>>>;
                 endpoints: z.ZodOptional<z.ZodArray<z.ZodObject<{
                     operations: z.ZodArray<z.ZodEnum<{
-                        register: "register";
                         invoke: "invoke";
+                        register: "register";
                     }>>;
                     endpoint: z.ZodString;
                 }, z.core.$strict>>>;
@@ -5390,6 +5469,8 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
         }, z.core.$strict>;
     }, z.core.$strict>>;
     kayAgentUriModules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        revisionBacked: z.ZodOptional<z.ZodLiteral<true>>;
+        mailCalibrationSource: z.ZodOptional<z.ZodLiteral<true>>;
         screenActions: z.ZodExactOptional<z.ZodObject<{
             scheme: z.ZodString;
             hosts: z.ZodArray<z.ZodString>;
@@ -5449,8 +5530,8 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
             description: z.ZodString;
             operations: z.ZodExactOptional<z.ZodArray<z.ZodEnum<{
                 search: "search";
-                list: "list";
                 read: "read";
+                list: "list";
                 write: "write";
                 edit: "edit";
                 delete: "delete";
@@ -5458,8 +5539,8 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
             }>>>;
             operationDocs: z.ZodExactOptional<z.ZodRecord<z.ZodEnum<{
                 search: "search";
-                list: "list";
                 read: "read";
+                list: "list";
                 write: "write";
                 edit: "edit";
                 delete: "delete";
@@ -5467,8 +5548,8 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
             }> & z.core.$partial, z.ZodString>>;
             operationDefaults: z.ZodExactOptional<z.ZodRecord<z.ZodEnum<{
                 search: "search";
-                list: "list";
                 read: "read";
+                list: "list";
                 write: "write";
                 edit: "edit";
                 delete: "delete";
@@ -5531,8 +5612,8 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                 action: z.ZodString;
                 operations: z.ZodExactOptional<z.ZodArray<z.ZodEnum<{
                     search: "search";
-                    list: "list";
                     read: "read";
+                    list: "list";
                     write: "write";
                     edit: "edit";
                     delete: "delete";
@@ -5544,8 +5625,8 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                 public: z.ZodLiteral<true>;
                 operations: z.ZodExactOptional<z.ZodArray<z.ZodEnum<{
                     search: "search";
-                    list: "list";
                     read: "read";
+                    list: "list";
                     write: "write";
                     edit: "edit";
                     delete: "delete";
@@ -5667,9 +5748,9 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
     }, z.core.$strict>>>;
     kayAppTools: z.ZodOptional<z.ZodArray<z.ZodObject<{
         description: z.ZodOptional<z.ZodString>;
-        localId: z.ZodString;
-        displayName: z.ZodOptional<z.ZodString>;
         toolName: z.ZodString;
+        displayName: z.ZodOptional<z.ZodString>;
+        localId: z.ZodString;
         parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>>;
         executionMode: z.ZodOptional<z.ZodEnum<{
             sequential: "sequential";
@@ -5715,9 +5796,6 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
     }, z.core.$strict>>>;
     kayAppApprovalTypes: z.ZodOptional<z.ZodArray<z.ZodObject<{
         kind: z.ZodLiteral<"message">;
-        localId: z.ZodString;
-        provider: z.ZodString;
-        unknownMessage: z.ZodString;
         fields: z.ZodObject<{
             body: z.ZodObject<{
                 key: z.ZodString;
@@ -5728,6 +5806,9 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                 max: z.ZodNumber;
             }, z.core.$strict>>;
         }, z.core.$strict>;
+        localId: z.ZodString;
+        provider: z.ZodString;
+        unknownMessage: z.ZodString;
         presentation: z.ZodObject<{
             showAccount: z.ZodBoolean;
             recipient: z.ZodEnum<{
@@ -6045,6 +6126,7 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                 "automations.read": "automations.read";
                 "automations.run": "automations.run";
                 "shared-artifacts.read": "shared-artifacts.read";
+                "projects.manage": "projects.manage";
                 "workspace.place-pane": "workspace.place-pane";
                 "workspace.pane-header": "workspace.pane-header";
                 "workspace.arrange": "workspace.arrange";

package/dist/kay-agent.d.ts

@@ -2789,8 +2789,10 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  *
  * 0.50.0 adds explicit cross-plugin endpoint calls on both backend targets. The URI-only 0.49.0
  * contract remains served.
+ *
+ * 0.51.0 adds flag-dependent title, icon and panel presence on rail entries.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.50.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.52.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -5090,8 +5092,8 @@ declare const PluginCapabilityRefusalV1: z.ZodObject<{
             scheme: z.ZodString;
             verb: z.ZodEnum<{
                 search: "search";
-                list: "list";
                 read: "read";
+                list: "list";
                 write: "write";
                 edit: "edit";
                 delete: "delete";
@@ -5507,6 +5509,34 @@ declare const PluginNamespace: z.ZodString;
 
 declare type PluginNamespace = z.infer<typeof PluginNamespace>;
 
+export declare interface PluginResourcePickCompletion {
+    readonly serviceId: string;
+    readonly schemeId: string;
+    readonly accountId: string;
+    readonly capabilityServiceId?: string;
+    readonly identityEmail?: string;
+    readonly pickedResourceIds: readonly string[];
+    readonly accessToken: string;
+    readonly accountAccessToken: string;
+    readonly traceId: string;
+}
+
+export declare type PluginResourcePickHandler = (completion: PluginResourcePickCompletion) => Promise<PluginResourcePickResult>;
+
+export declare type PluginResourcePickResult = {
+    readonly ok: true;
+    readonly recorded: number;
+    readonly resources: readonly {
+        readonly id: string;
+        readonly uri: string;
+        readonly title?: string;
+        readonly mimeType?: string;
+    }[];
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+
 /** What one connection flow unlocks and when an agent should choose it; grants no authority. */
 export declare type PluginSchemeAgentHint = string;
 

package/dist/kay-app.d.ts

@@ -2905,8 +2905,10 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  *
  * 0.50.0 adds explicit cross-plugin endpoint calls on both backend targets. The URI-only 0.49.0
  * contract remains served.
+ *
+ * 0.51.0 adds flag-dependent title, icon and panel presence on rail entries.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.50.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.52.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -3228,6 +3230,8 @@ export declare type KayAppActivate = (app: KayAppPluginApi) => void | Promise<vo
  */
 export declare interface KayAppAgentDefinition {
     readonly name: string;
+    readonly promptLayout?: "no-tool-judgment" | "outcome-handler";
+    readonly idleReplies?: readonly string[];
     readonly description?: string;
     readonly icon?: string;
     /** Defaults to `hidden` when absent - see {@link KayAppAgentDefinitionVisibility}. */
@@ -5266,6 +5270,9 @@ export declare interface KayAppPhaseShiftSessionEvent extends KayAppSessionEvent
  * physical sandbox against ambient Node imports.
  */
 export declare interface KayAppPluginApi {
+    readonly resourcePicks?: {
+        registerCompletion(moduleId: string, handler: PluginResourcePickHandler): void;
+    };
     readonly mcp: KayAppMcp;
     /** This plugin's canonical id (already validated by the host registry). */
     readonly id: string;
@@ -7658,6 +7665,7 @@ export declare interface KayAppSystemPrompt {
 }
 
 export declare interface KayAppSystemPromptFragment {
+    readonly analyticsFamily?: string;
     /**
      * The facts the text varies by. Chats with the same values share one rendered text, so the
      * text must depend on nothing else about the chat.
@@ -10063,6 +10071,34 @@ export declare interface PluginProductEventSend {
     readonly subjectUri?: string;
 }
 
+declare interface PluginResourcePickCompletion {
+    readonly serviceId: string;
+    readonly schemeId: string;
+    readonly accountId: string;
+    readonly capabilityServiceId?: string;
+    readonly identityEmail?: string;
+    readonly pickedResourceIds: readonly string[];
+    readonly accessToken: string;
+    readonly accountAccessToken: string;
+    readonly traceId: string;
+}
+
+declare type PluginResourcePickHandler = (completion: PluginResourcePickCompletion) => Promise<PluginResourcePickResult>;
+
+declare type PluginResourcePickResult = {
+    readonly ok: true;
+    readonly recorded: number;
+    readonly resources: readonly {
+        readonly id: string;
+        readonly uri: string;
+        readonly title?: string;
+        readonly mimeType?: string;
+    }[];
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+
 export declare const PluginSignal: z.ZodObject<{
     kind: z.ZodEnum<{
         message: "message";
@@ -10559,9 +10595,6 @@ export declare interface ResolvedCredential {
 
 declare const ResolvedKayAppApprovalType: z.ZodObject<{
     kind: z.ZodLiteral<"message">;
-    localId: z.ZodString;
-    provider: z.ZodString;
-    unknownMessage: z.ZodString;
     fields: z.ZodObject<{
         body: z.ZodObject<{
             key: z.ZodString;
@@ -10572,6 +10605,9 @@ declare const ResolvedKayAppApprovalType: z.ZodObject<{
             max: z.ZodNumber;
         }, z.core.$strict>>;
     }, z.core.$strict>;
+    localId: z.ZodString;
+    provider: z.ZodString;
+    unknownMessage: z.ZodString;
     presentation: z.ZodObject<{
         showAccount: z.ZodBoolean;
         recipient: z.ZodEnum<{
@@ -11485,6 +11521,47 @@ declare const SessionRelationship: z.ZodDiscriminatedUnion<[z.ZodObject<{
 
 declare type SessionRelationship = z.infer<typeof SessionRelationship>;
 
+export declare const ShellCommandOutcome: z.ZodObject<{
+    exitCode: z.ZodNumber;
+    envelope: z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>;
+    result: z.ZodOptional<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>;
+}, z.core.$strict>;
+
+export declare type ShellCommandOutcome = z.infer<typeof ShellCommandOutcome>;
+
+export declare const ShellCommandRequest: z.ZodObject<{
+    argv: z.ZodArray<z.ZodString>;
+    cwd: z.ZodString;
+    outcomes: z.ZodArray<z.ZodObject<{
+        exitCode: z.ZodNumber;
+        envelope: z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>;
+        result: z.ZodOptional<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+
+export declare type ShellCommandRequest = z.infer<typeof ShellCommandRequest>;
+
+export declare const ShellCommandStep: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"invoke">;
+    toolName: z.ZodEnum<{
+        search: "search";
+        read: "read";
+        list: "list";
+        write: "write";
+        edit: "edit";
+        delete: "delete";
+        help: "help";
+    }>;
+    input: z.ZodRecord<z.ZodString, z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>;
+    flags: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"finish">;
+    exitCode: z.ZodNumber;
+    stdout: z.ZodString;
+}, z.core.$strict>], "kind">;
+
+export declare type ShellCommandStep = z.infer<typeof ShellCommandStep>;
+
 /**
  * The largest epoch-millisecond time a `Date` can hold (about the year 275,760). A time outside
  * 0 to this bound has no date to show, so neither `observe` nor a read window accepts one.

package/dist/kay-app.js

@@ -387,6 +387,46 @@ var JsonValue = z5.lazy(() => z5.union([
 var JsonObject = z5.record(z5.string(), JsonValue);
 var JsonSchema = z5.record(z5.string(), JsonValue);
 
+// packages/plugin-protocol/dist/shell-commands.js
+import { z as z6 } from "zod";
+var PluginShellCommand = z6.strictObject({
+  name: z6.string().regex(/^[a-z][a-z0-9-]*$/),
+  aliases: z6.array(z6.string().regex(/^[a-z][a-z0-9-]*$/)).optional(),
+  endpoint: z6.string().min(1),
+  usage: z6.string().min(1)
+});
+var ShellCommandOutcome = z6.strictObject({
+  exitCode: z6.number().int(),
+  envelope: JsonValue,
+  result: JsonValue.optional()
+});
+var ShellCommandRequest = z6.strictObject({
+  argv: z6.array(z6.string()),
+  cwd: z6.string(),
+  outcomes: z6.array(ShellCommandOutcome).max(3)
+});
+var ShellCommandStep = z6.discriminatedUnion("kind", [
+  z6.strictObject({
+    kind: z6.literal("invoke"),
+    toolName: z6.enum([
+      "read",
+      "list",
+      "search",
+      "write",
+      "edit",
+      "delete",
+      "help"
+    ]),
+    input: z6.record(z6.string(), JsonValue),
+    flags: z6.record(z6.string(), z6.string())
+  }),
+  z6.strictObject({
+    kind: z6.literal("finish"),
+    exitCode: z6.number().int(),
+    stdout: z6.string()
+  })
+]);
+
 // packages/plugin-sdk/dist/kay-app/card-layout.js
 function element(type, props) {
   return { root: "root", elements: { root: { type, props } } };
@@ -447,7 +487,7 @@ function submit(label) {
 }
 
 // packages/plugin-sdk/dist/signals.js
-import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 function createFallbackOnlySignals() {
   const noStore = { status: "unavailable", reason: "no-store" };
   return {
@@ -477,23 +517,23 @@ var POINTER = /^[^\s\p{C}/?#]+$/u;
 var LABEL = /^[^\s,@\p{C}]+(?: [^\s,@\p{C}]+)*$/u;
 var RUN_ID = /^\P{Cc}+$/u;
 var POINTER_RULE = `1 to ${MAX_POINTER} characters with no whitespace, \`/\`, \`?\`, \`#\`, or control or invisible character`;
-var ObserveShape = z6.looseObject({
-  detector: z6.looseObject({ id: z6.string(), version: z6.string() }),
-  subject: z6.looseObject({ kind: z6.string(), key: z6.string().optional() }).optional(),
-  after: z6.looseObject({ observationId: z6.unknown() }).optional(),
-  reuse: z6.looseObject({ maxAgeMs: z6.unknown() }).optional(),
-  source: z6.looseObject({
-    sessionId: z6.string(),
-    entryId: z6.string(),
-    openerEntryId: z6.string().optional(),
-    runId: z6.string().optional(),
-    occurredAtMs: z6.unknown().optional()
+var ObserveShape = z7.looseObject({
+  detector: z7.looseObject({ id: z7.string(), version: z7.string() }),
+  subject: z7.looseObject({ kind: z7.string(), key: z7.string().optional() }).optional(),
+  after: z7.looseObject({ observationId: z7.unknown() }).optional(),
+  reuse: z7.looseObject({ maxAgeMs: z7.unknown() }).optional(),
+  source: z7.looseObject({
+    sessionId: z7.string(),
+    entryId: z7.string(),
+    openerEntryId: z7.string().optional(),
+    runId: z7.string().optional(),
+    occurredAtMs: z7.unknown().optional()
   }),
-  questions: z6.record(z6.string(), z6.unknown())
+  questions: z7.record(z7.string(), z7.unknown())
 });
-var ChoiceQuestion = z6.looseObject({
-  type: z6.literal("choice"),
-  criteria: z6.record(z6.string(), z6.unknown())
+var ChoiceQuestion = z7.looseObject({
+  type: z7.literal("choice"),
+  criteria: z7.record(z7.string(), z7.unknown())
 });
 var fits = (value, grammar) => value.length <= MAX_NAME && grammar.test(value);
 var isWhole = (value, min) => typeof value === "number" && Number.isSafeInteger(value) && value >= min && value <= SIGNAL_TIME_MAX_MS;
@@ -573,10 +613,10 @@ function grammarProblem(input) {
   }
   return void 0;
 }
-var EchoText = z6.string().catch("");
-var Echo = z6.object({
-  detector: z6.object({ id: EchoText, version: EchoText }).catch({ id: "", version: "" }),
-  source: z6.object({ sessionId: EchoText, entryId: EchoText }).catch({ sessionId: "", entryId: "" })
+var EchoText = z7.string().catch("");
+var Echo = z7.object({
+  detector: z7.object({ id: EchoText, version: EchoText }).catch({ id: "", version: "" }),
+  source: z7.object({ sessionId: EchoText, entryId: EchoText }).catch({ sessionId: "", entryId: "" })
 }).catch({
   detector: { id: "", version: "" },
   source: { sessionId: "", entryId: "" }
@@ -1103,6 +1143,9 @@ export {
   SIGNAL_TIME_MAX_MS,
   STORED_TRANSCRIPT_MESSAGE_FILTER,
   STORED_TRANSCRIPT_MESSAGE_KINDS,
+  ShellCommandOutcome,
+  ShellCommandRequest,
+  ShellCommandStep,
   UriConflictError,
   UriNotFoundError,
   UriProviderError,

package/package.json

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