@yaklabs-ai/plugin-protocol 0.10.0 → 0.12.2

package/README.md

@@ -11,7 +11,7 @@ flow.
 ```json
 {
   "dependencies": {
-    "@kay/plugin-protocol": "npm:@yaklabs-ai/plugin-protocol@^0.10.0"
+    "@kay/plugin-protocol": "npm:@yaklabs-ai/plugin-protocol@^0.12.2"
   }
 }
 ```

package/THIRD-PARTY-INVENTORY.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@yaklabs-ai/plugin-protocol",
-  "version": "0.10.0",
+  "version": "0.12.2",
   "target": "npm",
   "firstPartyLicense": "MIT",
   "bundled": [],
@@ -12,12 +12,6 @@
       "source": "https://github.com/colinhacks/zod",
       "note": "Installed as a consumer dependency; it is not bundled into the staged artifacts.",
       "versionRange": "^4.0.0"
-    },
-    {
-      "name": "@typesafe-ai/sdk",
-      "license": "MIT",
-      "source": "https://github.com/typesafe-ai/typesafe-sdk-js",
-      "note": "Types-only: the SDK re-exports the vendor's Jev client types, and the vendor's nominal class must stay a single declaration across entrypoints. Installed as a consumer dependency; a plugin never declares it itself."
     }
   ]
 }

package/dist/index.d.ts

@@ -263,6 +263,7 @@ export declare const ArtifactProvenanceCaptureContextSchema: z.ZodObject<{
                         "turn-settled": "turn-settled";
                         "phase-shift": "phase-shift";
                         "human-message": "human-message";
+                        "ui-action": "ui-action";
                     }>;
                     entryId: z.ZodString;
                     runId: z.ZodOptional<z.ZodString>;
@@ -355,6 +356,7 @@ export declare const ArtifactProvenanceCaptureContextSchema: z.ZodObject<{
                         "turn-settled": "turn-settled";
                         "phase-shift": "phase-shift";
                         "human-message": "human-message";
+                        "ui-action": "ui-action";
                     }>;
                     entryId: z.ZodString;
                     runId: z.ZodOptional<z.ZodString>;
@@ -451,6 +453,7 @@ export declare const ArtifactProvenanceCause: z.ZodDiscriminatedUnion<[z.ZodObje
                 "turn-settled": "turn-settled";
                 "phase-shift": "phase-shift";
                 "human-message": "human-message";
+                "ui-action": "ui-action";
             }>;
             entryId: z.ZodString;
             runId: z.ZodOptional<z.ZodString>;
@@ -528,6 +531,7 @@ export declare const ArtifactProvenanceEnvelopeV1: z.ZodPipe<z.ZodUnknown, z.Zod
                         "turn-settled": "turn-settled";
                         "phase-shift": "phase-shift";
                         "human-message": "human-message";
+                        "ui-action": "ui-action";
                     }>;
                     entryId: z.ZodString;
                     runId: z.ZodOptional<z.ZodString>;
@@ -619,6 +623,7 @@ export declare const ArtifactProvenanceEnvelopeV1: z.ZodPipe<z.ZodUnknown, z.Zod
                             "turn-settled": "turn-settled";
                             "phase-shift": "phase-shift";
                             "human-message": "human-message";
+                            "ui-action": "ui-action";
                         }>;
                         entryId: z.ZodString;
                         runId: z.ZodOptional<z.ZodString>;
@@ -735,6 +740,7 @@ export declare const ArtifactProvenanceEnvelopeV1: z.ZodPipe<z.ZodUnknown, z.Zod
                         "turn-settled": "turn-settled";
                         "phase-shift": "phase-shift";
                         "human-message": "human-message";
+                        "ui-action": "ui-action";
                     }>;
                     entryId: z.ZodString;
                     runId: z.ZodOptional<z.ZodString>;
@@ -906,6 +912,7 @@ export declare const ArtifactProvenanceMutation: z.ZodObject<{
                         "turn-settled": "turn-settled";
                         "phase-shift": "phase-shift";
                         "human-message": "human-message";
+                        "ui-action": "ui-action";
                     }>;
                     entryId: z.ZodString;
                     runId: z.ZodOptional<z.ZodString>;
@@ -1001,6 +1008,7 @@ export declare const ArtifactProvenanceOperation: z.ZodObject<{
                     "turn-settled": "turn-settled";
                     "phase-shift": "phase-shift";
                     "human-message": "human-message";
+                    "ui-action": "ui-action";
                 }>;
                 entryId: z.ZodString;
                 runId: z.ZodOptional<z.ZodString>;
@@ -1141,6 +1149,7 @@ export declare const ArtifactProvenanceSession: z.ZodObject<{
                     "turn-settled": "turn-settled";
                     "phase-shift": "phase-shift";
                     "human-message": "human-message";
+                    "ui-action": "ui-action";
                 }>;
                 entryId: z.ZodString;
                 runId: z.ZodOptional<z.ZodString>;
