@yaklabs-ai/plugin-protocol 0.55.4 → 0.55.5

package/README.md

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

package/THIRD-PARTY-INVENTORY.json

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

package/dist/index.d.ts

@@ -4138,6 +4138,9 @@ export declare function isKayPluginCompatibilityRefusal(code: string): code is K
 /** Whether `name` can name a declared event: the shape above, and not the journal's own family. */
 export declare function isPluginProductEventName(name: string): boolean;
 
+/** Whether a custom entry type is a plugin state entry's. */
+export declare function isPluginStateEntryCustomType(customType: string): boolean;
+
 /** Whether only plugins the release carries may hold `claim` ({@link PRIVATE_PLUGIN_CAPABILITY_SLUGS}). */
 export declare function isPrivateCapabilityClaim(claim: PluginCapabilityClaimV1): boolean;
 
@@ -4968,8 +4971,14 @@ export declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * of the installed, enabled plugins, with the plugin's id and display name and whether the person
  * has connected it. No account, identity or scope. Built-ins hold the claim; any other plugin needs
  * a grant. Additive; plugins calling it declare ^0.55.4.
+ *
+ * 0.55.5 adds `app.sessions.readState()` and `writeState()` under the new `sessions.state` claim:
+ * a plugin keeps its own state entries in a session's transcript, stored as `plugin-state:<pluginId>:<name>`,
+ * and each write names the newest entry it was computed from, so a write from a stale base is
+ * answered with the newest one instead of landing (compaction plan, phase 2). Additive; plugins
+ * calling them declare ^0.55.5.
  */
-export declare const KAY_PLUGIN_SDK_VERSION: "0.55.4";
+export declare const KAY_PLUGIN_SDK_VERSION: "0.55.5";
 
 export declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -8791,7 +8800,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", "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", "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"];
 
 /** 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. */
@@ -8846,6 +8855,25 @@ export declare const PLUGIN_SIGNAL_SNIPPET_MAX = 500;
 
 export declare const PLUGIN_SIGNAL_TITLE_MAX = 300;
 
