@yaklabs-ai/plugin-protocol 0.55.10 → 0.55.12

package/README.md

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

package/THIRD-PARTY-INVENTORY.json

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

package/dist/index.d.ts

@@ -552,6 +552,9 @@ export declare const AppUriModuleContribution: z.ZodObject<{
 
 export declare type AppUriModuleContribution = z.infer<typeof AppUriModuleContribution>;
 
+/** The most chats one `outputs.folderMarks` request may name (SDK 0.55.11). */
+export declare const ARTIFACT_OUTPUT_FOLDER_MARKS_MAX = 500;
+
 export declare const ARTIFACT_OUTPUT_PAGE_MAX = 200;
 
 export declare const ARTIFACT_PROVENANCE_VERSION: "kay.artifact-provenance.v1";
@@ -560,16 +563,116 @@ export declare const ArtifactGenerationId: z.core.$ZodBranded<z.ZodString, "Arti
 
 export declare type ArtifactGenerationId = z.infer<typeof ArtifactGenerationId>;
 
+/**
+ * A notice that output files changed. `{ uris }` names the files; since SDK 0.55.11 it may also
+ * carry `changes`, one per URI in `uris` and in the same order, saying what happened to each.
+ * `{ sessionId }` is the legacy chat-only notice from older adapters.
+ */
 export declare const ArtifactOutputChange: z.ZodUnion<readonly [z.ZodObject<{
     uris: z.ZodArray<z.ZodString>;
+    changes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        uri: z.ZodString;
+        kind: z.ZodEnum<{
+            created: "created";
+            changed: "changed";
+            deleted: "deleted";
+        }>;
+        file: z.ZodOptional<z.ZodObject<{
+            sizeBytes: z.ZodNumber;
+            modifiedAtMs: z.ZodNumber;
+            title: z.ZodString;
+            mimeType: z.ZodOptional<z.ZodString>;
+            versionState: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                state: z.ZodLiteral<"draft">;
+            }, z.core.$strict>, z.ZodObject<{
+                state: z.ZodEnum<{
+                    clean: "clean";
+                    edited: "edited";
+                }>;
+                committedVersion: z.ZodNumber;
+            }, z.core.$strict>], "state">>;
+        }, z.core.$strict>>;
+        metadataOnly: z.ZodOptional<z.ZodLiteral<true>>;
+    }, z.core.$strict>>>;
 }, z.core.$strict>, z.ZodObject<{
     sessionId: z.ZodString;
 }, z.core.$strict>]>;
 
 export declare type ArtifactOutputChange = z.infer<typeof ArtifactOutputChange>;
 
+/**
+ * One file's change (SDK 0.55.11). `created` and `deleted` are exact. `changed` means the file
+ * exists and its facts are as given; the host says `created` only when it knows the file is new,
+ * so a consumer that has no record of a `changed` file treats it as added. `metadataOnly` marks a
+ * change of version state alone: the bytes did not change. A `deleted` change carries no facts;
+ * every other change does. There is no rename: a rename is a delete plus a create.
+ */
+export declare const ArtifactOutputFileChange: z.ZodObject<{
+    uri: z.ZodString;
+    kind: z.ZodEnum<{
+        created: "created";
+        changed: "changed";
+        deleted: "deleted";
+    }>;
+    file: z.ZodOptional<z.ZodObject<{
+        sizeBytes: z.ZodNumber;
+        modifiedAtMs: z.ZodNumber;
+        title: z.ZodString;
+        mimeType: z.ZodOptional<z.ZodString>;
+        versionState: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            state: z.ZodLiteral<"draft">;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodEnum<{
+                clean: "clean";
+                edited: "edited";
+            }>;
+            committedVersion: z.ZodNumber;
+        }, z.core.$strict>], "state">>;
+    }, z.core.$strict>>;
+    metadataOnly: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strict>;
+
+export declare type ArtifactOutputFileChange = z.infer<typeof ArtifactOutputFileChange>;
+
+/**
+ * What the host knows about one output file without reading its body (SDK 0.55.11): its size and
+ * modified time from one stat, its title (a Markdown file's first `# ` heading within its first
+ * 4 KB, else its name), its type from the name, and its committed-version state when the chat
+ * has a version history.
+ */
+export declare const ArtifactOutputFileFacts: z.ZodObject<{
+    sizeBytes: z.ZodNumber;
+    modifiedAtMs: z.ZodNumber;
+    title: z.ZodString;
+    mimeType: z.ZodOptional<z.ZodString>;
+    versionState: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        state: z.ZodLiteral<"draft">;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodEnum<{
+            clean: "clean";
+            edited: "edited";
+        }>;
+        committedVersion: z.ZodNumber;
+    }, z.core.$strict>], "state">>;
+}, z.core.$strict>;
+
+export declare type ArtifactOutputFileFacts = z.infer<typeof ArtifactOutputFileFacts>;
+
 export declare const ArtifactOutputUri: z.ZodString;
 
