@yaklabs-ai/plugin-protocol 0.8.5 → 0.9.1

package/README.md

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

package/THIRD-PARTY-INVENTORY.json

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

package/dist/index.d.ts

@@ -262,9 +262,11 @@ export declare const ArtifactProvenanceCaptureContextSchema: z.ZodObject<{
                     type: z.ZodEnum<{
                         "turn-settled": "turn-settled";
                         "phase-shift": "phase-shift";
+                        "human-message": "human-message";
                     }>;
                     entryId: z.ZodString;
                     runId: z.ZodOptional<z.ZodString>;
+                    throughEntryId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
                 }, z.core.$strict>>;
                 dedupeKey: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>;
@@ -352,9 +354,11 @@ export declare const ArtifactProvenanceCaptureContextSchema: z.ZodObject<{
                     type: z.ZodEnum<{
                         "turn-settled": "turn-settled";
                         "phase-shift": "phase-shift";
+                        "human-message": "human-message";
                     }>;
                     entryId: z.ZodString;
                     runId: z.ZodOptional<z.ZodString>;
+                    throughEntryId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
                 }, z.core.$strict>>;
                 dedupeKey: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>>;
@@ -446,9 +450,11 @@ export declare const ArtifactProvenanceCause: z.ZodDiscriminatedUnion<[z.ZodObje
             type: z.ZodEnum<{
                 "turn-settled": "turn-settled";
                 "phase-shift": "phase-shift";
+                "human-message": "human-message";
             }>;
             entryId: z.ZodString;
             runId: z.ZodOptional<z.ZodString>;
+            throughEntryId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         }, z.core.$strict>>;
         dedupeKey: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
@@ -521,9 +527,11 @@ export declare const ArtifactProvenanceEnvelopeV1: z.ZodPipe<z.ZodUnknown, z.Zod
                     type: z.ZodEnum<{
                         "turn-settled": "turn-settled";
                         "phase-shift": "phase-shift";
+                        "human-message": "human-message";
                     }>;
                     entryId: z.ZodString;
                     runId: z.ZodOptional<z.ZodString>;
+                    throughEntryId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
                 }, z.core.$strict>>;
                 dedupeKey: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>;
@@ -610,9 +618,11 @@ export declare const ArtifactProvenanceEnvelopeV1: z.ZodPipe<z.ZodUnknown, z.Zod
                         type: z.ZodEnum<{
                             "turn-settled": "turn-settled";
                             "phase-shift": "phase-shift";
+                            "human-message": "human-message";
                         }>;
                         entryId: z.ZodString;
                         runId: z.ZodOptional<z.ZodString>;
+                        throughEntryId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
                     }, z.core.$strict>>;
                     dedupeKey: z.ZodOptional<z.ZodString>;
                 }, z.core.$strict>;
@@ -724,9 +734,11 @@ export declare const ArtifactProvenanceEnvelopeV1: z.ZodPipe<z.ZodUnknown, z.Zod
                     type: z.ZodEnum<{
                         "turn-settled": "turn-settled";
                         "phase-shift": "phase-shift";
+                        "human-message": "human-message";
                     }>;
                     entryId: z.ZodString;
                     runId: z.ZodOptional<z.ZodString>;
+                    throughEntryId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
                 }, z.core.$strict>>;
                 dedupeKey: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>>;
@@ -893,9 +905,11 @@ export declare const ArtifactProvenanceMutation: z.ZodObject<{
                     type: z.ZodEnum<{
                         "turn-settled": "turn-settled";
                         "phase-shift": "phase-shift";
+                        "human-message": "human-message";
                     }>;
                     entryId: z.ZodString;
                     runId: z.ZodOptional<z.ZodString>;
+                    throughEntryId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
                 }, z.core.$strict>>;
                 dedupeKey: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>;
@@ -986,9 +1000,11 @@ export declare const ArtifactProvenanceOperation: z.ZodObject<{
                 type: z.ZodEnum<{
                     "turn-settled": "turn-settled";
                     "phase-shift": "phase-shift";
+                    "human-message": "human-message";
                 }>;
                 entryId: z.ZodString;
                 runId: z.ZodOptional<z.ZodString>;
+                throughEntryId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             }, z.core.$strict>>;
             dedupeKey: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>;
