@yaklabs-ai/plugin-protocol 0.11.0 → 0.12.3

package/README.md

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

package/THIRD-PARTY-INVENTORY.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@yaklabs-ai/plugin-protocol",
-  "version": "0.11.0",
+  "version": "0.12.3",
   "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", "0.10.0"];
+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", "0.12.2"];
 
 export declare const KAY_PLUGIN_PROTOCOL_PACKAGE_NAME: "@kay/plugin-protocol";
 
@@ -2069,8 +2095,64 @@ export declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 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.
+ *
+ * 0.12.3 adds the `page` reference open kind (`{ kind: "page", pageId }` on a
+ * `referencePresentations` entry), and lets a presentation name a `kay.app` URI module as well as a
+ * `kay.agent` one. A plugin's own `scheme://` references then pill with its icon and the module's
+ * `describe` title, and a click opens the plugin's own registered page with the reference URI as
+ * the page's `objectId`. Additive: a `^0.12.2` plugin keeps loading. The value is new schema, so an
+ * older host refuses the whole manifest at parse (`manifest-schema-invalid`), before any range
+ * check runs. A plugin that declares it still declares `^0.12.3`, so the install-time version
+ * checks name the mismatch instead of a schema error.
  */
-export declare const KAY_PLUGIN_SDK_VERSION: "0.11.0";
+export declare const KAY_PLUGIN_SDK_VERSION: "0.12.3";
 
 export declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -2163,6 +2245,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>;
@@ -2503,6 +2593,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>;
@@ -2725,6 +2823,9 @@ export declare const KayPluginManifestV1: z.ZodObject<{
                             kind: z.ZodLiteral<"working-document">;
                         }, z.core.$strict>, z.ZodObject<{
                             kind: z.ZodLiteral<"browser-pane">;
+                        }, z.core.$strict>, z.ZodObject<{
+                            kind: z.ZodLiteral<"page">;
+                            pageId: z.ZodString;
                         }, z.core.$strict>], "kind">;
                         variants: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
                             resourceKind: z.ZodString;
@@ -2767,12 +2868,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";
@@ -3203,12 +3304,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";
@@ -3307,6 +3408,9 @@ export declare const KayUiTargetManifest: z.ZodObject<{
                 kind: z.ZodLiteral<"working-document">;
             }, z.core.$strict>, z.ZodObject<{
                 kind: z.ZodLiteral<"browser-pane">;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"page">;
+                pageId: z.ZodString;
             }, z.core.$strict>], "kind">;
             variants: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
                 resourceKind: z.ZodString;
@@ -3349,12 +3453,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";
@@ -3590,7 +3694,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";
@@ -4026,6 +4130,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">;
@@ -4130,6 +4238,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">;
@@ -4233,6 +4350,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">;
@@ -4337,6 +4458,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">;
@@ -4435,6 +4565,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">;
@@ -4539,6 +4673,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">;
@@ -4700,6 +4843,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">;
@@ -4804,6 +4951,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">;
@@ -4922,6 +5078,7 @@ export declare const PluginContributionKind: z.ZodEnum<{
     artifactUriModule: "artifactUriModule";
     cliBinding: "cliBinding";
     searchProvider: "searchProvider";
+    interactionDriver: "interactionDriver";
     entityResolver: "entityResolver";
     agentRenderer: "agentRenderer";
     eventDefinition: "eventDefinition";
@@ -5505,6 +5662,9 @@ export declare const ReferenceOpenBehavior: z.ZodDiscriminatedUnion<[z.ZodObject
     kind: z.ZodLiteral<"working-document">;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"browser-pane">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"page">;
+    pageId: z.ZodString;
 }, z.core.$strict>], "kind">;
 
 export declare type ReferenceOpenBehavior = z.infer<typeof ReferenceOpenBehavior>;
@@ -5517,6 +5677,9 @@ export declare const ReferencePresentationContribution: z.ZodObject<{
         kind: z.ZodLiteral<"working-document">;
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"browser-pane">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"page">;
+        pageId: z.ZodString;
     }, z.core.$strict>], "kind">;
     variants: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         resourceKind: z.ZodString;
@@ -5899,12 +6062,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";
@@ -6185,6 +6348,7 @@ export declare const ResolvedPluginContractV1: z.ZodObject<{
             artifactUriModule: "artifactUriModule";
             cliBinding: "cliBinding";
             searchProvider: "searchProvider";
+            interactionDriver: "interactionDriver";
             entityResolver: "entityResolver";
             agentRenderer: "agentRenderer";
             eventDefinition: "eventDefinition";
@@ -6707,6 +6871,9 @@ export declare const ResolvedPluginContractV1: z.ZodObject<{
             kind: z.ZodLiteral<"working-document">;
         }, z.core.$strict>, z.ZodObject<{
             kind: z.ZodLiteral<"browser-pane">;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"page">;
+            pageId: z.ZodString;
         }, z.core.$strict>], "kind">;
         variants: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
             resourceKind: z.ZodString;
