@yaklabs-ai/plugin-protocol 0.13.4 → 0.13.6

package/README.md

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

package/THIRD-PARTY-INVENTORY.json

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

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";
+                        "assistant-message": "assistant-message";
                         "ui-action": "ui-action";
                     }>;
                     entryId: z.ZodString;
@@ -356,6 +357,7 @@ export declare const ArtifactProvenanceCaptureContextSchema: z.ZodObject<{
                         "turn-settled": "turn-settled";
                         "phase-shift": "phase-shift";
                         "human-message": "human-message";
+                        "assistant-message": "assistant-message";
                         "ui-action": "ui-action";
                     }>;
                     entryId: z.ZodString;
@@ -453,6 +455,7 @@ export declare const ArtifactProvenanceCause: z.ZodDiscriminatedUnion<[z.ZodObje
                 "turn-settled": "turn-settled";
                 "phase-shift": "phase-shift";
                 "human-message": "human-message";
+                "assistant-message": "assistant-message";
                 "ui-action": "ui-action";
             }>;
             entryId: z.ZodString;
@@ -531,6 +534,7 @@ export declare const ArtifactProvenanceEnvelopeV1: z.ZodPipe<z.ZodUnknown, z.Zod
                         "turn-settled": "turn-settled";
                         "phase-shift": "phase-shift";
                         "human-message": "human-message";
+                        "assistant-message": "assistant-message";
                         "ui-action": "ui-action";
                     }>;
                     entryId: z.ZodString;
@@ -623,6 +627,7 @@ export declare const ArtifactProvenanceEnvelopeV1: z.ZodPipe<z.ZodUnknown, z.Zod
                             "turn-settled": "turn-settled";
                             "phase-shift": "phase-shift";
                             "human-message": "human-message";
+                            "assistant-message": "assistant-message";
                             "ui-action": "ui-action";
                         }>;
                         entryId: z.ZodString;
@@ -740,6 +745,7 @@ export declare const ArtifactProvenanceEnvelopeV1: z.ZodPipe<z.ZodUnknown, z.Zod
                         "turn-settled": "turn-settled";
                         "phase-shift": "phase-shift";
                         "human-message": "human-message";
+                        "assistant-message": "assistant-message";
                         "ui-action": "ui-action";
                     }>;
                     entryId: z.ZodString;
@@ -912,6 +918,7 @@ export declare const ArtifactProvenanceMutation: z.ZodObject<{
                         "turn-settled": "turn-settled";
                         "phase-shift": "phase-shift";
                         "human-message": "human-message";
+                        "assistant-message": "assistant-message";
                         "ui-action": "ui-action";
                     }>;
                     entryId: z.ZodString;
@@ -1008,6 +1015,7 @@ export declare const ArtifactProvenanceOperation: z.ZodObject<{
                     "turn-settled": "turn-settled";
                     "phase-shift": "phase-shift";
                     "human-message": "human-message";
+                    "assistant-message": "assistant-message";
                     "ui-action": "ui-action";
                 }>;
                 entryId: z.ZodString;
@@ -1149,6 +1157,7 @@ export declare const ArtifactProvenanceSession: z.ZodObject<{
                     "turn-settled": "turn-settled";
                     "phase-shift": "phase-shift";
                     "human-message": "human-message";
+                    "assistant-message": "assistant-message";
                     "ui-action": "ui-action";
                 }>;
                 entryId: z.ZodString;
@@ -1322,6 +1331,9 @@ export declare const AuthServiceReference: z.ZodString;
 
 export declare type AuthServiceReference = z.infer<typeof AuthServiceReference>;
 
