@yaklabs-ai/plugin-sdk 0.55.4 → 0.55.5

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.55.4"
+    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.55.5"
   }
 }
 ```
@@ -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.55.4" },
+  "compatibility": { "sdk": "^0.55.5" },
   "targets": {
     "kay": {
       "agent": {
@@ -153,7 +153,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.55.4`).
+A plugin that imports these subpaths declares the current supported SDK range (`^0.55.5`).
 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
@@ -161,7 +161,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.55.4`).
+`VendoredMcpPort` and `VendoredMcpOutcome` (declare `^0.55.5`).
 
 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
@@ -243,7 +243,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.55.4`. The current host also serves the 0.49.0 resource contract.
+refused; migrate and declare `^0.55.5`. 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.55.4",
+  "version": "0.55.5",
   "target": "npm",
   "firstPartyLicense": "MIT",
   "bundled": [

package/dist/disclosure.d.ts

@@ -845,6 +845,12 @@ declare interface DerivedToolClassification {
     readonly kind?: ToolActionKind;
     readonly ruleKey?: string;
     readonly scheme?: string;
+    /**
+     * This call needs a person's one-time answer: no allow rule, no mode (allow mode included) and
+     * no automatic approver settles it, and the approval cannot be remembered. Deny rules still
+     * apply. Stricter only, so it grants nothing. The same flag a URI route classification carries.
+     */
+    readonly humanOnly?: true;
 }
 
 declare const Digit: TDigit;
@@ -1357,11 +1363,53 @@ declare interface InteractionActed {
  * afterwards when `submit` is set.
  */
 declare const InteractionAction: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"upload">;
+    element: z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            fill: "fill";
+            upload: "upload";
+            activate: "activate";
+            click: "click";
+            select: "select";
+            scroll: "scroll";
+            wait: "wait";
+            press: "press";
+        }>;
+        label: z.ZodString;
+        node: z.ZodOptional<z.ZodNumber>;
+        role: z.ZodOptional<z.ZodString>;
+        value: z.ZodOptional<z.ZodString>;
+        current_value: z.ZodOptional<z.ZodString>;
+        checked: z.ZodOptional<z.ZodString>;
+        selected: z.ZodOptional<z.ZodString>;
+        expanded: z.ZodOptional<z.ZodString>;
+        look: z.ZodOptional<z.ZodEnum<{
+            link: "link";
+            widget: "widget";
+        }>>;
+        delta: z.ZodOptional<z.ZodNumber>;
+        position: z.ZodOptional<z.ZodEnum<{
+            above: "above";
+            below: "below";
+            beside: "beside";
+        }>>;
+        region: z.ZodOptional<z.ZodObject<{
+            role: z.ZodString;
+            name: z.ZodString;
+            front: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>;
+        scroller: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>;
+    path: z.ZodString;
+    origin: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"click">;
     element: z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
             fill: "fill";
+            upload: "upload";
             activate: "activate";
             click: "click";
             select: "select";
@@ -1400,6 +1448,7 @@ declare const InteractionAction: z.ZodDiscriminatedUnion<[z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
             fill: "fill";
+            upload: "upload";
             activate: "activate";
             click: "click";
             select: "select";
@@ -1441,6 +1490,7 @@ declare const InteractionAction: z.ZodDiscriminatedUnion<[z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
             fill: "fill";
+            upload: "upload";
             activate: "activate";
             click: "click";
             select: "select";
@@ -1479,6 +1529,7 @@ declare const InteractionAction: z.ZodDiscriminatedUnion<[z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
             fill: "fill";
+            upload: "upload";
             activate: "activate";
             click: "click";
             select: "select";
@@ -1517,6 +1568,7 @@ declare const InteractionAction: z.ZodDiscriminatedUnion<[z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
             fill: "fill";
+            upload: "upload";
             activate: "activate";
             click: "click";
             select: "select";
@@ -1556,6 +1608,7 @@ declare const InteractionAction: z.ZodDiscriminatedUnion<[z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
             fill: "fill";
+            upload: "upload";
             activate: "activate";
             click: "click";
             select: "select";
@@ -1652,6 +1705,7 @@ declare const InteractionObservation: z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
             fill: "fill";
+            upload: "upload";
             activate: "activate";
             click: "click";
             select: "select";
@@ -2692,8 +2746,14 @@ 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.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.55.4";
+declare const KAY_PLUGIN_SDK_VERSION: "0.55.5";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 

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

@@ -810,6 +810,12 @@ declare interface DerivedToolClassification {
     readonly kind?: ToolActionKind;
     readonly ruleKey?: string;
     readonly scheme?: string;
+    /**
+     * This call needs a person's one-time answer: no allow rule, no mode (allow mode included) and
+     * no automatic approver settles it, and the approval cannot be remembered. Deny rules still
+     * apply. Stricter only, so it grants nothing. The same flag a URI route classification carries.
+     */
+    readonly humanOnly?: true;
 }
 
 /**
@@ -1393,11 +1399,53 @@ declare interface InteractionActed {
  * afterwards when `submit` is set.
  */
 declare const InteractionAction: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"upload">;
+    element: z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            fill: "fill";
+            upload: "upload";
+            activate: "activate";
+            click: "click";
+            select: "select";
+            scroll: "scroll";
+            wait: "wait";
+            press: "press";
+        }>;
+        label: z.ZodString;
+        node: z.ZodOptional<z.ZodNumber>;
+        role: z.ZodOptional<z.ZodString>;
+        value: z.ZodOptional<z.ZodString>;
+        current_value: z.ZodOptional<z.ZodString>;
+        checked: z.ZodOptional<z.ZodString>;
+        selected: z.ZodOptional<z.ZodString>;
+        expanded: z.ZodOptional<z.ZodString>;
+        look: z.ZodOptional<z.ZodEnum<{
+            link: "link";
+            widget: "widget";
+        }>>;
+        delta: z.ZodOptional<z.ZodNumber>;
+        position: z.ZodOptional<z.ZodEnum<{
+            above: "above";
+            below: "below";
+            beside: "beside";
+        }>>;
+        region: z.ZodOptional<z.ZodObject<{
+            role: z.ZodString;
+            name: z.ZodString;
+            front: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>;
+        scroller: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>;
+    path: z.ZodString;
+    origin: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"click">;
     element: z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
             fill: "fill";
+            upload: "upload";
             activate: "activate";
             click: "click";
             select: "select";
@@ -1436,6 +1484,7 @@ declare const InteractionAction: z.ZodDiscriminatedUnion<[z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
             fill: "fill";
+            upload: "upload";
             activate: "activate";
             click: "click";
             select: "select";
@@ -1477,6 +1526,7 @@ declare const InteractionAction: z.ZodDiscriminatedUnion<[z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
             fill: "fill";
+            upload: "upload";
             activate: "activate";
             click: "click";
             select: "select";
@@ -1515,6 +1565,7 @@ declare const InteractionAction: z.ZodDiscriminatedUnion<[z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
             fill: "fill";
+            upload: "upload";
             activate: "activate";
             click: "click";
             select: "select";
@@ -1553,6 +1604,7 @@ declare const InteractionAction: z.ZodDiscriminatedUnion<[z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
             fill: "fill";
+            upload: "upload";
             activate: "activate";
             click: "click";
             select: "select";
@@ -1592,6 +1644,7 @@ declare const InteractionAction: z.ZodDiscriminatedUnion<[z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
             fill: "fill";
+            upload: "upload";
             activate: "activate";
             click: "click";
             select: "select";
@@ -1688,6 +1741,7 @@ declare const InteractionObservation: z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
             fill: "fill";
+            upload: "upload";
             activate: "activate";
             click: "click";
             select: "select";
@@ -2746,8 +2800,14 @@ 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.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.55.4";
+declare const KAY_PLUGIN_SDK_VERSION: "0.55.5";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 

package/dist/kay-agent.d.ts

@@ -1055,6 +1055,12 @@ declare interface DerivedToolClassification {
     readonly kind?: ToolActionKind;
     readonly ruleKey?: string;
     readonly scheme?: string;
+    /**
+     * This call needs a person's one-time answer: no allow rule, no mode (allow mode included) and
+     * no automatic approver settles it, and the approval cannot be remembered. Deny rules still
+     * apply. Stricter only, so it grants nothing. The same flag a URI route classification carries.
+     */
+    readonly humanOnly?: true;
 }
 
 /**
@@ -1668,11 +1674,53 @@ export declare type InteractionAction = DriverAction<InteractionAction_2>;
  * afterwards when `submit` is set.
  */
 declare const InteractionAction_2: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"upload">;
+    element: z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            fill: "fill";
+            upload: "upload";
+            activate: "activate";
+            click: "click";
+            select: "select";
+            scroll: "scroll";
+            wait: "wait";
+            press: "press";
+        }>;
+        label: z.ZodString;
+        node: z.ZodOptional<z.ZodNumber>;
+        role: z.ZodOptional<z.ZodString>;
+        value: z.ZodOptional<z.ZodString>;
+        current_value: z.ZodOptional<z.ZodString>;
+        checked: z.ZodOptional<z.ZodString>;
+        selected: z.ZodOptional<z.ZodString>;
+        expanded: z.ZodOptional<z.ZodString>;
+        look: z.ZodOptional<z.ZodEnum<{
+            link: "link";
+            widget: "widget";
+        }>>;
+        delta: z.ZodOptional<z.ZodNumber>;
+        position: z.ZodOptional<z.ZodEnum<{
+            above: "above";
+            below: "below";
+            beside: "beside";
+        }>>;
+        region: z.ZodOptional<z.ZodObject<{
+            role: z.ZodString;
+            name: z.ZodString;
+            front: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>;
+        scroller: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>;
+    path: z.ZodString;
+    origin: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"click">;
     element: z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
             fill: "fill";
+            upload: "upload";
             activate: "activate";
             click: "click";
             select: "select";
@@ -1711,6 +1759,7 @@ declare const InteractionAction_2: z.ZodDiscriminatedUnion<[z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
             fill: "fill";
+            upload: "upload";
             activate: "activate";
             click: "click";
             select: "select";
@@ -1752,6 +1801,7 @@ declare const InteractionAction_2: z.ZodDiscriminatedUnion<[z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
             fill: "fill";
+            upload: "upload";
             activate: "activate";
             click: "click";
             select: "select";
@@ -1790,6 +1840,7 @@ declare const InteractionAction_2: z.ZodDiscriminatedUnion<[z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
             fill: "fill";
+            upload: "upload";
             activate: "activate";
             click: "click";
             select: "select";
@@ -1828,6 +1879,7 @@ declare const InteractionAction_2: z.ZodDiscriminatedUnion<[z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
             fill: "fill";
+            upload: "upload";
             activate: "activate";
             click: "click";
             select: "select";
@@ -1867,6 +1919,7 @@ declare const InteractionAction_2: z.ZodDiscriminatedUnion<[z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
             fill: "fill";
+            upload: "upload";
             activate: "activate";
             click: "click";
             select: "select";
@@ -1919,6 +1972,7 @@ declare const InteractionCandidate_2: z.ZodObject<{
     id: z.ZodString;
     kind: z.ZodEnum<{
         fill: "fill";
+        upload: "upload";
         activate: "activate";
         click: "click";
         select: "select";
@@ -1955,7 +2009,7 @@ declare const InteractionCandidate_2: z.ZodObject<{
 declare type InteractionCandidate_2 = z.infer<typeof InteractionCandidate_2>;
 
 /** The candidate kinds a driver may offer. */
-export declare type InteractionCandidateKind = "click" | "fill" | "select" | "scroll" | "wait" | "activate" | "press";
+export declare type InteractionCandidateKind = "click" | "fill" | "upload" | "select" | "scroll" | "wait" | "activate" | "press";
 
 export declare interface InteractionDriver {
     /** Unique in the session. `builtin:` is reserved for Bonsai's own drivers. */
@@ -2017,6 +2071,7 @@ declare const InteractionObservation_2: z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
             fill: "fill";
+            upload: "upload";
             activate: "activate";
             click: "click";
             select: "select";
@@ -3100,8 +3155,14 @@ 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.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.55.4";
+declare const KAY_PLUGIN_SDK_VERSION: "0.55.5";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -5470,6 +5531,10 @@ 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">;

package/dist/kay-app-session-summary.d.ts

@@ -2265,6 +2265,21 @@ declare interface KayAppSessions {
      * an allowed compaction failed.
      */
     compact?(sessionId: string): Promise<boolean>;
+    /**
+     * The newest of this plugin's own state entries named `name` in a session (SDK 0.55.5). Checked
+     * against `sessions.state`, for any session. Rejects for a name outside the grammar.
+     */
+    readState?(sessionId: string, name: string): Promise<KayAppSessionStateRead>;
+    /**
+     * Append this plugin's next state entry of `write.name` to a session's transcript, only if the
+     * newest one is still `write.baseEntryId` (SDK 0.55.5). Checked against `sessions.state`, and
+     * bound like {@link annotate}: only for a session whose event one of this plugin's
+     * `sessionEvents` handlers is handling now. On `conflict`, apply the change again to `newest`
+     * and write with its id as the base. Rejects for a name or data outside the bounds; nothing is
+     * written then. The entries are not shown to the agent; a plugin or page that can read the
+     * conversation can read them.
+     */
+    writeState?(sessionId: string, write: KayAppSessionStateWriteInput): Promise<KayAppSessionStateWrite>;
     create?(input: {
         /** Omit to inherit the opener's cwd, unless an explicit project supplies its default. */
         readonly cwd?: string;
@@ -2374,6 +2389,68 @@ declare interface KayAppSessionState {
     };
 }
 
+/** One of a plugin's own state entries in a session. */
+declare interface KayAppSessionStateEntry {
+    readonly entryId: string;
+    readonly data: JsonValue_3;
+}
+
+/** What {@link KayAppSessions.readState} answers: the newest entry of the name. */
+declare type KayAppSessionStateRead = ({
+    readonly status: "found";
+} & KayAppSessionStateEntry) | {
+    readonly status: "none";
+} | {
+    readonly status: "unavailable";
+    readonly reason: KayAppSessionStateUnavailableReason;
+};
+
+/** Why a plugin state entry could not be read or written. Not a refusal of the plugin. */
+declare type KayAppSessionStateUnavailableReason = 
+/** The session does not exist, or is deleted (in the trash or being purged). */
+"not_found"
+/** The session's log could not be read. */
+| "unreadable"
+/**
+* The newest entry of the name lies further back in the log than one bounded read scans (about
+* 1 GiB of other records). The name cannot be read or written in that session.
+*/
+| "too_far_back";
+
+/**
+ * What {@link KayAppSessions.writeState} answers. `conflict`: the newest entry is not the
+ * `baseEntryId`, so nothing was written, and `newest` is what to build on (`null` when there is
+ * none). A write that rejected or timed out may still have landed: reading again then shows it as
+ * the newest entry, and a retry from the old base answers `conflict` with the plugin's own data.
+ */
+declare type KayAppSessionStateWrite = {
+    readonly status: "written";
+    readonly entryId: string;
+} | {
+    readonly status: "conflict";
+    readonly newest: KayAppSessionStateEntry | null;
+} | {
+    readonly status: "unavailable";
+    readonly reason: KayAppSessionStateUnavailableReason;
+};
+
+/** One write for {@link KayAppSessions.writeState}. */
+declare interface KayAppSessionStateWriteInput {
+    /**
+     * The plugin's own name for the entry: lowercase letters, digits and dashes, starting with a
+     * letter, at most 64 characters (`PLUGIN_STATE_ENTRY_NAME_PATTERN`). Stored as
+     * `plugin-state:<pluginId>:<name>`.
+     */
+    readonly name: string;
+    /** The entry id of the newest entry of this name the plugin read, or `null` when it read none. */
+    readonly baseEntryId: string | null;
+    /**
+     * Plain JSON: finite numbers, at most 64 levels deep and 256 KiB serialized
+     * (`PLUGIN_STATE_ENTRY_MAX_BYTES`), no credential-shaped field names.
+     */
+    readonly data: JsonValue_3;
+}
+
 export declare interface KayAppSessionSummaryChunk {
     readonly goal: string;
     readonly work: readonly string[];

package/dist/kay-app.d.ts

@@ -2645,6 +2645,12 @@ declare interface DerivedToolClassification {
     readonly kind?: ToolActionKind;
     readonly ruleKey?: string;
     readonly scheme?: string;
+    /**
+     * This call needs a person's one-time answer: no allow rule, no mode (allow mode included) and
+     * no automatic approver settles it, and the approval cannot be remembered. Deny rules still
+     * apply. Stricter only, so it grants nothing. The same flag a URI route classification carries.
+     */
+    readonly humanOnly?: true;
 }
 
 declare interface DiagnosticErrorInfo {
@@ -4402,8 +4408,14 @@ 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.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.55.4";
+declare const KAY_PLUGIN_SDK_VERSION: "0.55.5";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -8011,6 +8023,21 @@ export declare interface KayAppSessions {
      * an allowed compaction failed.
      */
     compact?(sessionId: string): Promise<boolean>;
+    /**
+     * The newest of this plugin's own state entries named `name` in a session (SDK 0.55.5). Checked
+     * against `sessions.state`, for any session. Rejects for a name outside the grammar.
+     */
+    readState?(sessionId: string, name: string): Promise<KayAppSessionStateRead>;
+    /**
+     * Append this plugin's next state entry of `write.name` to a session's transcript, only if the
+     * newest one is still `write.baseEntryId` (SDK 0.55.5). Checked against `sessions.state`, and
+     * bound like {@link annotate}: only for a session whose event one of this plugin's
+     * `sessionEvents` handlers is handling now. On `conflict`, apply the change again to `newest`
+     * and write with its id as the base. Rejects for a name or data outside the bounds; nothing is
+     * written then. The entries are not shown to the agent; a plugin or page that can read the
+     * conversation can read them.
+     */
+    writeState?(sessionId: string, write: KayAppSessionStateWriteInput): Promise<KayAppSessionStateWrite>;
     create?(input: {
         /** Omit to inherit the opener's cwd, unless an explicit project supplies its default. */
         readonly cwd?: string;
@@ -8120,6 +8147,68 @@ export declare interface KayAppSessionState {
     };
 }
 
+/** One of a plugin's own state entries in a session. */
+export declare interface KayAppSessionStateEntry {
+    readonly entryId: string;
+    readonly data: JsonValue;
+}
+
+/** What {@link KayAppSessions.readState} answers: the newest entry of the name. */
+export declare type KayAppSessionStateRead = ({
+    readonly status: "found";
+} & KayAppSessionStateEntry) | {
+    readonly status: "none";
+} | {
+    readonly status: "unavailable";
+    readonly reason: KayAppSessionStateUnavailableReason;
+};
+
+/** Why a plugin state entry could not be read or written. Not a refusal of the plugin. */
+export declare type KayAppSessionStateUnavailableReason = 
+/** The session does not exist, or is deleted (in the trash or being purged). */
+"not_found"
+/** The session's log could not be read. */
+| "unreadable"
+/**
+* The newest entry of the name lies further back in the log than one bounded read scans (about
+* 1 GiB of other records). The name cannot be read or written in that session.
+*/
+| "too_far_back";
+
+/**
+ * What {@link KayAppSessions.writeState} answers. `conflict`: the newest entry is not the
+ * `baseEntryId`, so nothing was written, and `newest` is what to build on (`null` when there is
+ * none). A write that rejected or timed out may still have landed: reading again then shows it as
+ * the newest entry, and a retry from the old base answers `conflict` with the plugin's own data.
+ */
+export declare type KayAppSessionStateWrite = {
+    readonly status: "written";
+    readonly entryId: string;
+} | {
+    readonly status: "conflict";
+    readonly newest: KayAppSessionStateEntry | null;
+} | {
+    readonly status: "unavailable";
+    readonly reason: KayAppSessionStateUnavailableReason;
+};
+
+/** One write for {@link KayAppSessions.writeState}. */
+export declare interface KayAppSessionStateWriteInput {
+    /**
+     * The plugin's own name for the entry: lowercase letters, digits and dashes, starting with a
+     * letter, at most 64 characters (`PLUGIN_STATE_ENTRY_NAME_PATTERN`). Stored as
+     * `plugin-state:<pluginId>:<name>`.
+     */
+    readonly name: string;
+    /** The entry id of the newest entry of this name the plugin read, or `null` when it read none. */
+    readonly baseEntryId: string | null;
+    /**
+     * Plain JSON: finite numbers, at most 64 levels deep and 256 KiB serialized
+     * (`PLUGIN_STATE_ENTRY_MAX_BYTES`), no credential-shaped field names.
+     */
+    readonly data: JsonValue;
+}
+
 /**
  * The durable summary of one session, as a run-detail activity item embeds it
  * (mirror of `AgentRuntimeSessionSummary` in its transformed shape).

package/package.json

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