@@ -1869,6 +1878,23 @@ export declare const HttpsUrl: z.ZodURL;
 
 export declare type HttpsUrl = z.infer<typeof HttpsUrl>;
 
+/**
+ * An Interaction driver (a backend behind the harness-owned `interaction_*` tools) the plugin's
+ * `kay.agent` entrypoint registers with `api.registerInteractionDriver`. The driver's `id` must be
+ * this `localId`; `kind` says whether it drives web pages ("browser", Browser Interaction) or
+ * native apps ("computer-use", Computer Use Interaction).
+ */
+export declare const InteractionDriverContribution: z.ZodObject<{
+    localId: z.ZodString;
+    displayName: z.ZodOptional<z.ZodString>;
+    kind: z.ZodEnum<{
+        browser: "browser";
+        "computer-use": "computer-use";
+    }>;
+}, z.core.$strict>;
+
+export declare type InteractionDriverContribution = z.infer<typeof InteractionDriverContribution>;
+
 /** Whether the report permits the plugin to load. */
 export declare function isCompatible(report: KayPluginCompatibilityReport): boolean;
 
@@ -1935,7 +1961,7 @@ export declare const KAY_APP_DATA_SNAPSHOT_MAX_BYTES: number;
 export declare const KAY_EVENT_PUBLISHER_ID: "kay";
 
 /** Released SDK contracts still implemented by the host, alongside its current SDK. */
-export declare const KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS: readonly ["0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.9.0", "0.9.1"];
+export declare const KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS: readonly ["0.8.0", "0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5", "0.9.0", "0.9.1", "0.10.0", "0.11.0", "0.11.1", "0.12.0", "0.12.1"];
 
 export declare const KAY_PLUGIN_PROTOCOL_PACKAGE_NAME: "@kay/plugin-protocol";
 
@@ -2061,8 +2087,63 @@ export declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * `app.automations.create` with a `spawn-session` effect now throws
  * explicitly at the call site instead of being accepted, for any plugin
  * regardless of its declared SDK range.
+ *
+ * 0.11.0 adds `producedResources` to `KayAppAutomationRunDetail` (every URI a
+ * run wrote, edited or declared, as one list deduplicated by URI) and the
+ * `produced-resource-unnamed` member to `KayAppProvenanceGapCode`. An
+ * authoring-type break only: code that builds a run detail must supply the
+ * new list, and an exhaustive switch over gap codes must handle the new one.
+ * 0.10.0 stays in the runtime-contract retention list below, because a plugin
+ * compiled against it reads the same run detail and simply ignores the list.
+ *
+ * 0.11.1 adds read-only skill metadata (`app.skills`: `list`, `read`, `history`),
+ * checked per call against the new `skills.read` claim. Additive: a plugin
+ * compiled against 0.11.0 never reads the member. A plugin that calls it
+ * declares `^0.11.1`, so an older host refuses it at load instead of the call
+ * failing.
+ *
+ * 0.12.0 replaces the vendor client `api.withJev` hands its callback. `use`
+ * now receives Kay's own `JevClient` (`@kay/plugin-sdk/jev`): one method,
+ * `classify({state, questions})`, in Kay's question and answer vocabulary
+ * (yes/no is `bool` answering `probability`; instructions and criteria are
+ * text; the state is a JSON object), rejecting with a classified
+ * `JevCallError`. TypeSafe's `TypeSafeClient`, `SystemOneRequest`,
+ * `SystemOneResult`, `Questions`, and the `NoulResponse`/`ChoiceResponse`/
+ * `ScoreResponse` re-exports are gone, and the SDK no longer depends on
+ * `@typesafe-ai/sdk`. `app.signals.observe` takes the same questions, answers
+ * `invalid` for a state that is not a JSON object, and its reads type stored
+ * answers as `KayAppSignalAnswer` (a `JevAnswer`, or a yes/no answer recorded
+ * before 0.12.0 as `{type: "noul", noul}`).
+ *
+ * A clean break with no shim, and deliberately NOT a load refusal: every
+ * earlier release stays in the retention list below. `withJev`'s contract was
+ * always that `use` may fail and the fallback then runs, so a plugin compiled
+ * against 0.11 that calls `jev.systemOne` throws inside `use` and runs its
+ * fallback on this host. This fallback guarantee does not cover `signals.observe`:
+ * old text/array states now return `invalid`; old object states with `noul`
+ * questions can classify but receive `bool` answers, so reading `.noul` yields
+ * undefined. Stored pre-0.12 answers retain `noul`. Retention allows activation,
+ * not vocabulary compatibility: old plugins must migrate both surfaces.
+ *
+ * 0.12.1 adds `app.time` (`KayAppTime`): `snapshot()` returns the daemon's clock and the time
+ * zone the user is in, as `{ nowMs, zone, zoneSource }`, where `zoneSource: "utc-fallback"` marks a
+ * zone the host does not know. The member is always present and ungated, like `app.paths`.
+ * Additive: a plugin compiled against 0.12.0 never reads it. A plugin that calls it declares
+ * `^0.12.1`, so an older host refuses a directory or repository plugin at load instead of the
+ * call failing. That check needs a host that knows its own version, and it never runs for a
+ * bundled plugin, which ships with the SDK it calls.
+ *
+ * 0.12.2 adds the `ui-action` session event (`KayAppUiActionSessionEvent`), a fourth member of the
+ * `KayAppSessionEvent` union: the daemon publishes it once per accepted answer to a card the agent
+ * drew with `ui_render` (pressing Send on a drafted message, submitting a form), carrying the
+ * projected entry's id and the answered call's id and no payload. A typed message still publishes
+ * only `human-message`. Additive: a plugin compiled against 0.12.1 never subscribes to it, and
+ * code that narrows the union by `type` meets one more member, as it must for any future one. A
+ * plugin that subscribes to it declares `^0.12.2`, so an older host refuses a directory or
+ * repository plugin at load instead of the subscription never firing. That check never runs for a
+ * bundled plugin, which ships with the SDK it calls.
  */