+/** Cap a plugin-controlled message at {@link PLUGIN_DIAGNOSTIC_MESSAGE_CAP} characters. */
+export declare function boundPluginDiagnosticMessage(message: string): string;
+
 /**
  * {@link mintOperation} and {@link resolveSessionAncestry}, composed into one capture.
  *
@@ -1368,7 +1380,7 @@ export declare function captureFailedContext(input: {
     readonly detail: string;
 }, clock?: CaptureClock): ArtifactProvenanceCaptureContext;
 
-export declare function checkKayPluginHostCompatibility(compatibility: PluginCompatibilityManifest | undefined, host: KayPluginHostCompatibility): KayPluginCompatibilityReport;
+export declare function checkKayPluginHostCompatibility(compatibility: DeclaredKayPluginCompatibility | undefined, host: KayPluginHostCompatibility): KayPluginCompatibilityReport;
 
 /**
  * The env var name a `cliBindings` contribution injects a resolved credential
@@ -1682,9 +1694,35 @@ export declare const CorpusResourceKind: z.ZodEnum<{
 
 export declare type CorpusResourceKind = z.infer<typeof CorpusResourceKind>;
 
+/**
+ * The `compatibility` block as the check reads it. Structural rather than the parsed
+ * `PluginCompatibilityManifest`, so a host can judge the block of a manifest whose other fields
+ * this build's strict schema would refuse (`judgeKayPluginDirectory` does, before the parse).
+ */
+export declare interface DeclaredKayPluginCompatibility {
+    readonly supportedProtocols?: readonly string[] | undefined;
+    readonly minKayVersion?: string | undefined;
+    readonly sdk?: string | undefined;
+}
+
 /** Drop repeats under {@link sameClaim}, preserving first-seen order (a sort settles the rest). */
 export declare function dedupeClaims(claims: readonly PluginCapabilityClaimV1[]): PluginCapabilityClaimV1[];
 