@@ -6748,12 +6915,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";
@@ -6789,6 +6956,7 @@ export declare const ResolvedPluginContributionId: z.ZodObject<{
         artifactUriModule: "artifactUriModule";
         cliBinding: "cliBinding";
         searchProvider: "searchProvider";
+        interactionDriver: "interactionDriver";
         entityResolver: "entityResolver";
         agentRenderer: "agentRenderer";
         eventDefinition: "eventDefinition";
@@ -7139,6 +7307,9 @@ export declare const ResolvedReferencePresentation: z.ZodObject<{
         kind: z.ZodLiteral<"working-document">;
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"browser-pane">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"page">;
+        pageId: z.ZodString;
     }, z.core.$strict>], "kind">;
     variants: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         resourceKind: z.ZodString;
@@ -7524,6 +7695,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>;
@@ -7747,6 +7919,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>;
@@ -8089,6 +8262,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;
@@ -8149,12 +8329,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";
@@ -8185,12 +8365,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.11.0";
+var KAY_PLUGIN_SDK_VERSION = "0.12.3";
 var KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS = [
   "0.8.0",
   "0.8.1",
@@ -125,7 +125,12 @@ var KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS = [
   "0.8.5",
   "0.9.0",
   "0.9.1",
-  "0.10.0"
+  "0.10.0",
+  "0.11.0",
+  "0.11.1",
+  "0.12.0",
+  "0.12.1",
+  "0.12.2"
 ];
 var KAY_PLUGIN_TARGET_NAMES = [
   "kay.agent",
@@ -344,7 +349,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(),
@@ -1516,6 +1526,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"),
@@ -1614,6 +1632,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"),
@@ -1650,6 +1674,7 @@ var PLUGIN_CAPABILITY_SLUGS = [
   "process.spawn",
   "corpus.read",
   "signals.read",
+  "skills.read",
   "workspace.command",
   "sessions.create",
   "sessions.update",
@@ -1666,6 +1691,7 @@ var PLUGIN_CAPABILITY_SLUGS = [
   "account.update",
   "agents.permissions",
   "tool-interception.register",
+  "interaction.surface",
   "config.declare-section",
   "auth.own-service",
   "auth.shared-identity",
@@ -1754,6 +1780,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":
@@ -1776,6 +1803,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":
@@ -1818,6 +1847,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":
@@ -1846,6 +1876,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":
@@ -2387,6 +2419,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,
@@ -2504,7 +2541,13 @@ var ResultRendererContribution = z7.strictObject({
 });
 var ReferenceOpenBehavior = z7.discriminatedUnion("kind", [
   z7.strictObject({ kind: z7.literal("working-document") }),
-  z7.strictObject({ kind: z7.literal("browser-pane") })
+  z7.strictObject({ kind: z7.literal("browser-pane") }),
+  /**
+   * Open one of the presenting plugin's OWN registered pages (`registerPage`'s
+   * descriptor id) with the reference's canonical URI as the page's `objectId`.
+   * Needs no web address, so a plugin-only resource (`user-todo://items/3`) can pill.
+   */
+  z7.strictObject({ kind: z7.literal("page"), pageId: NonEmptyString })
 ]);
 var ReferencePresentationVariant = z7.strictObject({
   resourceKind: NonEmptyString,
@@ -2643,6 +2686,7 @@ var PluginContributionKind = z7.enum([
   "resource",
   "skill",
   "searchProvider",
+  "interactionDriver",
   "entityResolver",
   "agentRenderer",
   "endpoint",
@@ -2749,6 +2793,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
@@ -3212,7 +3257,10 @@ var KayPluginManifestV1 = z8.strictObject({
   }
   const subscribedUiEvents = new Set(manifest.targets?.kay?.ui?.contributes?.eventSubscriptions?.map((subscription) => subscription.event) ?? []);
   const invokedUiEndpoints = new Set(manifest.permissions?.byTarget["kay.ui"]?.endpoints?.filter((grant) => grant.operations.includes("invoke")).map((grant) => grant.endpoint) ?? []);
-  const uriModuleIds = new Set(manifest.targets?.kay?.agent?.contributes?.uriModules?.map((module) => module.localId) ?? []);
+  const uriModuleIds = new Set([
+    ...manifest.targets?.kay?.agent?.contributes?.uriModules ?? [],
+    ...manifest.targets?.kay?.app?.contributes?.uriModules ?? []
+  ].map((module) => module.localId));
   const presentationByUriModule = /* @__PURE__ */ new Map();
   for (const [index, presentation] of (manifest.targets?.kay?.ui?.contributes?.referencePresentations ?? []).entries()) {
     const path = [
@@ -3712,6 +3760,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);
@@ -4053,6 +4102,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);
@@ -4677,6 +4727,7 @@ export {
   GlobalContributionId,
   HttpStatusCode,
   HttpsUrl,
+  InteractionDriverContribution,
   JsonObject,
   JsonPointer,
   JsonSchema,
@@ -4872,6 +4923,7 @@ export {
   satisfiesSemverRange,
   sessionHealthEntrySchema,
   sessionHealthPWellDecile,
+  turnMessageOrigin,
   turnPacket,
   urlHostWithinDomain,
   validateKayUiEventSubscription,

package/package.json

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