-export declare const KAY_PLUGIN_SDK_VERSION: "0.10.0";
+export declare const KAY_PLUGIN_SDK_VERSION: "0.12.2";
 
 export declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -2155,6 +2236,14 @@ export declare const KayAgentTargetManifest: z.ZodObject<{
             displayName: z.ZodOptional<z.ZodString>;
             schemes: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>>>;
+        interactionDrivers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            localId: z.ZodString;
+            displayName: z.ZodOptional<z.ZodString>;
+            kind: z.ZodEnum<{
+                browser: "browser";
+                "computer-use": "computer-use";
+            }>;
+        }, z.core.$strict>>>;
         entityResolvers: z.ZodOptional<z.ZodArray<z.ZodObject<{
             localId: z.ZodString;
             displayName: z.ZodOptional<z.ZodString>;
@@ -2495,6 +2584,14 @@ export declare const KayPluginManifestV1: z.ZodObject<{
                         displayName: z.ZodOptional<z.ZodString>;
                         schemes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     }, z.core.$strict>>>;
+                    interactionDrivers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        localId: z.ZodString;
+                        displayName: z.ZodOptional<z.ZodString>;
+                        kind: z.ZodEnum<{
+                            browser: "browser";
+                            "computer-use": "computer-use";
+                        }>;
+                    }, z.core.$strict>>>;
                     entityResolvers: z.ZodOptional<z.ZodArray<z.ZodObject<{
                         localId: z.ZodString;
                         displayName: z.ZodOptional<z.ZodString>;
@@ -2759,12 +2856,12 @@ export declare const KayPluginManifestV1: z.ZodObject<{
                         capabilities: z.ZodOptional<z.ZodObject<{
                             endpoints: z.ZodOptional<z.ZodArray<z.ZodString>>;
                             host: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                                "skills.read": "skills.read";
                                 "automations.run": "automations.run";
                                 "navigation.open-session": "navigation.open-session";
                                 "cost.read": "cost.read";
                                 "billing.read": "billing.read";
                                 "context.read": "context.read";
-                                "skills.read": "skills.read";
                                 "memory.read": "memory.read";
                                 "usage.read": "usage.read";
                                 "self-improvement.read": "self-improvement.read";
@@ -3195,12 +3292,12 @@ export declare const KayPluginProtocolVersion: z.ZodLiteral<"kay.plugin.v1">;
 export declare type KayPluginProtocolVersion = z.infer<typeof KayPluginProtocolVersion>;
 
 export declare const KayUiAppHostCapability: z.ZodEnum<{
+    "skills.read": "skills.read";
     "automations.run": "automations.run";
     "navigation.open-session": "navigation.open-session";
     "cost.read": "cost.read";
     "billing.read": "billing.read";
     "context.read": "context.read";
-    "skills.read": "skills.read";
     "memory.read": "memory.read";
     "usage.read": "usage.read";
     "self-improvement.read": "self-improvement.read";
@@ -3341,12 +3438,12 @@ export declare const KayUiTargetManifest: z.ZodObject<{
             capabilities: z.ZodOptional<z.ZodObject<{
                 endpoints: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 host: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                    "skills.read": "skills.read";
                     "automations.run": "automations.run";
                     "navigation.open-session": "navigation.open-session";
                     "cost.read": "cost.read";
                     "billing.read": "billing.read";
                     "context.read": "context.read";
-                    "skills.read": "skills.read";
                     "memory.read": "memory.read";
                     "usage.read": "usage.read";
                     "self-improvement.read": "self-improvement.read";
@@ -3582,7 +3679,7 @@ export declare function parseResolvedPluginContractV1(value: unknown): ResolvedP
 export declare function parseSemver(value: string): ParsedSemver | undefined;
 
 /** 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", "filesystem.read", "filesystem.write", "process.spawn", "corpus.read", "signals.read", "workspace.command", "sessions.create", "sessions.update", "models.complete", "jev.use", "automations.write", "automations.run", "workflows.define", "session-events.subscribe", "agents.run", "dynamic-context.register", "app-data.register", "account.assert", "account.update", "agents.permissions", "tool-interception.register", "config.declare-section", "auth.own-service", "auth.shared-identity", "cli.bind", "whiteboard.discover", "whiteboard.read", "whiteboard.create", "whiteboard.update", "whiteboard.remove"];
+export declare const PLUGIN_CAPABILITY_SLUGS: readonly ["sessions.run", "network.connect", "web-session.request", "web-session.download", "filesystem.read", "filesystem.write", "process.spawn", "corpus.read", "signals.read", "skills.read", "workspace.command", "sessions.create", "sessions.update", "models.complete", "jev.use", "automations.write", "automations.run", "workflows.define", "session-events.subscribe", "agents.run", "dynamic-context.register", "app-data.register", "account.assert", "account.update", "agents.permissions", "tool-interception.register", "interaction.surface", "config.declare-section", "auth.own-service", "auth.shared-identity", "cli.bind", "whiteboard.discover", "whiteboard.read", "whiteboard.create", "whiteboard.update", "whiteboard.remove"];
 
 /** The root `<svg>` attribute a tile icon declares itself with. */
 export declare const PLUGIN_ICON_SHAPE_ATTRIBUTE = "data-icon-shape";
@@ -3617,6 +3714,7 @@ export declare const PluginAgentDefinitionPermissionRule: z.ZodObject<{
         default: "default";
         allow: "allow";
         ask: "ask";
+        auto: "auto";
     }>>;
 }, z.core.$strict>;
 
@@ -4017,6 +4115,10 @@ export declare const PluginCapabilityClaimV1: z.ZodDiscriminatedUnion<[z.ZodObje
     target: z.ZodLiteral<"kay.app">;
     slug: z.ZodLiteral<"signals.read">;
     envelope: z.ZodObject<{}, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    target: z.ZodLiteral<"kay.app">;
+    slug: z.ZodLiteral<"skills.read">;
+    envelope: z.ZodObject<{}, z.core.$strict>;
 }, z.core.$strict>, z.ZodObject<{
     target: z.ZodLiteral<"kay.app">;
     slug: z.ZodLiteral<"workspace.command">;
@@ -4096,6 +4198,7 @@ export declare const PluginCapabilityClaimV1: z.ZodDiscriminatedUnion<[z.ZodObje
                 default: "default";
                 allow: "allow";
                 ask: "ask";
+                auto: "auto";
             }>>;
         }, z.core.$strict>>;
         fallback: z.ZodArray<z.ZodObject<{
@@ -4112,6 +4215,7 @@ export declare const PluginCapabilityClaimV1: z.ZodDiscriminatedUnion<[z.ZodObje
                 default: "default";
                 allow: "allow";
                 ask: "ask";
+                auto: "auto";
             }>>;
         }, z.core.$strict>>;
     }, z.core.$strict>;
@@ -4119,6 +4223,15 @@ export declare const PluginCapabilityClaimV1: z.ZodDiscriminatedUnion<[z.ZodObje
     target: z.ZodLiteral<"kay.agent">;
     slug: z.ZodLiteral<"tool-interception.register">;
     envelope: z.ZodObject<{}, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    target: z.ZodLiteral<"kay.agent">;
+    slug: z.ZodLiteral<"interaction.surface">;
+    envelope: z.ZodObject<{
+        surface: z.ZodEnum<{
+            "browser-pane": "browser-pane";
+            desktop: "desktop";
+        }>;
+    }, z.core.$strict>;
 }, z.core.$strict>, z.ZodObject<{
     target: z.ZodLiteral<"plugin">;
     slug: z.ZodLiteral<"config.declare-section">;
@@ -4222,6 +4335,10 @@ export declare const PluginCapabilityDecisionV1: z.ZodDiscriminatedUnion<[z.ZodO
         target: z.ZodLiteral<"kay.app">;
         slug: z.ZodLiteral<"signals.read">;
         envelope: z.ZodObject<{}, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"kay.app">;
+        slug: z.ZodLiteral<"skills.read">;
+        envelope: z.ZodObject<{}, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         target: z.ZodLiteral<"kay.app">;
         slug: z.ZodLiteral<"workspace.command">;
@@ -4301,6 +4418,7 @@ export declare const PluginCapabilityDecisionV1: z.ZodDiscriminatedUnion<[z.ZodO
                     default: "default";
                     allow: "allow";
                     ask: "ask";
+                    auto: "auto";
                 }>>;
             }, z.core.$strict>>;
             fallback: z.ZodArray<z.ZodObject<{
@@ -4317,6 +4435,7 @@ export declare const PluginCapabilityDecisionV1: z.ZodDiscriminatedUnion<[z.ZodO
                     default: "default";
                     allow: "allow";
                     ask: "ask";
+                    auto: "auto";
                 }>>;
             }, z.core.$strict>>;
         }, z.core.$strict>;
@@ -4324,6 +4443,15 @@ export declare const PluginCapabilityDecisionV1: z.ZodDiscriminatedUnion<[z.ZodO
         target: z.ZodLiteral<"kay.agent">;
         slug: z.ZodLiteral<"tool-interception.register">;
         envelope: z.ZodObject<{}, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"kay.agent">;
+        slug: z.ZodLiteral<"interaction.surface">;
+        envelope: z.ZodObject<{
+            surface: z.ZodEnum<{
+                "browser-pane": "browser-pane";
+                desktop: "desktop";
+            }>;
+        }, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         target: z.ZodLiteral<"plugin">;
         slug: z.ZodLiteral<"config.declare-section">;
@@ -4422,6 +4550,10 @@ export declare const PluginCapabilityDecisionV1: z.ZodDiscriminatedUnion<[z.ZodO
             target: z.ZodLiteral<"kay.app">;
             slug: z.ZodLiteral<"signals.read">;
             envelope: z.ZodObject<{}, z.core.$strict>;
+        }, z.core.$strict>, z.ZodObject<{
+            target: z.ZodLiteral<"kay.app">;
+            slug: z.ZodLiteral<"skills.read">;
+            envelope: z.ZodObject<{}, z.core.$strict>;
         }, z.core.$strict>, z.ZodObject<{
             target: z.ZodLiteral<"kay.app">;
             slug: z.ZodLiteral<"workspace.command">;
@@ -4501,6 +4633,7 @@ export declare const PluginCapabilityDecisionV1: z.ZodDiscriminatedUnion<[z.ZodO
                         default: "default";
                         allow: "allow";
                         ask: "ask";
+                        auto: "auto";
                     }>>;
                 }, z.core.$strict>>;
                 fallback: z.ZodArray<z.ZodObject<{
@@ -4517,6 +4650,7 @@ export declare const PluginCapabilityDecisionV1: z.ZodDiscriminatedUnion<[z.ZodO
                         default: "default";
                         allow: "allow";
                         ask: "ask";
+                        auto: "auto";
                     }>>;
                 }, z.core.$strict>>;
             }, z.core.$strict>;
@@ -4524,6 +4658,15 @@ export declare const PluginCapabilityDecisionV1: z.ZodDiscriminatedUnion<[z.ZodO
             target: z.ZodLiteral<"kay.agent">;
             slug: z.ZodLiteral<"tool-interception.register">;
             envelope: z.ZodObject<{}, z.core.$strict>;
+        }, z.core.$strict>, z.ZodObject<{
+            target: z.ZodLiteral<"kay.agent">;
+            slug: z.ZodLiteral<"interaction.surface">;
+            envelope: z.ZodObject<{
+                surface: z.ZodEnum<{
+                    "browser-pane": "browser-pane";
+                    desktop: "desktop";
+                }>;
+            }, z.core.$strict>;
         }, z.core.$strict>, z.ZodObject<{
             target: z.ZodLiteral<"plugin">;
             slug: z.ZodLiteral<"config.declare-section">;
@@ -4685,6 +4828,10 @@ export declare const PluginCapabilityRefusalV1: z.ZodObject<{
         target: z.ZodLiteral<"kay.app">;
         slug: z.ZodLiteral<"signals.read">;
         envelope: z.ZodObject<{}, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"kay.app">;
+        slug: z.ZodLiteral<"skills.read">;
+        envelope: z.ZodObject<{}, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         target: z.ZodLiteral<"kay.app">;
         slug: z.ZodLiteral<"workspace.command">;
@@ -4764,6 +4911,7 @@ export declare const PluginCapabilityRefusalV1: z.ZodObject<{
                     default: "default";
                     allow: "allow";
                     ask: "ask";
+                    auto: "auto";
                 }>>;
             }, z.core.$strict>>;
             fallback: z.ZodArray<z.ZodObject<{
@@ -4780,6 +4928,7 @@ export declare const PluginCapabilityRefusalV1: z.ZodObject<{
                     default: "default";
                     allow: "allow";
                     ask: "ask";
+                    auto: "auto";
                 }>>;
             }, z.core.$strict>>;
         }, z.core.$strict>;
@@ -4787,6 +4936,15 @@ export declare const PluginCapabilityRefusalV1: z.ZodObject<{
         target: z.ZodLiteral<"kay.agent">;
         slug: z.ZodLiteral<"tool-interception.register">;
         envelope: z.ZodObject<{}, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"kay.agent">;
+        slug: z.ZodLiteral<"interaction.surface">;
+        envelope: z.ZodObject<{
+            surface: z.ZodEnum<{
+                "browser-pane": "browser-pane";
+                desktop: "desktop";
+            }>;
+        }, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         target: z.ZodLiteral<"plugin">;
         slug: z.ZodLiteral<"config.declare-section">;
@@ -4905,6 +5063,7 @@ export declare const PluginContributionKind: z.ZodEnum<{
     artifactUriModule: "artifactUriModule";
     cliBinding: "cliBinding";
     searchProvider: "searchProvider";
+    interactionDriver: "interactionDriver";
     entityResolver: "entityResolver";
     agentRenderer: "agentRenderer";
     eventDefinition: "eventDefinition";
@@ -5882,12 +6041,12 @@ export declare const ResolvedKayUiApp: z.ZodObject<{
             globalId: z.ZodString;
         }, z.core.$strict>>>;
         host: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            "skills.read": "skills.read";
             "automations.run": "automations.run";
             "navigation.open-session": "navigation.open-session";
             "cost.read": "cost.read";
             "billing.read": "billing.read";
             "context.read": "context.read";
-            "skills.read": "skills.read";
             "memory.read": "memory.read";
             "usage.read": "usage.read";
             "self-improvement.read": "self-improvement.read";
@@ -6168,6 +6327,7 @@ export declare const ResolvedPluginContractV1: z.ZodObject<{
             artifactUriModule: "artifactUriModule";
             cliBinding: "cliBinding";
             searchProvider: "searchProvider";
+            interactionDriver: "interactionDriver";
             entityResolver: "entityResolver";
             agentRenderer: "agentRenderer";
             eventDefinition: "eventDefinition";
@@ -6731,12 +6891,12 @@ export declare const ResolvedPluginContractV1: z.ZodObject<{
                 globalId: z.ZodString;
             }, z.core.$strict>>>;
             host: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                "skills.read": "skills.read";
                 "automations.run": "automations.run";
                 "navigation.open-session": "navigation.open-session";
                 "cost.read": "cost.read";
                 "billing.read": "billing.read";
                 "context.read": "context.read";
-                "skills.read": "skills.read";
                 "memory.read": "memory.read";
                 "usage.read": "usage.read";
                 "self-improvement.read": "self-improvement.read";
@@ -6772,6 +6932,7 @@ export declare const ResolvedPluginContributionId: z.ZodObject<{
         artifactUriModule: "artifactUriModule";
         cliBinding: "cliBinding";
         searchProvider: "searchProvider";
+        interactionDriver: "interactionDriver";
         entityResolver: "entityResolver";
         agentRenderer: "agentRenderer";
         eventDefinition: "eventDefinition";
@@ -7507,6 +7668,7 @@ export declare const SessionCausedByEvent: z.ZodObject<{
             "turn-settled": "turn-settled";
             "phase-shift": "phase-shift";
             "human-message": "human-message";
+            "ui-action": "ui-action";
         }>;
         entryId: z.ZodString;
         runId: z.ZodOptional<z.ZodString>;
@@ -7730,6 +7892,7 @@ export declare const SessionProvenanceRecord: z.ZodObject<{
                 "turn-settled": "turn-settled";
                 "phase-shift": "phase-shift";
                 "human-message": "human-message";
+                "ui-action": "ui-action";
             }>;
             entryId: z.ZodString;
             runId: z.ZodOptional<z.ZodString>;
@@ -8072,6 +8235,13 @@ export declare type TurnMessageOrigin =
 /** Neither the session nor the message establishes human authorship. */
 | "unknown";
 
+/**
+ * Who wrote one message, read from what the transcript carries: `clientIntentId` AND
+ * `details.deliveryId` mean a person typed it. The one definition the turn packet and every other
+ * reader of a message's authorship share.
+ */
+export declare function turnMessageOrigin(entry: Pick<TurnPacketEntry, "message">): TurnMessageOrigin;
+
 export declare interface TurnPacket {
     /** The message that opened the turn. */
     readonly personMessage: TurnPacketMessage;
@@ -8132,12 +8302,12 @@ export declare interface TurnPacketMessage {
 export declare const UiAppCapabilities: z.ZodObject<{
     endpoints: z.ZodOptional<z.ZodArray<z.ZodString>>;
     host: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        "skills.read": "skills.read";
         "automations.run": "automations.run";
         "navigation.open-session": "navigation.open-session";
         "cost.read": "cost.read";
         "billing.read": "billing.read";
         "context.read": "context.read";
-        "skills.read": "skills.read";
         "memory.read": "memory.read";
         "usage.read": "usage.read";
         "self-improvement.read": "self-improvement.read";
@@ -8168,12 +8338,12 @@ export declare const UiAppContribution: z.ZodObject<{
     capabilities: z.ZodOptional<z.ZodObject<{
         endpoints: z.ZodOptional<z.ZodArray<z.ZodString>>;
         host: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            "skills.read": "skills.read";
             "automations.run": "automations.run";
             "navigation.open-session": "navigation.open-session";
             "cost.read": "cost.read";
             "billing.read": "billing.read";
             "context.read": "context.read";
-            "skills.read": "skills.read";
             "memory.read": "memory.read";
             "usage.read": "usage.read";
             "self-improvement.read": "self-improvement.read";

package/dist/index.js

@@ -30,7 +30,7 @@ function textOf(entry) {
     return "";
   return content.map((part) => typeof part === "object" && part !== null && part.type === "text" && typeof part.text === "string" ? part.text : "").join("");
 }
-function originOf(entry) {
+function turnMessageOrigin(entry) {
   const m = entry.message;
   if (m === void 0 || typeof m.clientIntentId !== "string")
     return "unknown";
@@ -71,7 +71,7 @@ function turnPacket(entries, settleEntryId, options = {}) {
     entryId: entry.id,
     timestamp: entry.timestamp,
     text: textOf(entry),
-    origin: originOf(entry)
+    origin: turnMessageOrigin(entry)
   });
   return {
     personMessage: toPacket(opener),
@@ -96,7 +96,7 @@ function precedingPersonMessages(entries, packet, count) {
       continue;
     if (e.type !== "message" || e.message?.role !== "user")
       continue;
-    if (originOf(e) !== "human-verified")
+    if (turnMessageOrigin(e) !== "human-verified")
       continue;
     found.push({
       entryId: e.id,
@@ -115,7 +115,7 @@ import { z as z2 } from "zod";
 import { z } from "zod";
 var KAY_PLUGIN_PROTOCOL_VERSION = "kay.plugin.v1";
 var KAY_PLUGIN_PROTOCOL_PACKAGE_NAME = "@kay/plugin-protocol";
-var KAY_PLUGIN_SDK_VERSION = "0.10.0";
+var KAY_PLUGIN_SDK_VERSION = "0.12.2";
 var KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS = [
   "0.8.0",
   "0.8.1",
@@ -124,7 +124,12 @@ var KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS = [
   "0.8.4",
   "0.8.5",
   "0.9.0",
-  "0.9.1"
+  "0.9.1",
+  "0.10.0",
+  "0.11.0",
+  "0.11.1",
+  "0.12.0",
+  "0.12.1"
 ];
 var KAY_PLUGIN_TARGET_NAMES = [
   "kay.agent",
@@ -343,7 +348,12 @@ var SessionCausedByEventShape = z3.strictObject({
   /** Required when `kind` is `"session-event"` or absent; must be omitted when `kind` is `"backfill"`. */
   event: z3.strictObject({
     /** {@link KayAppSessionEventType} in `@kay/plugin-sdk`, mirrored: a closed, extensible union. */
-    type: z3.enum(["turn-settled", "phase-shift", "human-message"]),
+    type: z3.enum([
+      "turn-settled",
+      "phase-shift",
+      "human-message",
+      "ui-action"
+    ]),
     entryId: NonEmptyString2,
     /** The source run captured at the event boundary; absence remains unresolved. */
     runId: NonEmptyString2.optional(),
@@ -1292,7 +1302,7 @@ var PluginAgentDefinitionPermissionRule = z5.strictObject({
   /** Restrict to matching resources (a path glob, or a URI-shaped policy address). */
   resource: NonEmptyString.optional(),
   /** Restrict the rule to one permission mode; omit to apply in all modes. */
-  mode: z5.enum(["default", "ask", "allow"]).optional()
+  mode: z5.enum(["default", "ask", "allow", "auto"]).optional()
 });
 var RETIRED_PERMISSION_ASK_KEYS = [
   "network",
@@ -1515,6 +1525,14 @@ var PluginCapabilityClaimV1 = z6.discriminatedUnion("slug", [
     slug: z6.literal("signals.read"),
     envelope: z6.strictObject({})
   }),
+  z6.strictObject({
+    // Read-only metadata about every managed skill: identity, versions, history, suggestions.
+    // Never a skill's bytes (an agent reads those through `skill://`) and never a write. An
+    // empty envelope because the grant itself is the visibility decision, as with `signals.read`.
+    target: z6.literal("kay.app"),
+    slug: z6.literal("skills.read"),
+    envelope: z6.strictObject({})
+  }),
   z6.strictObject({
     target: z6.literal("kay.app"),
     slug: z6.literal("workspace.command"),
@@ -1613,6 +1631,12 @@ var PluginCapabilityClaimV1 = z6.discriminatedUnion("slug", [
     slug: z6.literal("tool-interception.register"),
     envelope: z6.strictObject({})
   }),
+  z6.strictObject({
+    target: z6.literal("kay.agent"),
+    slug: z6.literal("interaction.surface"),
+    /** The one Kay-shipped interaction surface this plugin may drive; one claim per surface. */
+    envelope: z6.strictObject({ surface: z6.enum(["browser-pane", "desktop"]) })
+  }),
   z6.strictObject({
     target: z6.literal("plugin"),
     slug: z6.literal("config.declare-section"),
@@ -1649,6 +1673,7 @@ var PLUGIN_CAPABILITY_SLUGS = [
   "process.spawn",
   "corpus.read",
   "signals.read",
+  "skills.read",
   "workspace.command",
   "sessions.create",
   "sessions.update",
@@ -1665,6 +1690,7 @@ var PLUGIN_CAPABILITY_SLUGS = [
   "account.update",
   "agents.permissions",
   "tool-interception.register",
+  "interaction.surface",
   "config.declare-section",
   "auth.own-service",
   "auth.shared-identity",
@@ -1753,6 +1779,7 @@ function sameClaim(a, b) {
     case "sessions.update":
     case "corpus.read":
     case "signals.read":
+    case "skills.read":
     case "workspace.command":
     case "models.complete":
     case "jev.use":
@@ -1775,6 +1802,8 @@ function sameClaim(a, b) {
       return (b.slug === "filesystem.read" || b.slug === "filesystem.write") && a.envelope.root === b.envelope.root;
     case "process.spawn":
       return b.slug === "process.spawn" && a.envelope.command === b.envelope.command && a.envelope.argvClass === b.envelope.argvClass;
+    case "interaction.surface":
+      return b.slug === "interaction.surface" && a.envelope.surface === b.envelope.surface;
     case "dynamic-context.register":
       return b.slug === "dynamic-context.register" && a.envelope.contributor === b.envelope.contributor;
     case "app-data.register":
@@ -1817,6 +1846,7 @@ function envelopePairs(a, b) {
     case "sessions.update":
     case "corpus.read":
     case "signals.read":
+    case "skills.read":
     case "workspace.command":
     case "models.complete":
     case "jev.use":
@@ -1845,6 +1875,8 @@ function envelopePairs(a, b) {
         [a.envelope.command, b.envelope.command],
         [a.envelope.argvClass, b.envelope.argvClass]
       ] : [];
+    case "interaction.surface":
+      return b.slug === "interaction.surface" ? [[a.envelope.surface, b.envelope.surface]] : [];
     case "dynamic-context.register":
       return b.slug === "dynamic-context.register" ? [[a.envelope.contributor, b.envelope.contributor]] : [];
     case "app-data.register":
@@ -2386,6 +2418,11 @@ var SearchProviderContribution = z7.strictObject({
   displayName: OptionalDisplayName,
   schemes: z7.array(UriScheme).optional()
 });
+var InteractionDriverContribution = z7.strictObject({
+  localId: LocalContributionId,
+  displayName: OptionalDisplayName,
+  kind: z7.enum(["browser", "computer-use"])
+});
 var EntityResolverContribution = z7.strictObject({
   localId: LocalContributionId,
   displayName: OptionalDisplayName,
@@ -2642,6 +2679,7 @@ var PluginContributionKind = z7.enum([
   "resource",
   "skill",
   "searchProvider",
+  "interactionDriver",
   "entityResolver",
   "agentRenderer",
   "endpoint",
@@ -2748,6 +2786,7 @@ var KayAgentTargetManifest = z8.strictObject({
     resources: z8.array(ResourceContribution).optional(),
     skills: z8.array(SkillContribution).optional(),
     searchProviders: z8.array(SearchProviderContribution).optional(),
+    interactionDrivers: z8.array(InteractionDriverContribution).optional(),
     entityResolvers: z8.array(EntityResolverContribution).optional(),
     renderers: z8.array(AgentRenderContribution).optional(),
     // Handler restricted to skill | tool by the manifest-level refinement below (see
@@ -3711,6 +3750,7 @@ function collectDeclaredContributionIds(manifest) {
   pushContributionIds(output, ["targets", "kay", "agent", "contributes", "resources"], agent?.resources);
   pushContributionIds(output, ["targets", "kay", "agent", "contributes", "skills"], agent?.skills);
   pushContributionIds(output, ["targets", "kay", "agent", "contributes", "searchProviders"], agent?.searchProviders);
+  pushContributionIds(output, ["targets", "kay", "agent", "contributes", "interactionDrivers"], agent?.interactionDrivers);
   pushContributionIds(output, ["targets", "kay", "agent", "contributes", "entityResolvers"], agent?.entityResolvers);
   pushContributionIds(output, ["targets", "kay", "agent", "contributes", "renderers"], agent?.renderers);
   pushContributionIds(output, ["targets", "kay", "agent", "contributes", "commands"], agent?.commands);
@@ -4052,6 +4092,7 @@ function collectContributionSources(manifest) {
   pushAll(output, "kay.agent", "resource", agent?.resources);
   pushAll(output, "kay.agent", "skill", agent?.skills);
   pushAll(output, "kay.agent", "searchProvider", agent?.searchProviders);
+  pushAll(output, "kay.agent", "interactionDriver", agent?.interactionDrivers);
   pushAll(output, "kay.agent", "entityResolver", agent?.entityResolvers);
   pushAll(output, "kay.agent", "agentRenderer", agent?.renderers);
   pushAll(output, "kay.agent", "command", agent?.commands);
@@ -4676,6 +4717,7 @@ export {
   GlobalContributionId,
   HttpStatusCode,
   HttpsUrl,
+  InteractionDriverContribution,
   JsonObject,
   JsonPointer,
   JsonSchema,
@@ -4871,6 +4913,7 @@ export {
   satisfiesSemverRange,
   sessionHealthEntrySchema,
   sessionHealthPWellDecile,
+  turnMessageOrigin,
   turnPacket,
   urlHostWithinDomain,
   validateKayUiEventSubscription,

package/package.json

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