+/**
+ * The one `toolName` a directory plugin may declare for the tool `localId`: every `.` in
+ * `namespace` becomes `_`, then one more `_` joins `localId`. The directory verdict drops a tool
+ * that declares anything else. Bundled plugins are not held to it.
+ *
+ * Injective over every schema-valid pair, so two directory plugins can only derive the same tool
+ * name by sharing both namespace and localId. Neither input can contain `_` (`PLUGIN_ID_PATTERN`
+ * and `LOCAL_CONTRIBUTION_ID_PATTERN` exclude it), so every `_` in the output was inserted here,
+ * and splitting on `_` recovers the namespace's segments and then `localId` (which has no `.`).
+ *
+ * A `-` is deliberately left alone: mapping it to `_` too would send `("a", "b-c")` and
+ * `("a-b", "c")` to the same `a_b_c`. The tool-name alphabet admits `-` for that reason (#4341).
+ */
+export declare function deriveDirectoryPluginToolName(namespace: string, localId: string): string;
+
 export declare const DeviceDelegationContribution: z.ZodObject<{
     localId: z.ZodString;
     device: z.ZodEnum<{
@@ -1952,6 +1990,26 @@ export declare type JsonValue = string | number | boolean | null | JsonValue[] |
 
 export declare const JsonValue: z.ZodType<JsonValue>;
 
+/** Judge one plugin directory. Never throws for a bad plugin: every finding is a diagnostic. */
+export declare function judgeKayPluginDirectory(input: JudgeKayPluginDirectoryInput): Promise<KayPluginDirectoryVerdict>;
+
+export declare interface JudgeKayPluginDirectoryInput {
+    readonly tree: KayPluginTreeReader;
+    /** The root the directory was found under, and the directory's name there: diagnostic provenance. */
+    readonly root: string;
+    readonly dir: string;
+    /**
+     * The host to judge `compatibility` against. `undefined` skips that step: a host that cannot
+     * state its own version has no evidence a plugin is incompatible.
+     */
+    readonly host: KayPluginHostCompatibility | undefined;
+    /**
+     * Set when the caller already knows this directory is a commit of a plugin, so a missing
+     * manifest is a refusal naming that commit rather than "not a plugin".
+     */
+    readonly revision?: string | undefined;
+}
+
 /** Maximum UTF-8 JSON size of one plugin app-data live change. */
 export declare const KAY_APP_DATA_CHANGE_MAX_BYTES: number;
 
@@ -1973,7 +2031,13 @@ 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", "0.11.0", "0.11.1", "0.12.0", "0.12.1", "0.12.2", "0.12.3", "0.12.4", "0.12.5", "0.13.0", "0.13.1", "0.13.2", "0.13.3"];
+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", "0.12.3", "0.12.4", "0.12.5", "0.13.0", "0.13.1", "0.13.2", "0.13.3", "0.13.4", "0.13.5"];
+
+/** The file whose presence makes a directory a plugin. A directory without one is not a plugin. */
+export declare const KAY_PLUGIN_MANIFEST_FILENAME = "kay-plugin.json";
+
+/** Manifest byte cap: a larger file is refused unread. */
+export declare const KAY_PLUGIN_MANIFEST_SIZE_CAP_BYTES: number;
 
 export declare const KAY_PLUGIN_PROTOCOL_PACKAGE_NAME: "@bonsai/plugin-protocol";
 
@@ -2229,8 +2293,29 @@ export declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * in one call, and such a plugin reads in bounded chunks (a file handle's `read`,
  * `createReadStream`, `readLines`), which work on every 0.13 host. File calls sent to a host worker
  * that fail are also logged to the daemon log as `runtime.user-files.*` events.
+ *
+ * 0.13.5 loads a `kay.agent` or `kay.app` entrypoint's default export when the manifest's
+ * `entrypoint.export` names none, the way Pi writes extensions; a module with no default export
+ * still loads from a named `activate`. A plugin whose entrypoint has only a default
+ * export declares `^0.13.5`, so an older host, which reads only `activate`, refuses it at load
+ * instead of failing to find the export. It also renamed three published types with no aliases,
+ * a break in the authoring types that shipped in this patch: `kay-app`'s `SessionTreeEntry`
+ * became `TranscriptEntry`, and `transcript`'s `TranscriptEntry` and `TranscriptSourceEntry`
+ * became `TranscriptEntryLike` and `TranscriptSourceEntryLike`.
+ *
+ * 0.13.6 publishes the pure contracts Bonsai's own plugins took from its internal libraries, so a
+ * plugin needs less beside the SDK. A new `@bonsai/plugin-sdk/time` carries `Temporal` (the
+ * host's own instance, like `z`), `canonicalZone`, `isValidZone` and `sameZone`, and the time
+ * door's types. `kay-app` adds
+ * the `JsonSchema` and `JsonValue` schemas, `PluginAgentDefinitionPermissionRule`,
+ * `KAY_APP_DATA_SNAPSHOT_MAX_BYTES`, and the URI types `UriHelp`, `RawResource`, `UriPayload`,
+ * `UriListParams`, `UriListResult`, `UriSearchParams` and `UriSearchResult`. `kay-agent` adds
+ * `compileUriClaim`, `kay-agent/testing` adds `createTestClock`, and `transcript` adds the turn walk
+ * (`turnSegments`), the run records and the work-block and work-headline helpers. Additive: a
+ * plugin compiled against 0.13.5 never imports them. A plugin that imports one declares `^0.13.6`,
+ * so an older host refuses a directory or repository plugin at load instead of the import failing.
  */
-export declare const KAY_PLUGIN_SDK_VERSION: "0.13.4";
+export declare const KAY_PLUGIN_SDK_VERSION: "0.13.6";
 
 export declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -2354,6 +2439,7 @@ export declare const KayAgentTargetManifest: z.ZodObject<{
         }, z.core.$strict>>>;
     }, z.core.$strict>>;
     primer: z.ZodOptional<z.ZodString>;
+    onboarding: z.ZodOptional<z.ZodString>;
     prompt: z.ZodOptional<z.ZodString>;
     skillSources: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         channel: z.ZodLiteral<"installer">;
@@ -2519,6 +2605,23 @@ export declare type KayAppTargetManifest = z.infer<typeof KayAppTargetManifest>;
 
 declare type KayAppWhiteboardCapabilityOperation = Extract<WhiteboardCapabilityOperation, "discover" | "read">;
 
+/**
+ * What is worth saying about a LOADING plugin's compatibility block (an undeclared SDK range, an
+ * unmet `minKayVersion`), as `source-scan` diagnostics scoped to the root.
+ *
+ * Root-scoped on purpose: a diagnostic naming a `dir` renders as a plugin that failed to load,
+ * and this plugin loaded. Without a `dir` the note rides its source's row as ordinary text.
+ * Because nothing in it names the plugin's directory, a host that keeps only some of the plugins
+ * it scanned must derive these for the plugins it keeps, after choosing them.
+ */
+export declare function kayPluginCompatibilityAdvisories(input: {
+    readonly manifest: Pick<KayPluginManifestV1, "id" | "displayName" | "compatibility">;
+    readonly host: KayPluginHostCompatibility;
+    readonly root: string;
+    /** A plugin that ships inside Bonsai; see `KayPluginHostCompatibility.bundled`. */
+    readonly bundled?: boolean;
+}): readonly PluginLoadDiagnostic[];
+
 export declare type KayPluginCompatibilityAdvisoryCode = "sdk-range-undeclared" | "min-kay-version-unmet" | "min-kay-version-unparseable";
 
 export declare interface KayPluginCompatibilityNote<TCode extends string> {
@@ -2545,6 +2648,25 @@ export declare class KayPluginContractResolutionError extends Error {
     constructor(message: string);
 }
 
+export declare type KayPluginDirectoryVerdict = {
+    /** The plugin SDK version the compatibility step judged against; `undefined` when it was skipped. */
+    readonly hostSdkVersion: string | undefined;
+} & ({
+    readonly outcome: "not-a-plugin";
+} | {
+    readonly outcome: "refused";
+    readonly refusal: PluginLoadDiagnostic;
+    /** Notes raised before the refusal; the author still meets them once it is fixed. */
+    readonly warnings: readonly PluginLoadDiagnostic[];
+} | {
+    readonly outcome: "loads";
+    readonly manifest: KayPluginManifestV1;
+    readonly contract: ResolvedPluginContractV1;
+    readonly warnings: readonly PluginLoadDiagnostic[];
+    /** See {@link kayPluginCompatibilityAdvisories}. */
+    readonly advisories: readonly PluginLoadDiagnostic[];
+});
+
 /** The host facts a manifest's `compatibility` block is judged against. */
 export declare interface KayPluginHostCompatibility {
     /** The host's plugin protocol version, e.g. `KAY_PLUGIN_PROTOCOL_VERSION`. */
@@ -2568,6 +2690,9 @@ export declare interface KayPluginHostCompatibility {
     readonly bundled?: boolean | undefined;
 }
 
+/** The host facts of the build this package ships in, for a host whose app version is `appVersion`. */
+export declare function kayPluginHostCompatibility(appVersion: string): KayPluginHostCompatibility;
+
 export declare const KayPluginManifestV1: z.ZodObject<{
     protocol: z.ZodLiteral<"kay.plugin.v1">;
     id: z.ZodString;
@@ -2694,6 +2819,7 @@ export declare const KayPluginManifestV1: z.ZodObject<{
                     }, z.core.$strict>>>;
                 }, z.core.$strict>>;
                 primer: z.ZodOptional<z.ZodString>;
+                onboarding: z.ZodOptional<z.ZodString>;
                 prompt: z.ZodOptional<z.ZodString>;
                 skillSources: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
                     channel: z.ZodLiteral<"installer">;
@@ -2996,8 +3122,8 @@ export declare const KayPluginManifestV1: z.ZodObject<{
                 kind: z.ZodLiteral<"oauth2">;
                 exchange: z.ZodLiteral<"pkce">;
                 clientSuppliers: z.ZodArray<z.ZodEnum<{
-                    kay: "kay";
                     user: "user";
+                    kay: "kay";
                 }>>;
                 scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 displayName: z.ZodOptional<z.ZodString>;
@@ -3366,6 +3492,31 @@ export declare const KayPluginProtocolVersion: z.ZodLiteral<"kay.plugin.v1">;
 
 export declare type KayPluginProtocolVersion = z.infer<typeof KayPluginProtocolVersion>;
 
+/** What sits at a path in a plugin directory, without following a symlink at that path. */
+export declare interface KayPluginTreeEntry {
+    readonly kind: "file" | "directory" | "other";
+    readonly size: number;
+}
+
+/**
+ * Read access to one plugin directory. Every `path` is relative to the plugin directory: the
+ * manifest's own filename, or a path as the manifest declares it.
+ */
+export declare interface KayPluginTreeReader {
+    /** What is at `path`, or `undefined` when nothing is. Any other failure throws. */
+    entry(path: string): Promise<KayPluginTreeEntry | undefined>;
+    /** `path`'s contents as UTF-8. Throws when it cannot be read. */
+    readText(path: string): Promise<string>;
+    /** The plugin directory's real location (every symlink resolved), or `undefined` when unresolvable. */
+    realDirectory(): Promise<string | undefined>;
+    /**
+     * Whether `path`, with every symlink followed, lands inside `realDirectory`. A path that does not
+     * exist is judged by its nearest existing ancestor, so a missing `../x` is still outside. Never
+     * throws: a path that cannot be resolved is outside.
+     */
+    isInside(realDirectory: string, path: string): Promise<boolean>;
+}
+
 export declare const KayUiAppHostCapability: z.ZodEnum<{
     "skills.read": "skills.read";
     "automations.run": "automations.run";
@@ -3759,6 +3910,10 @@ 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", "process.spawn", "corpus.read", "signals.read", "skills.read", "tools.describe", "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"];
 
+/** Diagnostic messages carry plugin-controlled text (parse errors, module errors); bound it so a
+ *  hostile or accidental multi-megabyte error can never blow up a log line or a render surface. */
+export declare const PLUGIN_DIAGNOSTIC_MESSAGE_CAP = 300;
+
 /** The root `<svg>` attribute a tile icon declares itself with. */
 export declare const PLUGIN_ICON_SHAPE_ATTRIBUTE = "data-icon-shape";
 
@@ -3807,8 +3962,8 @@ export declare const PluginAuthManifest: z.ZodObject<{
             kind: z.ZodLiteral<"oauth2">;
             exchange: z.ZodLiteral<"pkce">;
             clientSuppliers: z.ZodArray<z.ZodEnum<{
-                kay: "kay";
                 user: "user";
+                kay: "kay";
             }>>;
             scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
             displayName: z.ZodOptional<z.ZodString>;
@@ -3918,8 +4073,8 @@ export declare const PluginAuthScheme: z.ZodDiscriminatedUnion<[z.ZodDiscriminat
     kind: z.ZodLiteral<"oauth2">;
     exchange: z.ZodLiteral<"pkce">;
     clientSuppliers: z.ZodArray<z.ZodEnum<{
-        kay: "kay";
         user: "user";
+        kay: "kay";
     }>>;
     scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
     displayName: z.ZodOptional<z.ZodString>;
@@ -4009,8 +4164,8 @@ export declare const PluginAuthService: z.ZodObject<{
         kind: z.ZodLiteral<"oauth2">;
         exchange: z.ZodLiteral<"pkce">;
         clientSuppliers: z.ZodArray<z.ZodEnum<{
-            kay: "kay";
             user: "user";
+            kay: "kay";
         }>>;
         scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
         displayName: z.ZodOptional<z.ZodString>;
@@ -5169,6 +5324,61 @@ export declare const PluginId: z.ZodString;
 
 export declare type PluginId = z.infer<typeof PluginId>;
 
+/**
+ * Why a plugin, target, or contribution is not fully loaded. A closed discriminated union: adding a
+ * failure mode means adding a `stage` member here, so no path can raise an unclassified diagnostic.
+ * Stages run in order, earliest first: `source-scan`, `manifest-parse`, `contract-resolve`,
+ * `target-load`, `cross-plugin`.
+ *
+ * Provenance is stage-dependent by construction. `source-scan`, `manifest-parse`, and
+ * `contract-resolve` fire BEFORE a trustworthy plugin id exists, so they are located by
+ * `{root, dir}` on disk (a `source-scan` failure of an unreadable ROOT has no `dir` yet). Once the
+ * manifest's id is validated, `target-load` and `cross-plugin` carry the `pluginId` instead.
+ */
+export declare type PluginLoadDiagnostic = (PluginLoadDiagnosticMessage & {
+    readonly stage: "source-scan";
+    /** The scanned root. Always present — a scan failure is always attributable to its root. */
+    readonly root: string;
+    /** The offending immediate subdirectory, when the failure is dir-scoped (oversize, unreadable
+     *  dir); absent for root-scoped failures (unreadable root, scan timeout). */
+    readonly dir?: string;
+}) | (PluginLoadDiagnosticMessage & {
+    readonly stage: "manifest-parse";
+    readonly root: string;
+    readonly dir: string;
+}) | (PluginLoadDiagnosticMessage & {
+    readonly stage: "contract-resolve";
+    readonly root: string;
+    readonly dir: string;
+}) | (PluginLoadDiagnosticMessage & {
+    readonly stage: "target-load";
+    readonly pluginId: string;
+    /** Which target failed to load — the cell whose runtime status flips to `failed`. */
+    readonly target: PluginTargetName;
+    /**
+     * Where the failing target came from, when the source knew it. The kay.agent/kay.app
+     * preparation step has the registration in hand, so it can name both the plugin AND the
+     * directory — which is what lets an item yield survive the registration being REPLACED by
+     * this diagnostic (a first enable of a plugin that throws at import).
+     */
+    readonly root?: string;
+    readonly dir?: string;
+    /** The unresolved SDK subpath, when the failure is a missing virtual-module subpath (contract
+     *  §"Module loading": name the subpath, never a bare `ERR_MODULE_NOT_FOUND`). */
+    readonly subpath?: string;
+}) | (PluginLoadDiagnosticMessage & {
+    readonly stage: "cross-plugin";
+    readonly pluginId: string;
+});
+
+/** The message payload every diagnostic carries regardless of stage. */
+declare interface PluginLoadDiagnosticMessage {
+    /** A short, stable slug for the failure class (e.g. `"oversize-manifest"`, `"id-collision"`). */
+    readonly code: string;
+    /** Human-facing detail; length-bounded and escaped at its render surface, never trusted markup. */
+    readonly message: string;
+}
+
 export declare const PluginNamespace: z.ZodString;
 
 export declare type PluginNamespace = z.infer<typeof PluginNamespace>;
@@ -5211,8 +5421,8 @@ export declare type PluginNotificationRuleContribution = z.infer<typeof PluginNo
  * literal values are re-declared here, not aliased; a herd↔protocol parity test pins them equal.
  */
 export declare const PluginOAuthClientSupplier: z.ZodEnum<{
-    kay: "kay";
     user: "user";
+    kay: "kay";
 }>;
 
 export declare type PluginOAuthClientSupplier = z.infer<typeof PluginOAuthClientSupplier>;
@@ -5799,6 +6009,15 @@ export declare const RegistrableDomain: z.ZodString;
 
 export declare type RegistrableDomain = z.infer<typeof RegistrableDomain>;
 
+/**
+ * Id namespaces a directory plugin may never claim. `herd.` is the kernel's first-party namespace
+ * (`HERD_RESERVED_ID_PREFIX`: the kernel's extension loader throws on it without a first-party
+ * opt-in) and `kay.` is the product's bundled and app-extension namespace. Refusing them here keeps
+ * a reserved id from reaching either kernel throw, which would abort a whole extension batch and
+ * drop every sibling plugin with it.
+ */
+export declare const RESERVED_DIRECTORY_PLUGIN_ID_PREFIXES: readonly ["herd.", "kay."];
+
 /**
  * Resolves the runtime selection key for a provider-shaped contribution — the
  * value an *adapter binding* names to make one implementation live.
@@ -6127,8 +6346,8 @@ export declare type ResolvedKayUiAppEndpointCapability = z.infer<typeof Resolved
 export declare const ResolvedPluginAuthScheme: z.ZodDiscriminatedUnion<[z.ZodDiscriminatedUnion<[z.ZodObject<{
     exchange: z.ZodLiteral<"pkce">;
     clientSuppliers: z.ZodArray<z.ZodEnum<{
-        kay: "kay";
         user: "user";
+        kay: "kay";
     }>>;
     localId: z.ZodString;
     globalId: z.ZodString;
@@ -6234,8 +6453,8 @@ export declare const ResolvedPluginAuthService: z.ZodObject<{
     schemes: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodDiscriminatedUnion<[z.ZodObject<{
         exchange: z.ZodLiteral<"pkce">;
         clientSuppliers: z.ZodArray<z.ZodEnum<{
-            kay: "kay";
             user: "user";
+            kay: "kay";
         }>>;
         localId: z.ZodString;
         globalId: z.ZodString;
@@ -6403,8 +6622,8 @@ export declare const ResolvedPluginContractV1: z.ZodObject<{
         schemes: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodDiscriminatedUnion<[z.ZodObject<{
             exchange: z.ZodLiteral<"pkce">;
             clientSuppliers: z.ZodArray<z.ZodEnum<{
-                kay: "kay";
                 user: "user";
+                kay: "kay";
             }>>;
             localId: z.ZodString;
             globalId: z.ZodString;
@@ -7713,6 +7932,7 @@ export declare const SessionCausedByEvent: z.ZodObject<{
             "turn-settled": "turn-settled";
             "phase-shift": "phase-shift";
             "human-message": "human-message";
+            "assistant-message": "assistant-message";
             "ui-action": "ui-action";
         }>;
         entryId: z.ZodString;
@@ -7937,6 +8157,7 @@ export declare const SessionProvenanceRecord: z.ZodObject<{
                 "turn-settled": "turn-settled";
                 "phase-shift": "phase-shift";
                 "human-message": "human-message";
+                "assistant-message": "assistant-message";
                 "ui-action": "ui-action";
             }>;
             entryId: z.ZodString;