+/** A file's committed-version label, as the host's listing reports it. */
+export declare const ArtifactOutputVersionState: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    state: z.ZodLiteral<"draft">;
+}, z.core.$strict>, z.ZodObject<{
+    state: z.ZodEnum<{
+        clean: "clean";
+        edited: "edited";
+    }>;
+    committedVersion: z.ZodNumber;
+}, z.core.$strict>], "state">;
+
+export declare type ArtifactOutputVersionState = z.infer<typeof ArtifactOutputVersionState>;
+
 export declare const ArtifactProvenanceActor: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"session">;
     sessionId: z.ZodString;
@@ -3021,6 +3124,7 @@ declare const canonicalContributionSchemas: {
         localId: z.ZodString;
         slot: z.ZodString;
         title: z.ZodOptional<z.ZodString>;
+        app: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
     ReferenceOpenBehavior: z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"working-document">;
@@ -3282,6 +3386,7 @@ declare const canonicalContributionSchemas: {
         "artifacts.preview": "artifacts.preview";
         "markdown.document-view": "markdown.document-view";
         "references.open": "references.open";
+        "files.choose-folder": "files.choose-folder";
         "billing.read": "billing.read";
         "account.read": "account.read";
         "plugins.read": "plugins.read";
@@ -3320,6 +3425,7 @@ declare const canonicalContributionSchemas: {
             "artifacts.preview": "artifacts.preview";
             "markdown.document-view": "markdown.document-view";
             "references.open": "references.open";
+            "files.choose-folder": "files.choose-folder";
             "billing.read": "billing.read";
             "account.read": "account.read";
             "plugins.read": "plugins.read";
@@ -3356,6 +3462,13 @@ declare const canonicalContributionSchemas: {
                 localId: z.ZodString;
             }, z.core.$strict>]>;
             where: z.ZodOptional<z.ZodString>;
+            also: z.ZodOptional<z.ZodObject<{
+                source: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    pluginId: z.ZodString;
+                    localId: z.ZodString;
+                }, z.core.$strict>]>;
+                where: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
             label: z.ZodObject<{
                 one: z.ZodOptional<z.ZodString>;
                 other: z.ZodString;
@@ -3426,6 +3539,7 @@ declare const canonicalContributionSchemas: {
                 "artifacts.preview": "artifacts.preview";
                 "markdown.document-view": "markdown.document-view";
                 "references.open": "references.open";
+                "files.choose-folder": "files.choose-folder";
                 "billing.read": "billing.read";
                 "account.read": "account.read";
                 "plugins.read": "plugins.read";
@@ -3481,6 +3595,7 @@ declare const canonicalContributionSchemas: {
                 "artifacts.preview": "artifacts.preview";
                 "markdown.document-view": "markdown.document-view";
                 "references.open": "references.open";
+                "files.choose-folder": "files.choose-folder";
                 "billing.read": "billing.read";
                 "account.read": "account.read";
                 "plugins.read": "plugins.read";
@@ -5004,8 +5119,25 @@ export declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * compacts with). A plugin preparing a reset text reads them to spend nothing on a session whose
  * reset would not read it (compaction plan, phase 2, #16713). Additive; a plugin reading them
  * declares ^0.55.10.
+ *
+ * 0.55.11 widens `app.artifacts.outputs()` for the Files table (#15965). A `{ uris }` change may
+ * carry `changes`: for each file, `created`, `changed` or `deleted`, with its size, modified
+ * time, title, type and committed-version state (`ArtifactOutputFileFacts`). `enumerate` takes
+ * `facts` and then returns the same facts per item (and an `excluded` count of names the output
+ * identity cannot carry), the new optional `folderMarks()` answers each chat's outputs-folder
+ * modified time, and the new optional `chatsWithOutputs()` lists every chat with an outputs folder
+ * from one scan. The `{ uris }` and `{ sessionId }` shapes stay valid. Additive; a plugin reading
+ * the new fields declares ^0.55.11.
+ *
+ * 0.55.12 raises the reset text's cap (compaction plan, 11 Nov): `RESET_TEXT_MAX_CHARS` goes from
+ * 18,000 to 31,500 characters, and the new `RESET_TEXT_MAX_TOKENS` (10,500) states the same cap in
+ * herd's estimated tokens, which herd's own check now allows. Compatible: every entry valid before
+ * is still valid. An entry over 18,000 characters, read by a host before 0.55.12 (an older app
+ * opening the same transcript), fails that host's parse and its reset writes the summary, as for
+ * any entry it cannot use. A plugin writing such a text, or reading the token cap, declares
+ * ^0.55.12; no other plugin's range changes.
  */
-export declare const KAY_PLUGIN_SDK_VERSION: "0.55.10";
+export declare const KAY_PLUGIN_SDK_VERSION: "0.55.12";
 
 export declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -6879,6 +7011,7 @@ export declare const KayPluginManifestV1: z.ZodObject<{
                         localId: z.ZodString;
                         slot: z.ZodString;
                         title: z.ZodOptional<z.ZodString>;
+                        app: z.ZodOptional<z.ZodString>;
                     }, z.core.$strict>>>;
                     referencePresentations: z.ZodOptional<z.ZodArray<z.ZodObject<{
                         localId: z.ZodString;
@@ -7037,6 +7170,7 @@ export declare const KayPluginManifestV1: z.ZodObject<{
                                 "artifacts.preview": "artifacts.preview";
                                 "markdown.document-view": "markdown.document-view";
                                 "references.open": "references.open";
+                                "files.choose-folder": "files.choose-folder";
                                 "billing.read": "billing.read";
                                 "account.read": "account.read";
                                 "plugins.read": "plugins.read";
@@ -7092,6 +7226,7 @@ export declare const KayPluginManifestV1: z.ZodObject<{
                                 "artifacts.preview": "artifacts.preview";
                                 "markdown.document-view": "markdown.document-view";
                                 "references.open": "references.open";
+                                "files.choose-folder": "files.choose-folder";
                                 "billing.read": "billing.read";
                                 "account.read": "account.read";
                                 "plugins.read": "plugins.read";
@@ -7129,6 +7264,13 @@ export declare const KayPluginManifestV1: z.ZodObject<{
                                 localId: z.ZodString;
                             }, z.core.$strict>]>;
                             where: z.ZodOptional<z.ZodString>;
+                            also: z.ZodOptional<z.ZodObject<{
+                                source: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                                    pluginId: z.ZodString;
+                                    localId: z.ZodString;
+                                }, z.core.$strict>]>;
+                                where: z.ZodOptional<z.ZodString>;
+                            }, z.core.$strict>>;
                             label: z.ZodObject<{
                                 one: z.ZodOptional<z.ZodString>;
                                 other: z.ZodString;
@@ -8118,6 +8260,7 @@ export declare const KayUiAppHostCapability: z.ZodEnum<{
     "artifacts.preview": "artifacts.preview";
     "markdown.document-view": "markdown.document-view";
     "references.open": "references.open";
+    "files.choose-folder": "files.choose-folder";
     "billing.read": "billing.read";
     "account.read": "account.read";
     "plugins.read": "plugins.read";
@@ -8253,6 +8396,7 @@ export declare const KayUiTargetManifest: z.ZodObject<{
             localId: z.ZodString;
             slot: z.ZodString;
             title: z.ZodOptional<z.ZodString>;
+            app: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>>;
         referencePresentations: z.ZodOptional<z.ZodArray<z.ZodObject<{
             localId: z.ZodString;
@@ -8411,6 +8555,7 @@ export declare const KayUiTargetManifest: z.ZodObject<{
                     "artifacts.preview": "artifacts.preview";
                     "markdown.document-view": "markdown.document-view";
                     "references.open": "references.open";
+                    "files.choose-folder": "files.choose-folder";
                     "billing.read": "billing.read";
                     "account.read": "account.read";
                     "plugins.read": "plugins.read";
@@ -8466,6 +8611,7 @@ export declare const KayUiTargetManifest: z.ZodObject<{
                     "artifacts.preview": "artifacts.preview";
                     "markdown.document-view": "markdown.document-view";
                     "references.open": "references.open";
+                    "files.choose-folder": "files.choose-folder";
                     "billing.read": "billing.read";
                     "account.read": "account.read";
                     "plugins.read": "plugins.read";
@@ -8503,6 +8649,13 @@ export declare const KayUiTargetManifest: z.ZodObject<{
                     localId: z.ZodString;
                 }, z.core.$strict>]>;
                 where: z.ZodOptional<z.ZodString>;
+                also: z.ZodOptional<z.ZodObject<{
+                    source: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                        pluginId: z.ZodString;
+                        localId: z.ZodString;
+                    }, z.core.$strict>]>;
+                    where: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>>;
                 label: z.ZodObject<{
                     one: z.ZodOptional<z.ZodString>;
                     other: z.ZodString;
@@ -8835,7 +8988,7 @@ export declare function parseSemver(value: string): ParsedSemver | undefined;
 export declare function parseWhere(source: string, keyTypes?: WhereKeyTypes): WhereParseResult;
 
 /** 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", "sessions.read", "signals.read", "uri.call", "endpoints.invoke", "skills.read", "skills.write", "skills.share", "plugins.set-enabled", "plugins.read", "sessions.assign-project", "artifacts.resolve-file", "process.run", "sessions.annotate", "sessions.compact", "sessions.state", "compaction.reset-text", "soul.write", "tools.describe", "workspace.command", "sessions.create", "sessions.update", "models.complete", "systemOne.use", "automations.write", "automations.run", "workflows.define", "workflows.signals", "session-events.subscribe", "agents.run", "dynamic-context.register", "app-data.register", "app-data.read", "knowledge-source.register", "artifacts.read", "session-artifacts.read", "session-artifacts.create", "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", "family-folder.root", "whiteboard.discover", "whiteboard.read", "whiteboard.create", "whiteboard.update", "whiteboard.remove", "model-selection.register", "system-prompt.register"];
+export declare const PLUGIN_CAPABILITY_SLUGS: readonly ["sessions.run", "network.connect", "web-session.request", "web-session.download", "process.spawn", "sessions.read", "signals.read", "uri.call", "endpoints.invoke", "skills.read", "skills.write", "skills.share", "plugins.set-enabled", "plugins.read", "sessions.assign-project", "artifacts.resolve-file", "process.run", "sessions.annotate", "sessions.compact", "sessions.state", "compaction.reset-text", "soul.write", "tools.describe", "workspace.command", "sessions.create", "sessions.update", "models.complete", "systemOne.use", "automations.write", "automations.run", "workflows.define", "workflows.signals", "session-events.subscribe", "agents.run", "dynamic-context.register", "app-data.register", "app-data.read", "knowledge-source.register", "artifacts.read", "session-artifacts.read", "session-artifacts.create", "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", "family-folder.root", "messages.send", "whiteboard.discover", "whiteboard.read", "whiteboard.create", "whiteboard.update", "whiteboard.remove", "model-selection.register", "system-prompt.register"];
 
 /** 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. */
@@ -9612,6 +9765,12 @@ export declare const PluginCapabilityClaimInputV1: z.ZodCustom<{
     target: "kay.app";
     slug: "workspace.command";
     envelope: Record<string, never>;
+} | {
+    target: "kay.app";
+    slug: "messages.send";
+    envelope: {
+        provider: string;
+    };
 } | {
     target: "kay.app";
     slug: "sessions.create";
@@ -9914,6 +10073,12 @@ export declare const PluginCapabilityClaimInputV1: z.ZodCustom<{
     target: "kay.app";
     slug: "workspace.command";
     envelope: Record<string, never>;
+} | {
+    target: "kay.app";
+    slug: "messages.send";
+    envelope: {
+        provider: string;
+    };
 } | {
     target: "kay.app";
     slug: "sessions.create";
@@ -10226,6 +10391,12 @@ export declare const PluginCapabilityClaimV1: z.ZodDiscriminatedUnion<[z.ZodObje
     target: z.ZodLiteral<"kay.app">;
     slug: z.ZodLiteral<"workspace.command">;
     envelope: z.ZodObject<{}, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    target: z.ZodLiteral<"kay.app">;
+    slug: z.ZodLiteral<"messages.send">;
+    envelope: z.ZodObject<{
+        provider: z.ZodString;
+    }, z.core.$strict>;
 }, z.core.$strict>, z.ZodObject<{
     target: z.ZodLiteral<"kay.app">;
     slug: z.ZodLiteral<"sessions.create">;
@@ -10584,6 +10755,12 @@ export declare const PluginCapabilityDecisionV1: z.ZodDiscriminatedUnion<[z.ZodO
         target: z.ZodLiteral<"kay.app">;
         slug: z.ZodLiteral<"workspace.command">;
         envelope: z.ZodObject<{}, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"kay.app">;
+        slug: z.ZodLiteral<"messages.send">;
+        envelope: z.ZodObject<{
+            provider: z.ZodString;
+        }, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         target: z.ZodLiteral<"kay.app">;
         slug: z.ZodLiteral<"sessions.create">;
@@ -10941,6 +11118,12 @@ export declare const PluginCapabilityDecisionV1: z.ZodDiscriminatedUnion<[z.ZodO
             target: z.ZodLiteral<"kay.app">;
             slug: z.ZodLiteral<"workspace.command">;
             envelope: z.ZodObject<{}, z.core.$strict>;
+        }, z.core.$strict>, z.ZodObject<{
+            target: z.ZodLiteral<"kay.app">;
+            slug: z.ZodLiteral<"messages.send">;
+            envelope: z.ZodObject<{
+                provider: z.ZodString;
+            }, z.core.$strict>;
         }, z.core.$strict>, z.ZodObject<{
             target: z.ZodLiteral<"kay.app">;
             slug: z.ZodLiteral<"sessions.create">;
@@ -11332,6 +11515,12 @@ export declare const PluginCapabilityRefusalV1: z.ZodObject<{
         target: z.ZodLiteral<"kay.app">;
         slug: z.ZodLiteral<"workspace.command">;
         envelope: z.ZodObject<{}, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"kay.app">;
+        slug: z.ZodLiteral<"messages.send">;
+        envelope: z.ZodObject<{
+            provider: z.ZodString;
+        }, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         target: z.ZodLiteral<"kay.app">;
         slug: z.ZodLiteral<"sessions.create">;
@@ -13259,10 +13448,20 @@ export declare const RENAMED_PLUGIN_CAPABILITY_SLUGS: {
 export declare const RESERVED_DIRECTORY_PLUGIN_ID_PREFIXES: readonly ["herd.", "kay."];
 
 /**
- * The longest text an entry may hold, in characters: herd's 6,000 estimated tokens at its three
+ * The longest text an entry may hold, in characters: {@link RESET_TEXT_MAX_TOKENS} at herd's three
  * characters per token for ASCII. Herd also counts the tokens, so denser text is refused sooner.
  */
-export declare const RESET_TEXT_MAX_CHARS = 18000;
+export declare const RESET_TEXT_MAX_CHARS: number;
+
+/**
+ * The most a reset text may hold, in herd's estimated tokens: about 3 characters a token for ASCII,
+ * one token for any other character (`estimateTokens` in herd's compaction executor, which a
+ * plugin's count must repeat). Herd refuses a larger text and writes today's summary
+ * (`PREPARED_STATE_MAX_TOKENS`, kept equal to this by a test in `@bonsai/agent-runtime`). 10,500
+ * fits the median record render the compaction plan chose, about 30,000 characters; a larger render
+ * is trimmed to fit (`docs/plans/compaction.md`, decision log, 11 Nov).
+ */
+export declare const RESET_TEXT_MAX_TOKENS = 10500;
 
 /** The `contributes.resetText` declaration: which of the plugin's state entries holds it. */
 export declare const ResetTextContribution: z.ZodObject<{
@@ -13984,6 +14183,7 @@ export declare const ResolvedKayUiApp: z.ZodObject<{
             "artifacts.preview": "artifacts.preview";
             "markdown.document-view": "markdown.document-view";
             "references.open": "references.open";
+            "files.choose-folder": "files.choose-folder";
             "billing.read": "billing.read";
             "account.read": "account.read";
             "plugins.read": "plugins.read";
@@ -15908,6 +16108,7 @@ export declare const ResolvedPluginContractV1: z.ZodObject<{
                 "artifacts.preview": "artifacts.preview";
                 "markdown.document-view": "markdown.document-view";
                 "references.open": "references.open";
+                "files.choose-folder": "files.choose-folder";
                 "billing.read": "billing.read";
                 "account.read": "account.read";
                 "plugins.read": "plugins.read";
@@ -17814,6 +18015,7 @@ export declare const UiAppCapabilities: z.ZodObject<{
         "artifacts.preview": "artifacts.preview";
         "markdown.document-view": "markdown.document-view";
         "references.open": "references.open";
+        "files.choose-folder": "files.choose-folder";
         "billing.read": "billing.read";
         "account.read": "account.read";
         "plugins.read": "plugins.read";
@@ -17879,6 +18081,7 @@ export declare const UiAppContribution: z.ZodObject<{
             "artifacts.preview": "artifacts.preview";
             "markdown.document-view": "markdown.document-view";
             "references.open": "references.open";
+            "files.choose-folder": "files.choose-folder";
             "billing.read": "billing.read";
             "account.read": "account.read";
             "plugins.read": "plugins.read";
@@ -17934,6 +18137,7 @@ export declare const UiAppContribution: z.ZodObject<{
             "artifacts.preview": "artifacts.preview";
             "markdown.document-view": "markdown.document-view";
             "references.open": "references.open";
+            "files.choose-folder": "files.choose-folder";
             "billing.read": "billing.read";
             "account.read": "account.read";
             "plugins.read": "plugins.read";
@@ -18046,6 +18250,13 @@ export declare const UiRailEntryContribution: z.ZodObject<{
             localId: z.ZodString;
         }, z.core.$strict>]>;
         where: z.ZodOptional<z.ZodString>;
+        also: z.ZodOptional<z.ZodObject<{
+            source: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                pluginId: z.ZodString;
+                localId: z.ZodString;
+            }, z.core.$strict>]>;
+            where: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
         label: z.ZodObject<{
             one: z.ZodOptional<z.ZodString>;
             other: z.ZodString;
@@ -18066,6 +18277,7 @@ export declare const UiSlotContribution: z.ZodObject<{
     localId: z.ZodString;
     slot: z.ZodString;
     title: z.ZodOptional<z.ZodString>;
+    app: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 
 export declare type UiSlotContribution = z.infer<typeof UiSlotContribution>;

package/dist/index.js

@@ -260,8 +260,10 @@ var JsonSchema = z4.record(z4.string(), JsonValue);
 var KAY_PLUGIN_MANIFEST_SIZE_CAP_BYTES = 1024 * 1024;
 var KAY_PLUGIN_PROTOCOL_VERSION = "kay.plugin.v1";
 var KAY_PLUGIN_PROTOCOL_PACKAGE_NAME = "@bonsai/plugin-protocol";
-var KAY_PLUGIN_SDK_VERSION = "0.55.10";
+var KAY_PLUGIN_SDK_VERSION = "0.55.12";
 var KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS = [
+  "0.55.11",
+  "0.55.10",
   "0.55.9",
   "0.55.8",
   "0.55.7",
@@ -1856,6 +1858,7 @@ var PLUGIN_CAPABILITY_SLUGS = [
   "prompt.resident",
   "skills.declared-source",
   "family-folder.root",
+  "messages.send",
   "whiteboard.discover",
   "whiteboard.read",
   "whiteboard.create",
@@ -2109,6 +2112,14 @@ function createAuthoritySchemas(canonical) {
       slug: z11.literal("workspace.command"),
       envelope: z11.strictObject({})
     }),
+    z11.strictObject({
+      // Prepare and send replies through one provider (`app.messages`). Preparing reads who a
+      // message's reply goes to, so it needs this claim too; sending also needs the person's
+      // command on the plugin's own page.
+      target: z11.literal("kay.app"),
+      slug: z11.literal("messages.send"),
+      envelope: z11.strictObject({ provider: NonEmptyString3.max(100) })
+    }),
     z11.strictObject({
       target: z11.literal("kay.app"),
       slug: z11.literal("sessions.create"),
@@ -2431,6 +2442,8 @@ function sameClaim(a, b) {
       return true;
     case "uri.call":
       return b.slug === "uri.call" && a.envelope.scheme === b.envelope.scheme && a.envelope.verb === b.envelope.verb;
+    case "messages.send":
+      return b.slug === "messages.send" && a.envelope.provider === b.envelope.provider;
     case "endpoints.invoke":
       return b.slug === "endpoints.invoke" && a.envelope.pluginId === b.envelope.pluginId && a.envelope.endpointId === b.envelope.endpointId;
     case "network.connect":
@@ -2532,6 +2545,8 @@ function envelopePairs(a, b) {
         [a.envelope.scheme, b.envelope.scheme],
         [a.envelope.verb, b.envelope.verb]
       ] : [];
+    case "messages.send":
+      return b.slug === "messages.send" ? [[a.envelope.provider, b.envelope.provider]] : [];
     case "endpoints.invoke":
       return b.slug === "endpoints.invoke" ? [
         [a.envelope.pluginId, b.envelope.pluginId],
@@ -4339,7 +4354,12 @@ function createContributionsSchemas(canonical) {
   const UiSlotContribution2 = z14.strictObject({
     localId: LocalContributionId2,
     slot: NonEmptyString3,
-    title: NonEmptyString3.optional()
+    title: NonEmptyString3.optional(),
+    /**
+     * The `contextOnly` app in this plugin that fills the slot. Home reads `home.tasks` this way:
+     * it mounts that app in each Home pane.
+     */
+    app: LocalContributionId2.optional()
   });
   const NOT_LOCAL_APP_SCHEMES = /* @__PURE__ */ new Set([
     "http",
@@ -4577,6 +4597,9 @@ function createContributionsSchemas(canonical) {
     // Draws links the host resolves and opens (`BonsaiReferencePill`, `BonsaiReferenceRow`,
     // `BonsaiReferenceMarkdown`). A person's click on one can open a session or another plugin's page.
     "references.open",
+    // Opens the system folder picker when the person acts (`useBonsaiFolderPicker`) and answers
+    // the one folder they chose, or nothing when they cancel. It lists and reads nothing.
+    "files.choose-folder",
     // Server-rated organization billing, distinct from local/provider cost.
     "billing.read",
     "account.read",
@@ -4642,20 +4665,33 @@ function createContributionsSchemas(canonical) {
   const UiRailBadge = z14.strictObject({
     source: UiAppCapabilityReference2,
     where: NonEmptyString3.optional(),
+    /**
+     * A second rows source the count adds, with its own `where`: for a page that tends two kinds
+     * of thing kept by different plugins. The label's `${count}` is the sum.
+     */
+    also: z14.strictObject({
+      source: UiAppCapabilityReference2,
+      where: NonEmptyString3.optional()
+    }).optional(),
     label: z14.strictObject({
       one: NonEmptyString3.optional(),
       other: NonEmptyString3
     })
   }).superRefine((badge, ctx) => {
-    if (badge.where === void 0)
-      return;
-    const parsed = parseWhere(badge.where);
-    if (!parsed.ok) {
-      ctx.addIssue({
-        code: "custom",
-        path: ["where"],
-        message: `rail badge has an invalid where: ${parsed.message}`
-      });
+    for (const [path, where] of [
+      [["where"], badge.where],
+      [["also", "where"], badge.also?.where]
+    ]) {
+      if (where === void 0)
+        continue;
+      const parsed = parseWhere(where);
+      if (!parsed.ok) {
+        ctx.addIssue({
+          code: "custom",
+          path: [...path],
+          message: `rail badge has an invalid where: ${parsed.message}`
+        });
+      }
     }
   });
   const UiRailEntryContribution2 = z14.strictObject({
@@ -4991,7 +5027,8 @@ function isPluginStateEntryCustomType(customType) {
 }
 
 // packages/plugin-protocol/dist/reset-text.js
-var RESET_TEXT_MAX_CHARS = 18e3;
+var RESET_TEXT_MAX_TOKENS = 10500;
+var RESET_TEXT_MAX_CHARS = RESET_TEXT_MAX_TOKENS * 3;
 var EntryAddress = z18.strictObject({
   sessionId: z18.string().min(1),
   entryId: z18.string().min(1)
@@ -5716,12 +5753,17 @@ function createManifestSchemas(canonical) {
         index,
         "badge"
       ];
-      if (typeof entry.badge.source === "string" && !declaredRowsStores.has(entry.badge.source)) {
-        ctx.addIssue({
-          code: "custom",
-          path: [...path, "source"],
-          message: `rail entry ${entry.id} counts ${entry.badge.source}, which is not one of this plugin's data sources with a rows store`
-        });
+      for (const [at, source] of [
+        [["source"], entry.badge.source],
+        [["also", "source"], entry.badge.also?.source]
+      ]) {
+        if (typeof source === "string" && !declaredRowsStores.has(source)) {
+          ctx.addIssue({
+            code: "custom",
+            path: [...path, ...at],
+            message: `rail entry ${entry.id} counts ${source}, which is not one of this plugin's data sources with a rows store`
+          });
+        }
       }
     }
     for (const source of declaredAppDataSources) {
@@ -5783,6 +5825,26 @@ function createManifestSchemas(canonical) {
         });
       }
     }
+    for (const [index, slot] of (manifest.targets?.kay?.ui?.contributes?.slots ?? []).entries()) {
+      if (slot.app === void 0)
+        continue;
+      const app = manifest.targets?.kay?.ui?.contributes?.apps?.find((candidate) => candidate.localId === slot.app);
+      if (app === void 0 || app.contextOnly !== true) {
+        ctx.addIssue({
+          code: "custom",
+          path: [
+            "targets",
+            "kay",
+            "ui",
+            "contributes",
+            "slots",
+            index,
+            "app"
+          ],
+          message: app === void 0 ? `Slot ${slot.localId} names app ${slot.app}, which this plugin does not declare` : `Slot ${slot.localId} app ${app.localId} must be a contextOnly ui app`
+        });
+      }
+    }
     const notificationRuleIds = new Set(manifest.targets?.kay?.app?.contributes?.notificationRules?.map((rule) => rule.localId) ?? []);
     const previewedRules = /* @__PURE__ */ new Set();
     for (const [index, preview] of (manifest.targets?.kay?.ui?.contributes?.toastPreviews ?? []).entries()) {
@@ -8479,10 +8541,32 @@ function isCanonicalArtifactOutputUri(uri) {
   return parseArtifactOutputUri(uri) !== void 0;
 }
 var ArtifactOutputUri = z27.string().refine(isCanonicalArtifactOutputUri, "Expected a canonical output://session/name URI");
+var ARTIFACT_OUTPUT_FOLDER_MARKS_MAX = 500;
+var ArtifactOutputVersionState = z27.discriminatedUnion("state", [
+  z27.strictObject({ state: z27.literal("draft") }),
+  z27.strictObject({
+    state: z27.enum(["clean", "edited"]),
+    committedVersion: z27.number().int().positive()
+  })
+]);
+var ArtifactOutputFileFacts = z27.strictObject({
+  sizeBytes: z27.number().finite().nonnegative(),
+  modifiedAtMs: z27.number().finite().nonnegative(),
+  title: z27.string().min(1).max(4096),
+  mimeType: z27.string().min(1).max(255).optional(),
+  versionState: ArtifactOutputVersionState.optional()
+});
+var ArtifactOutputFileChange = z27.strictObject({
+  uri: ArtifactOutputUri,
+  kind: z27.enum(["created", "changed", "deleted"]),
+  file: ArtifactOutputFileFacts.optional(),
+  metadataOnly: z27.literal(true).optional()
+}).refine((change) => change.kind === "deleted" === (change.file === void 0), "A deleted change carries no facts; every other change carries them.");
 var ArtifactOutputChange = z27.union([
   z27.strictObject({
-    uris: z27.array(ArtifactOutputUri).min(1).max(ARTIFACT_OUTPUT_PAGE_MAX)
-  }),
+    uris: z27.array(ArtifactOutputUri).min(1).max(ARTIFACT_OUTPUT_PAGE_MAX),
+    changes: z27.array(ArtifactOutputFileChange).min(1).max(ARTIFACT_OUTPUT_PAGE_MAX).optional()
+  }).refine((change) => change.changes === void 0 || change.changes.length === change.uris.length && change.changes.every((file, index) => file.uri === change.uris[index]), "Each change names the URI at the same position in uris."),
   z27.strictObject({ sessionId: Segment })
 ]);
 
@@ -8584,6 +8668,7 @@ export {
   AGENT_RUNTIME_SESSION_CREATOR_KINDS,
   APPROVAL_ANSWERS,
   APPROVAL_KINDS,
+  ARTIFACT_OUTPUT_FOLDER_MARKS_MAX,
   ARTIFACT_OUTPUT_PAGE_MAX,
   ARTIFACT_PROVENANCE_VERSION,
   AccessApprovalReview,
@@ -8602,7 +8687,10 @@ export {
   ApprovalTypeContribution,
   ArtifactGenerationId,
   ArtifactOutputChange,
+  ArtifactOutputFileChange,
+  ArtifactOutputFileFacts,
   ArtifactOutputUri,
+  ArtifactOutputVersionState,
   ArtifactProvenanceActor,
   ArtifactProvenanceCaptureContextSchema,
   ArtifactProvenanceCause,
@@ -8771,6 +8859,7 @@ export {
   RENAMED_PLUGIN_CAPABILITY_SLUGS,
   RESERVED_DIRECTORY_PLUGIN_ID_PREFIXES,
   RESET_TEXT_MAX_CHARS,
+  RESET_TEXT_MAX_TOKENS,
   RETIRED_COMPATIBILITY_KEYS,
   RETIRED_PERMISSION_ASK_KEYS,
   RETIRED_PLUGIN_CAPABILITY_SLUGS,

package/package.json

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