@@ -1124,9 +1140,11 @@ export declare const ArtifactProvenanceSession: z.ZodObject<{
                 type: z.ZodEnum<{
                     "turn-settled": "turn-settled";
                     "phase-shift": "phase-shift";
+                    "human-message": "human-message";
                 }>;
                 entryId: z.ZodString;
                 runId: z.ZodOptional<z.ZodString>;
+                throughEntryId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             }, z.core.$strict>>;
             dedupeKey: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
@@ -1556,6 +1574,93 @@ export declare const CorpusContribution: z.ZodObject<{
 
 export declare type CorpusContribution = z.infer<typeof CorpusContribution>;
 
+export declare interface CorpusResourceInvocation {
+    readonly eventId: string;
+    /** Envelope recording time, never a run/message/incident identifier. */
+    readonly at: string;
+    readonly kind: CorpusResourceKind;
+    readonly sessionId: string;
+    /** Falls back to sessionId for legacy events without a recorded root. */
+    readonly rootSessionId: string;
+    readonly name: string;
+    readonly sourceId?: string;
+    /** Absent on unresolved legacy rows; names/aliases are not a substitute. */
+    readonly resourceId?: string;
+    readonly version?: string;
+    readonly variantId?: string;
+    readonly rootProvenance: SessionProvenanceRecord;
+    /** Current index hints, not the session's historical context at invocation. */
+    readonly currentContext: {
+        readonly cwd: string;
+        readonly projectId?: string;
+    };
+}
+
+/** Exclusive keyset position; preserve timestamp precision when returning it. */
+export declare const CorpusResourceInvocationCursor: z.ZodObject<{
+    at: z.ZodISODateTime;
+    eventId: z.ZodString;
+}, z.core.$strict>;
+
+export declare type CorpusResourceInvocationCursor = z.infer<typeof CorpusResourceInvocationCursor>;
+
+export declare interface CorpusResourceInvocationExclusion {
+    readonly eventId: string;
+    readonly sessionId: string;
+    readonly rootSessionId: string;
+    readonly reason: "session-missing" | "root-missing" | "root-provenance-unverified" | "root-creator-filtered";
+}
+
+export declare type CorpusResourceInvocationPage = {
+    readonly state: "available";
+    readonly items: readonly CorpusResourceInvocation[];
+    /** Absent only when this recording-time window is exhausted. */
+    readonly next?: CorpusResourceInvocationCursor;
+    /** Telemetry import succeeded; exclusions still describe missing or filtered index facts. */
+    readonly coverage: {
+        readonly scanned: number;
+        readonly exclusions: readonly CorpusResourceInvocationExclusion[];
+    };
+} | {
+    readonly state: "unavailable";
+    readonly reason: "not-wired" | "telemetry-unavailable" | "telemetry-incomplete" | "index-unavailable" | "invalid-record";
+    readonly message: string;
+};
+
+/** Half-open recording-time window. Limits bound scanned rows, including exclusions. */
+export declare const CorpusResourceInvocationQuery: z.ZodObject<{
+    kind: z.ZodEnum<{
+        skill: "skill";
+        "context-file": "context-file";
+        "prompt-command": "prompt-command";
+    }>;
+    since: z.ZodISODateTime;
+    until: z.ZodISODateTime;
+    after: z.ZodOptional<z.ZodObject<{
+        at: z.ZodISODateTime;
+        eventId: z.ZodString;
+    }, z.core.$strict>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    rootCreatedByKind: z.ZodOptional<z.ZodEnum<{
+        human: "human";
+        agent: "agent";
+        plugin: "plugin";
+        trigger: "trigger";
+        daemon: "daemon";
+    }>>;
+}, z.core.$strict>;
+
+export declare type CorpusResourceInvocationQuery = z.infer<typeof CorpusResourceInvocationQuery>;
+
+/** Roster invocation facts, not evidence that a read completed successfully. */
+export declare const CorpusResourceKind: z.ZodEnum<{
+    skill: "skill";
+    "context-file": "context-file";
+    "prompt-command": "prompt-command";
+}>;
+
+export declare type CorpusResourceKind = z.infer<typeof CorpusResourceKind>;
+
 /** Drop repeats under {@link sameClaim}, preserving first-seen order (a sort settles the rest). */
 export declare function dedupeClaims(claims: readonly PluginCapabilityClaimV1[]): PluginCapabilityClaimV1[];
 
@@ -1829,6 +1934,9 @@ 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"];
+
 export declare const KAY_PLUGIN_PROTOCOL_PACKAGE_NAME: "@kay/plugin-protocol";
 
 export declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
@@ -1932,7 +2040,7 @@ export declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * slot: nothing a `^0.8.1`/`^0.8.3` plugin already compiles against changes
  * shape, and the fix is which bytes reach npm, not what the contract promises.
  */
-export declare const KAY_PLUGIN_SDK_VERSION: "0.8.5";
+export declare const KAY_PLUGIN_SDK_VERSION: "0.9.1";
 
 export declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -2253,6 +2361,8 @@ export declare interface KayPluginHostCompatibility {
     readonly protocolVersion: string;
     /** The plugin SDK version this host injects, e.g. `KAY_PLUGIN_SDK_VERSION`. */
     readonly sdkVersion: string;
+    /** Older SDK releases whose runtime contracts this host still implements; absent means none. */
+    readonly compatibleSdkVersions?: readonly string[];
     /** The Kay app version. Advisory only — never a refusal. */
     readonly appVersion: string;
     /**
@@ -7348,9 +7458,11 @@ export declare const SessionCausedByEvent: z.ZodObject<{
         type: z.ZodEnum<{
             "turn-settled": "turn-settled";
             "phase-shift": "phase-shift";
+            "human-message": "human-message";
         }>;
         entryId: z.ZodString;
         runId: z.ZodOptional<z.ZodString>;
+        throughEntryId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strict>>;
     dedupeKey: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
@@ -7569,9 +7681,11 @@ export declare const SessionProvenanceRecord: z.ZodObject<{
             type: z.ZodEnum<{
                 "turn-settled": "turn-settled";
                 "phase-shift": "phase-shift";
+                "human-message": "human-message";
             }>;
             entryId: z.ZodString;
             runId: z.ZodOptional<z.ZodString>;
+            throughEntryId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         }, z.core.$strict>>;
         dedupeKey: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;

package/dist/index.js

@@ -115,7 +115,16 @@ 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.8.5";
+var KAY_PLUGIN_SDK_VERSION = "0.9.1";
+var KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS = [
+  "0.8.0",
+  "0.8.1",
+  "0.8.2",
+  "0.8.3",
+  "0.8.4",
+  "0.8.5",
+  "0.9.0"
+];
 var KAY_PLUGIN_TARGET_NAMES = [
   "kay.agent",
   "kay.app",
@@ -333,10 +342,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"]),
+    type: z3.enum(["turn-settled", "phase-shift", "human-message"]),
     entryId: NonEmptyString2,
     /** The source run captured at the event boundary; absence remains unresolved. */
-    runId: NonEmptyString2.optional()
+    runId: NonEmptyString2.optional(),
+    /** Exact prior persisted boundary for a projected human-message event; null means empty history. */
+    throughEntryId: NonEmptyString2.nullable().optional()
   }).optional(),
   /**
    * The plugin-supplied exact-match dedupe key, when it gave one. Absent when the handler chose
@@ -2106,11 +2117,16 @@ function checkKayPluginHostCompatibility(compatibility, host) {
     }
     return { refusal: void 0, advisories };
   }
-  if (parseSemver(host.sdkVersion) === void 0) {
+  const supportedVersions = [
+    host.sdkVersion,
+    ...host.compatibleSdkVersions ?? []
+  ];
+  const invalidVersion = supportedVersions.find((version) => parseSemver(version) === void 0);
+  if (invalidVersion !== void 0) {
     return {
       refusal: {
         code: "host-sdk-version-invalid",
-        message: `cannot be checked: this Kay reports plugin SDK "${host.sdkVersion}", which is not valid semver`
+        message: `cannot be checked: this Kay reports plugin SDK "${invalidVersion}", which is not valid semver`
       },
       advisories
     };
@@ -2124,7 +2140,7 @@ function checkKayPluginHostCompatibility(compatibility, host) {
       advisories
     };
   }
-  if (satisfiesSemverRange(host.sdkVersion, range) !== true) {
+  if (!supportedVersions.some((version) => satisfiesSemverRange(version, range) === true)) {
     return {
       refusal: {
         code: "sdk-range-unsatisfied",
@@ -4427,15 +4443,37 @@ function sessionHealthPWellDecile(pWell) {
   return Math.min(9, Math.floor(pWell * 10));
 }
 
-// packages/plugin-protocol/dist/ui-app-package.js
+// packages/plugin-protocol/dist/resource-invocations.js
 import { z as z11 } from "zod";
+var CorpusResourceKind = z11.enum([
+  "skill",
+  "context-file",
+  "prompt-command"
+]);
+var CorpusResourceInvocationCursor = z11.strictObject({
+  at: z11.iso.datetime({ offset: true }),
+  eventId: z11.string().min(1)
+});
+var CorpusResourceInvocationQuery = z11.strictObject({
+  kind: CorpusResourceKind,
+  since: z11.iso.datetime({ offset: true }),
+  until: z11.iso.datetime({ offset: true }),
+  after: CorpusResourceInvocationCursor.optional(),
+  limit: z11.number().int().min(1).max(1e3).optional(),
+  rootCreatedByKind: z11.enum(AGENT_RUNTIME_SESSION_CREATOR_KINDS).optional()
+}).refine((value) => Date.parse(value.since) < Date.parse(value.until), {
+  message: "since must precede until"
+});
+
+// packages/plugin-protocol/dist/ui-app-package.js
+import { z as z12 } from "zod";
 var KAY_UI_APP_PACKAGE_PROTOCOL = "kay.ui.app-package.v1";
 var KAY_UI_BUNDLE_INDEX_PROTOCOL = "kay.ui.bundle-index.v1";
-var KayUiBundleOutputPath = z11.string().trim().min(1).refine((value) => !value.startsWith("/") && !value.startsWith("./") && !value.includes("\\") && !value.split("/").includes(".."), { message: "bundle output path must stay relative to the bundle root" });
-var KayUiBundleIndexV1 = z11.strictObject({
-  protocol: z11.literal(KAY_UI_BUNDLE_INDEX_PROTOCOL),
+var KayUiBundleOutputPath = z12.string().trim().min(1).refine((value) => !value.startsWith("/") && !value.startsWith("./") && !value.includes("\\") && !value.split("/").includes(".."), { message: "bundle output path must stay relative to the bundle root" });
+var KayUiBundleIndexV1 = z12.strictObject({
+  protocol: z12.literal(KAY_UI_BUNDLE_INDEX_PROTOCOL),
   entryPath: KayUiBundleOutputPath,
-  files: z11.array(z11.strictObject({
+  files: z12.array(z12.strictObject({
     path: KayUiBundleOutputPath,
     mediaType: NonEmptyString
   })).min(1)
@@ -4462,19 +4500,19 @@ var KayUiBundleIndexV1 = z11.strictObject({
 function parseKayUiBundleIndexV1(input) {
   return KayUiBundleIndexV1.parse(input);
 }
-var KayUiAppPackageFile = z11.strictObject({
+var KayUiAppPackageFile = z12.strictObject({
   path: PackageAssetPath,
   mediaType: NonEmptyString,
-  bytes: z11.instanceof(Uint8Array).refine((bytes) => bytes.byteLength > 0, {
+  bytes: z12.instanceof(Uint8Array).refine((bytes) => bytes.byteLength > 0, {
     message: "app package file bytes must not be empty"
   })
 });
-var KayUiAppPackageV1 = z11.strictObject({
-  protocol: z11.literal(KAY_UI_APP_PACKAGE_PROTOCOL),
+var KayUiAppPackageV1 = z12.strictObject({
+  protocol: z12.literal(KAY_UI_APP_PACKAGE_PROTOCOL),
   appLocalId: LocalContributionId,
   entry: KayUiAppPackageFile,
-  styles: z11.array(KayUiAppPackageFile).optional(),
-  assets: z11.array(KayUiAppPackageFile).optional()
+  styles: z12.array(KayUiAppPackageFile).optional(),
+  assets: z12.array(KayUiAppPackageFile).optional()
 }).superRefine((appPackage, ctx) => {
   if (appPackage.entry.mediaType !== "application/javascript") {
     ctx.addIssue({
@@ -4511,16 +4549,16 @@ function parseKayUiAppPackageV1(input) {
 }
 
 // packages/plugin-protocol/dist/whiteboard.js
-import { z as z12 } from "zod";
+import { z as z13 } from "zod";
 var WhiteboardValue = JsonValue;
-var WhiteboardEntryEnvelope = z12.strictObject({
+var WhiteboardEntryEnvelope = z13.strictObject({
   id: NonEmptyString,
   typeId: GlobalContributionId,
-  schemaVersion: z12.number().int().positive(),
-  title: z12.string(),
+  schemaVersion: z13.number().int().positive(),
+  title: z13.string(),
   authorSessionId: NonEmptyString.nullable()
 });
-var WhiteboardEntrySummary = z12.strictObject({
+var WhiteboardEntrySummary = z13.strictObject({
   name: NonEmptyString,
   entry: WhiteboardEntryEnvelope,
   revision: NonEmptyString
@@ -4528,31 +4566,31 @@ var WhiteboardEntrySummary = z12.strictObject({
 var WhiteboardEntrySnapshot = WhiteboardEntrySummary.extend({
   value: WhiteboardValue
 });
-var WhiteboardDiagnostic = z12.strictObject({
+var WhiteboardDiagnostic = z13.strictObject({
   ruleId: NonEmptyString,
-  severity: z12.enum(["error", "warning"]),
+  severity: z13.enum(["error", "warning"]),
   message: NonEmptyString
 });
-var WhiteboardEntryInfo = z12.strictObject({
+var WhiteboardEntryInfo = z13.strictObject({
   name: NonEmptyString,
   revision: NonEmptyString,
   entry: WhiteboardEntryEnvelope.optional(),
-  state: z12.enum(["available", "unavailable", "unsupported-version", "invalid"]),
-  mutable: z12.boolean(),
-  diagnostics: z12.array(z12.string())
+  state: z13.enum(["available", "unavailable", "unsupported-version", "invalid"]),
+  mutable: z13.boolean(),
+  diagnostics: z13.array(z13.string())
 });
 var WhiteboardEntryInspection = WhiteboardEntryInfo.extend({
   value: WhiteboardValue.optional(),
-  text: z12.string(),
-  truncated: z12.boolean()
+  text: z13.string(),
+  truncated: z13.boolean()
 });
-var WhiteboardTypeInfo = z12.strictObject({
+var WhiteboardTypeInfo = z13.strictObject({
   typeId: GlobalContributionId,
   displayName: NonEmptyString,
-  schemaVersion: z12.number().int().positive(),
-  available: z12.boolean(),
+  schemaVersion: z13.number().int().positive(),
+  available: z13.boolean(),
   /** A plugin-owned readonly presentation; absent types use the host fallback. */
-  presentation: z12.strictObject({
+  presentation: z13.strictObject({
     app: GlobalContributionId
   }).optional()
 });
@@ -4594,6 +4632,9 @@ export {
   ContextContributorContribution,
   ConverterContribution,
   CorpusContribution,
+  CorpusResourceInvocationCursor,
+  CorpusResourceInvocationQuery,
+  CorpusResourceKind,
   DeviceDelegationContribution,
   EndpointContribution,
   EndpointGrantRequest,
@@ -4615,6 +4656,7 @@ export {
   KAY_APP_DATA_READ_RESULT_MAX_BYTES,
   KAY_APP_DATA_SNAPSHOT_MAX_BYTES,
   KAY_EVENT_PUBLISHER_ID,
+  KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS,
   KAY_PLUGIN_PROTOCOL_PACKAGE_NAME,
   KAY_PLUGIN_PROTOCOL_VERSION,
   KAY_PLUGIN_SDK_VERSION,

package/package.json

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