+/**
+ * The most one entry may hold, as serialized UTF-8 JSON: 256 KiB, a quarter of what one
+ * `session/readCustomEntries` read returns, so the newest entry is always read back whole.
+ */
+export declare const PLUGIN_STATE_ENTRY_MAX_BYTES: number;
+
+/** The deepest nesting of arrays and objects one entry may hold. */
+export declare const PLUGIN_STATE_ENTRY_MAX_DEPTH = 64;
+
+/** A plugin's own entry name: a local contribution id (lowercase letters, digits, dashes), at most 64 characters. */
+export declare const PLUGIN_STATE_ENTRY_NAME_PATTERN: RegExp;
+
+/**
+ * The prefix of every plugin state entry's custom type. Its own namespace, apart from herd's
+ * `ext:<extensionId>:` for an extension's own entries, so the host can tell a plugin's state
+ * from every other entry: it is no activity, and a snapshot carries only its newest entry.
+ */
+export declare const PLUGIN_STATE_ENTRY_TYPE_PREFIX = "plugin-state:";
+
 export declare const PluginAgentDefinitionPermissionRule: z.ZodObject<{
     effect: z.ZodEnum<{
         allow: "allow";
@@ -9529,6 +9557,10 @@ export declare const PluginCapabilityClaimInputV1: z.ZodCustom<{
     target: "kay.app";
     slug: "sessions.compact";
     envelope: Record<string, never>;
+} | {
+    target: "kay.app";
+    slug: "sessions.state";
+    envelope: Record<string, never>;
 } | {
     target: "kay.app";
     slug: "soul.write";
@@ -9823,6 +9855,10 @@ export declare const PluginCapabilityClaimInputV1: z.ZodCustom<{
     target: "kay.app";
     slug: "sessions.compact";
     envelope: Record<string, never>;
+} | {
+    target: "kay.app";
+    slug: "sessions.state";
+    envelope: Record<string, never>;
 } | {
     target: "kay.app";
     slug: "soul.write";
@@ -10127,6 +10163,10 @@ export declare const PluginCapabilityClaimV1: z.ZodDiscriminatedUnion<[z.ZodObje
     target: z.ZodLiteral<"kay.app">;
     slug: z.ZodLiteral<"sessions.compact">;
     envelope: z.ZodObject<{}, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    target: z.ZodLiteral<"kay.app">;
+    slug: z.ZodLiteral<"sessions.state">;
+    envelope: z.ZodObject<{}, z.core.$strict>;
 }, z.core.$strict>, z.ZodObject<{
     target: z.ZodLiteral<"kay.app">;
     slug: z.ZodLiteral<"soul.write">;
@@ -10477,6 +10517,10 @@ export declare const PluginCapabilityDecisionV1: z.ZodDiscriminatedUnion<[z.ZodO
         target: z.ZodLiteral<"kay.app">;
         slug: z.ZodLiteral<"sessions.compact">;
         envelope: z.ZodObject<{}, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"kay.app">;
+        slug: z.ZodLiteral<"sessions.state">;
+        envelope: z.ZodObject<{}, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         target: z.ZodLiteral<"kay.app">;
         slug: z.ZodLiteral<"soul.write">;
@@ -10826,6 +10870,10 @@ export declare const PluginCapabilityDecisionV1: z.ZodDiscriminatedUnion<[z.ZodO
             target: z.ZodLiteral<"kay.app">;
             slug: z.ZodLiteral<"sessions.compact">;
             envelope: z.ZodObject<{}, z.core.$strict>;
+        }, z.core.$strict>, z.ZodObject<{
+            target: z.ZodLiteral<"kay.app">;
+            slug: z.ZodLiteral<"sessions.state">;
+            envelope: z.ZodObject<{}, z.core.$strict>;
         }, z.core.$strict>, z.ZodObject<{
             target: z.ZodLiteral<"kay.app">;
             slug: z.ZodLiteral<"soul.write">;
@@ -11209,6 +11257,10 @@ export declare const PluginCapabilityRefusalV1: z.ZodObject<{
         target: z.ZodLiteral<"kay.app">;
         slug: z.ZodLiteral<"sessions.compact">;
         envelope: z.ZodObject<{}, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"kay.app">;
+        slug: z.ZodLiteral<"sessions.state">;
+        envelope: z.ZodObject<{}, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         target: z.ZodLiteral<"kay.app">;
         slug: z.ZodLiteral<"soul.write">;
@@ -12695,6 +12747,14 @@ export declare const PluginSourceClass: z.ZodEnum<{
 
 export declare type PluginSourceClass = z.infer<typeof PluginSourceClass>;
 
+/**
+ * The custom entry type a plugin's entry `name` is stored under: `plugin-state:<pluginId>:<name>`.
+ * A plugin id holds no `:`, and the name grammar holds no `.`, `:` or `_`, so no kernel or daemon
+ * type (`herd.permission_rules`, `session_steward`, ...) and no other plugin's entry can be
+ * reached. Returns `undefined` for a name outside the grammar.
+ */
+export declare function pluginStateEntryCustomType(pluginId: string, name: string): string | undefined;
+
 export declare const PluginStorageManifest: z.ZodObject<{
     sqlite: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodBoolean;

package/dist/index.js

@@ -260,8 +260,9 @@ 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.4";
+var KAY_PLUGIN_SDK_VERSION = "0.55.5";
 var KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS = [
+  "0.55.4",
   "0.55.3",
   "0.55.2",
   "0.55.1",
@@ -1815,6 +1816,7 @@ var PLUGIN_CAPABILITY_SLUGS = [
   "process.run",
   "sessions.annotate",
   "sessions.compact",
+  "sessions.state",
   "soul.write",
   "tools.describe",
   "workspace.command",
@@ -2063,6 +2065,15 @@ function createAuthoritySchemas(canonical) {
       slug: z11.literal("sessions.compact"),
       envelope: z11.strictObject({})
     }),
+    z11.strictObject({
+      // Read and write this plugin's own state entries in a session's transcript
+      // (`app.sessions.readState` / `writeState`): custom entries stored under the plugin's own
+      // id, each write checked against the newest one. A write is bound like `sessions.annotate`
+      // to the session whose event the calling handler is answering; a read is not bound.
+      target: z11.literal("kay.app"),
+      slug: z11.literal("sessions.state"),
+      envelope: z11.strictObject({})
+    }),
     z11.strictObject({
       // Read and rewrite the soul file every new conversation is told. Private
       // (PRIVATE_PLUGIN_CAPABILITY_SLUGS): only a plugin the release carries may hold it.
@@ -2382,6 +2393,7 @@ function sameClaim(a, b) {
     case "process.run":
     case "sessions.annotate":
     case "sessions.compact":
+    case "sessions.state":
     case "soul.write":
     case "tools.describe":
     case "workspace.command":
@@ -2478,6 +2490,7 @@ function envelopePairs(a, b) {
     case "process.run":
     case "sessions.annotate":
     case "sessions.compact":
+    case "sessions.state":
     case "soul.write":
     case "tools.describe":
     case "workspace.command":
@@ -8073,6 +8086,18 @@ function sessionHealthPWellDecile(pWell) {
   return Math.min(9, Math.floor(pWell * 10));
 }
 
+// packages/plugin-protocol/dist/session-state.js
+var PLUGIN_STATE_ENTRY_NAME_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
+var PLUGIN_STATE_ENTRY_MAX_BYTES = 256 * 1024;
+var PLUGIN_STATE_ENTRY_MAX_DEPTH = 64;
+var PLUGIN_STATE_ENTRY_TYPE_PREFIX = "plugin-state:";
+function pluginStateEntryCustomType(pluginId, name) {
+  return PLUGIN_STATE_ENTRY_NAME_PATTERN.test(name) ? `${PLUGIN_STATE_ENTRY_TYPE_PREFIX}${pluginId}:${name}` : void 0;
+}
+function isPluginStateEntryCustomType(customType) {
+  return customType.startsWith(PLUGIN_STATE_ENTRY_TYPE_PREFIX);
+}
+
 // packages/plugin-protocol/dist/resource-invocations.js
 import { z as z23 } from "zod";
 
@@ -8638,6 +8663,10 @@ export {
   PLUGIN_SIGNAL_RELATED_KEYS,
   PLUGIN_SIGNAL_SNIPPET_MAX,
   PLUGIN_SIGNAL_TITLE_MAX,
+  PLUGIN_STATE_ENTRY_MAX_BYTES,
+  PLUGIN_STATE_ENTRY_MAX_DEPTH,
+  PLUGIN_STATE_ENTRY_NAME_PATTERN,
+  PLUGIN_STATE_ENTRY_TYPE_PREFIX,
   PRIVATE_PLUGIN_CAPABILITY_SLUGS,
   PackageAssetPath,
   PluginAgentDefinitionPermissionRule,
@@ -8830,6 +8859,7 @@ export {
   isDeclaredLocalAppLink,
   isKayPluginCompatibilityRefusal,
   isPluginProductEventName,
+  isPluginStateEntryCustomType,
   isPrivateCapabilityClaim,
   isQualifiedAuthSchemeRef,
   isQualifiedAuthServiceRef,
@@ -8854,6 +8884,7 @@ export {
   parseWhere,
   pluginIconShape,
   pluginSignalPayloadJsonSchema,
+  pluginStateEntryCustomType,
   precedingPersonMessages,
   readKayPluginDeclaredCompatibility,
   refineWebSessionScopeConfined,

package/package.json

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