@yaklabs-ai/plugin-sdk 0.15.3 → 0.26.3

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

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 
 /**
- * Who a connected account *belongs to* — the human, as the provider reports them. Derived at connect
+ * Who a connected account *belongs to* - the human, as the provider reports them. Derived at connect
  * time by a scheme's `resolveAccountId` hook from the provider's own profile endpoint, and surfaced
  * to the agent so it never has to ask "what is your email?" for a service the user already
  * connected.
@@ -9,7 +9,7 @@ import { z } from 'zod';
  * Distinct from {@link AccountProvenance}: an account can be firmly identified
  * (`externalId`/`provider`) while nothing is known about its owner, and a workspace's name is not a
  * person's name. Field-for-field the same shape the credential authority persists, so identity
- * crosses the daemon⇄kernel boundary without a lossy projection.
+ * crosses the daemon<->kernel boundary without a lossy projection.
  */
 declare interface AccountIdentity {
     /** Provider handle (GitHub `login`, Slack `user`). */
@@ -28,7 +28,7 @@ declare interface AccountIdentity {
     /**
      * Provider-native session id claim (WorkOS's `sid`), needed to call the provider's own
      * session-revocation endpoint at sign-out (`POST /user_management/sessions/revoke`, not yet
-     * wired — see `docs/kay-account-auth.md`'s "Sign-out guarantee" section). Only Bonsai's WorkOS
+     * wired - see `docs/kay-account-auth.md`'s "Sign-out guarantee" section). Only Bonsai's WorkOS
      * product-account exchange/refresh sets it; every other provider leaves it absent.
      */
     readonly providerSessionId?: string;
@@ -36,7 +36,7 @@ declare interface AccountIdentity {
 
 /**
  * Structured, non-secret *provenance* for a connected account: which record on the provider's side
- * this credential points at. Says nothing about the human — a Notion `displayName` here is the
+ * this credential points at. Says nothing about the human - a Notion `displayName` here is the
  * workspace name, a Slack one is the team name. To describe the person, see {@link AccountIdentity}.
  */
 declare interface AccountProvenance {
@@ -50,6 +50,17 @@ declare interface AccountProvenance {
     readonly raw?: Readonly<Record<string, unknown>>;
 }
 
+declare const AdapterPlacement: z.ZodEnum<{
+    "local-only": "local-only";
+    anywhere: "anywhere";
+}>;
+
+declare type AdapterPlacement = z.infer<typeof AdapterPlacement>;
+
+declare const AdapterSelectionKey: z.ZodString;
+
+declare type AdapterSelectionKey = z.infer<typeof AdapterSelectionKey>;
+
 /** Applies an AddImmutable action to a type. */
 declare function AddImmutable<Type extends TSchema>(type: Type, options?: TSchemaOptions): TAddImmutable<Type>;
 
@@ -146,21 +157,6 @@ declare function Any(options?: TSchemaOptions): TAny;
 
 declare type Api = KnownApi | (string & {});
 
-/** One labeled secret input of a multi-field api-key scheme. */
-declare interface ApiKeyAuthSchemeField {
-    /** Stable key — the `fields` Record key on the stored material and resolved credential. */
-    readonly id: string;
-    /** Per-field prompt copy, e.g. "Access Client ID". */
-    readonly label: string;
-}
-
-/** Provider-owned instructions for creating a credential outside Bonsai. */
-declare interface ApiKeyAuthSchemeSetup {
-    readonly instructions: string;
-    /** Absolute HTTPS page where the user can create or manage the credential. */
-    readonly url: string;
-}
-
 /** One non-secret capability observation made while validating a credential. */
 declare interface ApiKeyCapabilityCheck {
     /** Stable service capability id the scheme checked. */
@@ -178,13 +174,17 @@ declare function _Array_<Type extends TSchema>(items: Type, options?: TArrayOpti
 /** Extracts options from a TArray. */
 declare function ArrayOptions(type: TArray): TArrayOptions;
 
+declare const ArtifactGenerationId: z.core.$ZodBranded<z.ZodString, "ArtifactGenerationId", "out">;
+
+declare type ArtifactGenerationId = z.infer<typeof ArtifactGenerationId>;
+
 /**
  * Performs an Object assign using the Left and Right object types. We track this operation as it
  * creates a new GC handle per assignment.
  */
 declare function Assign<Left extends ObjectLike, Right extends ObjectLike>(left: Left, right: Right): TAssign<Left, Right>;
 
-/** A connected account under one `(serviceId, schemeId)` — the multi-account unit. */
+/** A connected account under one `(serviceId, schemeId)` - the multi-account unit. */
 declare interface AuthAccount {
     readonly accountId: string;
     readonly displayName: string;
@@ -199,12 +199,66 @@ declare interface AuthAccount {
     /**
      * Trust-lost marker carried through from `StoredCredentialSummary.needsReconnect`
      * (kay#7852): the account's credential is dead (revoked or terminally unrefreshable) and the
-     * user must reconnect it. The account stays listed — with this flag — so the agent can see it
+     * user must reconnect it. The account stays listed - with this flag - so the agent can see it
      * and point the user at a reconnect; token resolution for it still fails closed.
      */
     readonly needsReconnect?: boolean;
 }
 
+declare namespace authoringCommonSchemas {
+    export {
+        hostWithinDomain,
+        urlHostWithinDomain,
+        refineWebSessionScopeConfined,
+        KAY_PLUGIN_PROTOCOL_VERSION,
+        KAY_PLUGIN_PROTOCOL_PACKAGE_NAME,
+        KAY_PLUGIN_SDK_VERSION,
+        KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS,
+        KAY_PLUGIN_TARGET_NAMES,
+        KayPluginProtocolVersion,
+        PluginTargetName,
+        KAY_EVENT_PUBLISHER_ID,
+        NonEmptyString,
+        PluginId,
+        PluginNamespace,
+        LocalContributionId,
+        GlobalContributionId,
+        PluginToolName,
+        AuthServiceReference,
+        AuthSchemeReference,
+        AdapterSelectionKey,
+        AdapterPlacement,
+        UriScheme,
+        MimeTypeString,
+        FileExtensionToken,
+        CliBinaryName,
+        CliAuthEnvVarName,
+        PackageAssetPath,
+        PluginSourceClass,
+        ArtifactGenerationId,
+        HttpsUrl,
+        RegistrableDomain,
+        GitHostName,
+        GitBasicAuthUser,
+        HttpStatusCode,
+        SignedInStatusCode,
+        JsonPointer,
+        TargetEntrypoint,
+        canonicalCommonSchemas,
+        JsonObject,
+        JsonSchema_2 as JsonSchema,
+        JsonValue_2 as JsonValue
+    }
+}
+
+declare const AuthSchemeReference: z.ZodString;
+
+declare type AuthSchemeReference = z.infer<typeof AuthSchemeReference>;
+
+declare const AuthServiceReference: z.ZodString;
+
+declare type AuthServiceReference = z.infer<typeof AuthServiceReference>;
+
 declare interface Availability {
     readonly available: boolean;
     readonly reason?: string;
@@ -256,7 +310,7 @@ declare type BackgroundTaskRun = (ctx: BackgroundTaskRunContext) => Promise<stri
 declare interface BackgroundTaskRunContext {
     readonly taskId: string;
     readonly signal: AbortSignal;
-    /** `this: void` — task bodies destructure this reporter off the context. */
+    /** `this: void` - task bodies destructure this reporter off the context. */
     reportProgress(this: void, text: string, details?: Record<string, unknown>): void;
 }
 
@@ -320,6 +374,47 @@ declare function Call<Target extends TSchema, Arguments extends TSchema[]>(targe
 
 declare function CallConstruct<Target extends TSchema, Arguments extends TSchema[]>(target: Target, arguments_: [...Arguments]): TCallConstruct<Target, Arguments>;
 
+declare const canonicalCommonSchemas: {
+    NonEmptyString: z.ZodString;
+    PluginId: z.ZodString;
+    PluginNamespace: z.ZodString;
+    LocalContributionId: z.ZodString;
+    GlobalContributionId: z.ZodString;
+    PluginToolName: z.ZodString;
+    AuthServiceReference: z.ZodString;
+    AuthSchemeReference: z.ZodString;
+    AdapterSelectionKey: z.ZodString;
+    AdapterPlacement: z.ZodEnum<{
+        "local-only": "local-only";
+        anywhere: "anywhere";
+    }>;
+    UriScheme: z.ZodString;
+    MimeTypeString: z.ZodString;
+    FileExtensionToken: z.ZodString;
+    CliBinaryName: z.ZodString;
+    CliAuthEnvVarName: z.ZodString;
+    PackageAssetPath: z.ZodString;
+    PluginSourceClass: z.ZodEnum<{
+        bundled: "bundled";
+        "org-shared": "org-shared";
+        "user-local": "user-local";
+        "verified-marketplace": "verified-marketplace";
+        freeform: "freeform";
+    }>;
+    ArtifactGenerationId: z.core.$ZodBranded<z.ZodString, "ArtifactGenerationId", "out">;
+    HttpsUrl: z.ZodURL;
+    RegistrableDomain: z.ZodString;
+    GitHostName: z.ZodString;
+    GitBasicAuthUser: z.ZodString;
+    HttpStatusCode: z.ZodNumber;
+    SignedInStatusCode: z.ZodNumber;
+    JsonPointer: z.ZodString;
+    TargetEntrypoint: z.ZodObject<{
+        module: z.ZodString;
+        export: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+};
+
 /** Applies a Capitalize action to the given type. */
 declare function Capitalize_2<Type extends TSchema>(type: Type, options?: TSchemaOptions): TCapitalize<Type>;
 
@@ -353,6 +448,14 @@ declare namespace Char {
     }
 }
 
+declare const CliAuthEnvVarName: z.ZodString;
+
+declare type CliAuthEnvVarName = z.infer<typeof CliAuthEnvVarName>;
+
+declare const CliBinaryName: z.ZodString;
+
+declare type CliBinaryName = z.infer<typeof CliBinaryName>;
+
 /**
  * Returns a Clone of the given value. This function is similar to structuredClone()
  * but also supports deep cloning instances of Map, Set and TypeArray.
@@ -414,7 +517,13 @@ declare interface ContentConverter {
      */
     readonly description?: string;
     matches(probe: ContentProbe): boolean;
-    convert(bytes: Uint8Array, probe: ContentProbe, ctx: ConvertContext): Promise<ConversionResult>;
+    /**
+     * Converts the file `matches` claimed. Resolves `undefined` to decline it after all: the read
+     * pipeline then tries the next converter that claimed it, as if this one had not. A converter
+     * that answers elsewhere (the plugin host's stand-in, which learns only there which converter
+     * takes the file) declines this way; one that decides in `matches` never needs to.
+     */
+    convert(bytes: Uint8Array, probe: ContentProbe, ctx: ConvertContext): Promise<ConversionResult | undefined>;
 }
 
 /**
@@ -438,7 +547,7 @@ declare interface ContentProbe {
 
 /**
  * The convert return shape. `content` is the agent-facing
- * {@link ModelContent} — text and/or image blocks — and is
+ * {@link ModelContent} - text and/or image blocks - and is
  * the field the read pipeline consumes (finalize windows/truncates TEXT blocks and
  * passes IMAGE blocks through unchanged). `contentType`/`artifacts`/`structure`/
  * `notes` are reserved metadata that no consumer renders yet. The converter does
@@ -615,7 +724,7 @@ declare function Deferred<Action extends string, Types extends TSchema[]>(action
  * What `service_connect` hands a delegated scheme's {@link DelegatedAuthScheme.connect}: the
  * scope being connected plus the host's browser-redirect capability when one is configured.
  * `authorize`/`redirectUri` wrap the host `OAuthRedirectTransport` (`@herd/herd-agent`)
- * — both absent when the host has none; the scheme decides whether it needs them.
+ * - both absent when the host has none; the scheme decides whether it needs them.
  */
 declare interface DelegatedConnectContext {
     readonly serviceId: string;
@@ -648,7 +757,7 @@ declare interface DelegatedConnectResult {
 /**
  * Token material minted by a delegated scheme's extension-provided flow. Core reads only
  * `accessToken`/`expiresAt` (resolution + proactive refresh); `data` is an opaque blob the
- * scheme round-trips through `refresh` (refresh token, DCR client info, …) — never read by core.
+ * scheme round-trips through `refresh` (refresh token, DCR client info, ...) - never read by core.
  */
 declare interface DelegatedSecretMaterial {
     readonly kind: "delegated";
@@ -674,7 +783,7 @@ declare function DependentOptions(type: TDependent): TSchemaOptions;
  * can derive per-call via {@link ToolPermissionHint.deriveClassification}. Every field is
  * optional: a present field overrides the static hint for that call; an absent field falls back
  * to the static hint (then to the fail-closed default). `resources` stays a separate deriver
- * ({@link ToolPermissionHint.deriveResources}) — these are the fields that decide which rule a
+ * ({@link ToolPermissionHint.deriveResources}) - these are the fields that decide which rule a
  * call matches, not the paths it touches.
  */
 declare interface DerivedToolClassification {
@@ -683,6 +792,13 @@ declare interface DerivedToolClassification {
     readonly scheme?: string;
 }
 
+/**
+ * The definition the host builds for the tool `contract` describes under `localId`, running
+ * `execute`: name, parameters, auth binding and permission all come from the manifest, as in a
+ * session.
+ */
+export declare function describedToolForTest(contract: ResolvedPluginContractV1, localId: string, execute: KayAgentToolExecute): ToolDefinition;
+
 declare const Digit: TDigit;
 
 /** Discards multiple property keys from the given object value */
@@ -834,18 +950,19 @@ declare function ExtendsTrue<Inferred extends TProperties>(inferred: TProperties
 declare function ExtendsUnion<Inferred extends TProperties>(inferred: TProperties): TExtendsUnion<Inferred>;
 
 /**
- * The execute-time auth surface the SDK wrappers read off `ctx.auth`. Slice 3 attaches a
- * concrete implementation (vault + pkce refresh + active-account store) to ExtensionContext;
- * defining the contract here lets the wrappers compile and be unit-tested against a double.
+ * The auth resolver: the host resolves a capability's credential through it before calling the
+ * capability, and an extension's event handlers read it off `ctx.auth`. Tools, URI verbs and search
+ * providers never see it; they receive the {@link ResolvedCredential} the host resolved.
  */
 declare interface ExtensionAuthContext {
     /**
      * Resolve a live token for a service and an account: the explicit `accountId` when given, else
-     * the session-active account. `schemeId` is a preference, not an address — an explicit account
+     * the session-active account. `schemeId` is a preference, not an address - an explicit account
      * resolves against its OWN backing scheme even when a different scheme is named/bound, and an
      * absent `schemeId` resolves service-level across the injectable schemes. Refreshes oauth near
      * expiry under the hood. Returns an actionable {@link ResolveTokenFailure} (never throws) when
-     * there is no connection or the account is ambiguous, so wrappers can short-circuit gracefully.
+     * there is no connection or the account is ambiguous, which the host answers with instead of
+     * calling the capability.
      */
     readonly resolveToken: (input: {
         readonly serviceId: string;
@@ -854,7 +971,7 @@ declare interface ExtensionAuthContext {
         /**
          * The invoking capability's `requiresAuth.requiredScopes`, threaded down to the vault load so a
          * grant-enforcing vault can refuse a plugin whose granted scopes don't cover them. The
-         * caller identity itself is not a per-call argument — it is fixed by the owner-scoped context
+         * caller identity itself is not a per-call argument - it is fixed by the owner-scoped context
          * (see `CreateExtensionAuthContextInput.callerId`).
          */
         readonly requiredScopes?: readonly string[];
@@ -906,7 +1023,7 @@ declare interface ExtensionBackgroundTasksApi {
 
 /**
  * Host-provided, per-extension writable data root surfaced on {@link ToolContext.paths}. Isolation is
- * the DIRECTORY itself — exactly like the per-extension SQLite db files keyed by extension id: the host
+ * the DIRECTORY itself - exactly like the per-extension SQLite db files keyed by extension id: the host
  * provisions a distinct path per owning extension, the extension owns everything inside it. The kernel
  * never decides *where* this lives; it carries an opaque host-resolved path and exposes it, so an
  * extension can read/write files (caches, scratch state, downloads) under a sanctioned root without the
@@ -1051,18 +1168,22 @@ declare function FactorMapping(input: [unknown, unknown, unknown, unknown, unkno
  * A default-permissive {@link ExtensionAuthContext} double: every method resolves
  * to a benign "not connected" outcome unless overridden. Kernel test fixtures that
  * need real account-selection semantics (active/sole/ambiguous account picking) or
- * call-recording pass their own `resolveToken`/`listAccounts`/etc via `overrides` —
+ * call-recording pass their own `resolveToken`/`listAccounts`/etc via `overrides` -
  * this owns only the four-method boilerplate shell that four kernel test files
  * used to hand-roll independently (see `extensions-auth-sdk.test.ts`'s `stubAuth`,
  * the double this was derived from).
  */
 export declare function fauxAuthContext(overrides?: Partial<ExtensionAuthContext>): ExtensionAuthContext;
 
-/** The capability handles a `KayAgentPluginApi` always carries — authority is decided per call. */
-export declare type FauxKayAgentCapabilities = Pick<KayAgentPluginApi, "network" | "webSession" | "process" | "whiteboard" | "interaction" | "interceptToolCall" | "systemOne" | "events" | "time" | "userFiles" | "familyFolder">;
+/** The capability handles a `KayAgentPluginApi` always carries - authority is decided per call. */
+export declare type FauxKayAgentCapabilities = Pick<KayAgentPluginApi, "network" | "webSession" | "process" | "whiteboard" | "interaction" | "interceptToolCall" | "implementTool" | "systemOne" | "events" | "time" | "log" | "userFiles" | "familyFolder" | "vendoredMcp" | "endpoints" | "compiler">;
 
 export declare function fauxKayAgentCapabilities(): FauxKayAgentCapabilities;
 
+declare const FileExtensionToken: z.ZodString;
+
+declare type FileExtensionToken = z.infer<typeof FileExtensionToken>;
+
 declare type ForecastInterval = "step" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year";
 
 /** Creates a Function type. */
@@ -1126,6 +1247,36 @@ declare const GenericType: (input: string) => [unknown, string] | [];
 
 declare function GenericTypeMapping(input: [unknown, unknown, unknown]): unknown;
 
+declare const GitBasicAuthUser: z.ZodString;
+
+declare type GitBasicAuthUser = z.infer<typeof GitBasicAuthUser>;
+
+declare const GitHostName: z.ZodString;
+
+declare type GitHostName = z.infer<typeof GitHostName>;
+
+declare const GlobalContributionId: z.ZodString;
+
+declare type GlobalContributionId = z.infer<typeof GlobalContributionId>;
+
+/**
+ * The cookie suffix rule shared by every web-session boundary: whether `host`
+ * is `domain` or a subdomain of it. Coined ONCE here - the manifest's scope
+ * confinement, the resolved/wire re-checks, and the desktop probe's
+ * redirect-landing classification must all agree on it, or a login bounce
+ * inside the declared scope could read as "unknown" on one side of a seam and
+ * "signed-out" on the other.
+ */
+declare function hostWithinDomain(host: string, domain: string): boolean;
+
+declare const HttpStatusCode: z.ZodNumber;
+
+declare type HttpStatusCode = z.infer<typeof HttpStatusCode>;
+
+declare const HttpsUrl: z.ZodURL;
+
+declare type HttpsUrl = z.infer<typeof HttpsUrl>;
+
 declare const Hyphen = "-";
 
 /** Matches if next is an Ident */
@@ -1134,13 +1285,6 @@ declare function Ident<Input extends string>(input: Input): TIdent<Input>;
 /** Creates an Identifier. */
 declare function Identifier<Name extends string>(name: Name): TIdentifier<Name>;
 
-/**
- * Whether a scheme acts *as the user* (the fully-built PKCE path) or *on behalf of the user
- * as an app* (a declared seam — see {@link OAuthPkceAuthScheme.mintToken}). It's a property of
- * the scheme, not the call, so the resolver knows the identity without per-call ambiguity.
- */
-declare type IdentityMode = "as-user" | "on-behalf-of-app";
-
 declare interface ImageContent {
     type: "image";
     data: string;
@@ -1270,6 +1414,12 @@ declare interface InteractionCandidate {
     readonly checked?: string | undefined;
     readonly selected?: string | undefined;
     readonly expanded?: string | undefined;
+    /**
+     * What a page driver found the element to be in the DOM, not what the page calls it: `link` is an
+     * anchor that navigates to another http(s) page; `widget` is an element that is no form control.
+     * Absent means unknown, and the engine then treats the element as any other.
+     */
+    readonly look?: "link" | "widget" | undefined;
     readonly delta?: number | undefined;
     /** Where an element outside the visible area sits; absent means on screen. */
     readonly position?: "above" | "below" | "beside" | undefined;
@@ -1445,18 +1595,18 @@ declare class InvalidLiteralValue extends Error {
 
 /**
  * Invoke a plugin tool definition's `execute` in a test, owning the **one sanctioned cast** past
- * `ToolExecutionAwareParams<unknown>` — the phantom-wire-shaped type every `ToolDefinition`'s
+ * `ToolExecutionAwareParams<unknown>` - the phantom-wire-shaped type every `ToolDefinition`'s
  * `execute` resolves to once auth-gated by `withResolvedAuth` (whose synthesized `execute` does not
  * go through `defineTool`'s `PluginToolDefinition` -> `InferToolInput` mapping, so there is no
- * zod-inferred params type to type-check `params` against at the call site — see decision 002's
+ * zod-inferred params type to type-check `params` against at the call site - see decision 002's
  * problem statement). `tool` is typed `ToolDefinition<any, TDetails>`, the same
  * accept-any-params-shape idiom the kernel itself uses for generic tool-definition plumbing
- * (`core/tools/execution-policy.ts`, `core/tools/tool-definition-wrapper.ts`) — the `any` is this
+ * (`core/tools/execution-policy.ts`, `core/tools/tool-definition-wrapper.ts`) - the `any` is this
  * function's entire reason to exist, not a shortcut taken to avoid one.
  *
- * Fixes `toolCallId` to `"test-call"`, `signal` to `undefined`, and `onUpdate` to `undefined` —
+ * Fixes `toolCallId` to `"test-call"`, `signal` to `undefined`, and `onUpdate` to `undefined` -
  * the values every fixture invocation wants and no fal-style test had a reason to vary. Pass a
- * `ctx` (with `auth: fauxAuthContext(...)` for an auth-gated tool) to exercise anything beyond the
+ * `ctx` (with a `credential` for an auth-gated tool) to exercise anything beyond the
  * happy-path default.
  */
 export declare function invokeToolForTest<TDetails = unknown>(tool: ToolDefinition<any, TDetails>, params: Record<string, unknown>, ctx?: ToolContext): Promise<AgentToolResult<TDetails>>;
@@ -1620,10 +1770,22 @@ declare function IsUnsafe(value: unknown): value is TUnsafe;
 /** Returns true if the given value is TVoid. */
 declare function IsVoid(value: unknown): value is TVoid;
 
+declare const JsonObject: z.ZodRecord<z.ZodString, z.ZodType<JsonValue_2, unknown, z.core.$ZodTypeInternals<JsonValue_2, unknown>>>;
+
+declare type JsonObject = z.infer<typeof JsonObject>;
+
+declare const JsonPointer: z.ZodString;
+
+declare type JsonPointer = z.infer<typeof JsonPointer>;
+
 declare type JsonPrimitive = string | number | boolean | null;
 
 declare type JsonSchema = Record<string, unknown>;
 
+declare const JsonSchema_2: z.ZodRecord<z.ZodString, z.ZodType<JsonValue_2, unknown, z.core.$ZodTypeInternals<JsonValue_2, unknown>>>;
+
+declare type JsonSchema_2 = z.infer<typeof JsonSchema_2>;
+
 declare type JsonValue = JsonPrimitive | {
     readonly [key: string]: JsonValue;
 } | readonly JsonValue[];
@@ -1638,6 +1800,627 @@ declare type JsonValue_3 = null | boolean | number | string | JsonValue_3[] | {
     [key: string]: JsonValue_3;
 };
 
+/**
+ * The publisher id Bonsai's own subsystems publish declared events under (skill
+ * changes, wallet notices, automation failures). A notification rule matches a
+ * declared event by (publisher id, event local id), so no plugin may take this
+ * id or it could publish events that Bonsai's default rules read as Bonsai's own.
+ */
+declare const KAY_EVENT_PUBLISHER_ID: "kay";
+
+/** Released SDK contracts still implemented by the host, alongside its current SDK. */
+declare const KAY_PLUGIN_COMPATIBLE_SDK_VERSIONS: readonly string[];
+
+declare const KAY_PLUGIN_PROTOCOL_PACKAGE_NAME: "@bonsai/plugin-protocol";
+
+declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
+
+/**
+ * The plugin SDK version this host ships, and the number a plugin's
+ * `compatibility.sdk` range is matched against.
+ *
+ * -- Why this is the compatibility axis, and the app version is not ----------
+ * A plugin never bundles the SDK: the host injects its own `@bonsai/plugin-sdk`
+ * dist at import time. So the SDK surface a plugin was written against is the
+ * thing that can break under it, and the Bonsai app version is only correlated
+ * with that - it moves for reasons a plugin cannot observe.
+ *
+ * -- Two lines, deliberately, not one ----------------------------------------
+ * This continues the published `@yaklabs-ai/plugin-sdk` line, currently in 0.x.
+ * `KAY_UI_SDK_VERSION` in `@bonsai/protocol` is a SEPARATE line at its own number,
+ * and the two are never compared: a `kay.ui` app package declares against the
+ * UI SDK, a plugin manifest declares `compatibility.sdk` against this one, and
+ * no manifest field takes both. Unifying them would have to publish the plugin
+ * SDK at the UI line's 1.x, claiming a stability this surface does not have -
+ * 0.x says "breaking minors" honestly, which is the truth pre-product.
+ *
+ * -- Bumping it --------------------------------------------------------------
+ * A protocol or SDK surface break bumps this constant IN THE SAME PR, and
+ * `scripts/check-sdk-release-due.mjs` then reports a release due at the new
+ * number. The constant is the declared version, not a derived one: the release
+ * publishes exactly what is written here.
+ *
+ * An ADDITION takes the patch slot, not the minor. Under 0.x npm's caret makes
+ * the minor the breaking slot, so a minor bump refuses
+ * (`sdk-range-unsatisfied`) every plugin still declaring the previous one - a
+ * fleet-wide break, never the price of one new entrypoint. 0.7.1 carried the
+ * additive `@bonsai/plugin-sdk/phase-shift` surface that way, while `^0.7.0`
+ * plugins kept loading.
+ *
+ * 0.8.0 IS that fleet-wide break, deliberately, and it spends the one break on
+ * two changes at once.
+ *
+ * FIRST, a plugin no longer declares the capabilities it wants, because the
+ * CALL is the ask. Every capability ask left `permissions.byTarget` (an
+ * installed manifest that still carries one is stripped with a
+ * `retired-permission-ask` diagnostic, never refused - the same law
+ * `RETIRED_COMPATIBILITY_KEYS` follows), every brokered capability object is
+ * unconditionally present on the SDK surface (presence is no longer a grant
+ * signal to feature-detect), and authority is one exact claim checked against
+ * the user's grant ledger at the call.
+ *
+ * SECOND, `app.hindsight` (`KayAppHindsight` - lane registration, the lane
+ * event, the lane context, and the followup DTOs) is DELETED, along with the
+ * daemon-side lane dispatcher it registered onto. Its replacement is two
+ * generic doors a plugin composes itself, `app.sessionEvents.subscribe` and
+ * `app.agents.run`, and their authority is two claims in the same ledger
+ * (`session-events.subscribe`, `agents.run`). There is no shim, because a shim
+ * would have to fake a dispatcher that no longer exists.
+ *
+ * Either half alone breaks a `^0.7` plugin: the TYPE surface it compiles
+ * against moved under it - the ask keys are gone from the manifest type, the
+ * capability objects are required rather than optional, and the hindsight door
+ * is gone - which is what the minor bump signals. A plugin declaring `^0.7` is
+ * refused (`sdk-range-unsatisfied`) rather than loaded against a contract it
+ * was not written to.
+ *
+ * 0.8.1 takes the PATCH slot under the addition rule above: `api.withJev`
+ * (`@bonsai/plugin-sdk/jev`) - Jev typed-decision inference with a required
+ * fallback - is one new member on an api a plugin RECEIVES. A `^0.8.0` plugin
+ * keeps loading and keeps compiling; it simply never reaches for the member.
+ * The member is non-optional for the same reason 0.8.0 made every brokered
+ * capability unconditional: presence is not a grant signal, and an optional one
+ * would invite the feature-detect branch that skips the required fallback.
+ *
+ * 0.8.2 adds the received Whiteboard handles, type contributions, and session
+ * app-data readers. Existing 0.8 plugins keep loading without using them.
+ *
+ * 0.8.3 adds the recorded Jev signal reads, `app.signals.list` and
+ * `app.signals.listDetectors`, behind the new `signals.read` claim. It is also
+ * the first number that guarantees `app.signals.observe`, which reached hosts
+ * still advertising 0.8.2. A plugin that reads signals declares `^0.8.3`, so an
+ * older host refuses it at load instead of failing at the call. 0.8.3's
+ * `observe` also answers `invalid`, recording nothing, for a detector id,
+ * version, question name, choice label, or source id outside the recorded-name
+ * grammar (`invalidObservation` in `@bonsai/plugin-sdk/signals`): names a reader
+ * could not later address, filter on, or copy back. A 0.8.2 host recorded such
+ * names, so a plugin moving to 0.8.3 checks its names against that grammar.
+ *
+ * 0.8.4 adds `api.events` on `kay.agent` (publish a declared event from agent
+ * code, host-stamped with the session) and the `kay.app` manifest key
+ * `notificationRules` (default notification rules for a plugin's own events).
+ * Both are additions: a `^0.8` plugin keeps loading. The manifest key is new
+ * schema, so an older host refuses a manifest that uses it at parse. `api.events`
+ * carries no such schema backstop - it is a call, not a manifest field - so a
+ * plugin that calls it, or declares `notificationRules`, declares `^0.8.4`: a
+ * host still advertising 0.8.3 (signals only, landed separately) refuses it at
+ * load instead of failing at the call.
+ *
+ * 0.8.5 republishes `@yaklabs-ai/plugin-sdk` to include the `./jev` and
+ * `./signals` entrypoints: the workspace package has exported them since 0.8.1
+ * (`jev`) and 0.8.3 (`signals`), but `scripts/build-publishable-packages.mjs`'s
+ * hand-maintained `entrypoints` allowlist had omitted both. This packages
+ * EXISTING apis; the type contract does not change. It still takes the patch
+ * 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.
+ *
+ * 0.9.0 adds timer_cancelled and requires workflow descriptions and summary
+ * returns. This is an authoring-type break only: the host retains the 0.8
+ * runtime contracts.
+ *
+ * 0.9.1 adds bounded corpus invocation reads (`app.corpus.listResourceInvocations`).
+ * Existing received APIs are unchanged, so this is additive only.
+ *
+ * 0.10.0 removes the `spawn-session` variant from `KayAppAutomationEffectInput`
+ * (and its daemon-facing mirror, `KayAutomationEffectInput`): an agent or
+ * plugin can no longer create a spawn-session automation binding (owner
+ * ruling, 2026-09-28) - durable recurring agent work is a plugin workflow
+ * (`app.workflows.define` + `ctx.runAgent`) or a direct `session/run`. A
+ * binding created before this version, or by daemon-internal code, still
+ * stores and reads the effect fine (`KayAppAutomationEffect` keeps it); only
+ * the create-time input type is narrower. Mostly an authoring-type break -
+ * 0.9.0 and 0.9.1 stay in the runtime-contract retention list below, so a
+ * plugin still running bytecode compiled against either keeps loading and
+ * working - except for the one call this ruling actually closes:
+ * `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 Bonsai's own `JevClient` (`@bonsai/plugin-sdk/jev`): one method,
+ * `classify({state, questions})`, in Bonsai'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.
+ *
+ * 0.12.4 adds `app.repos` (`KayAppRepos`): `resolve(folder)` answers which git checkout encloses a
+ * folder (repo root, primary checkout, common dir, remotes, origin), and `linkedWorktrees(commonDir)`
+ * lists git's linked-worktree registry, both read by the host asynchronously under a time limit and
+ * answering `unknown` rather than throwing. Always present and ungated, like `app.paths`. Additive:
+ * a plugin compiled against 0.12.3 never reads it. A plugin that calls it declares `^0.12.4`, so an
+ * older host refuses a directory or repository plugin at load instead of the call failing.
+ *
+ * 0.12.5 adds `userFiles` (`KayAppUserFiles`) on both `app` and the `kay.agent` api: stat, read,
+ * list, walk, realpath, write, mkdir and rename in user folders, run by the host on its own worker
+ * threads under a deadline and answering a typed result rather than throwing. Always present and
+ * ungated, like `app.paths`. Additive: a plugin compiled against 0.12.4 never reads it. A plugin
+ * that calls it declares `^0.12.5`, so an older host refuses a directory or repository plugin at
+ * load instead of the call failing.
+ *
+ * 0.13.0 adds `@bonsai/plugin-sdk/fs`, Bonsai's own `node:fs/promises`: the same functions, arguments,
+ * return types and errors, with every call run on the host's user-files workers under a deadline
+ * (`ERR_KAY_FS_DEADLINE` and siblings when the host gives up or does not try), plus
+ * `writeFileAtomic` and `withTimeout`. With no host installed it is Node's own module. It adds
+ * `api.familyFolder` (`KayAgentFamilyFolder`), whose `path()` answers the plugin's folder in its
+ * session family's Whiteboard, and makes it a required member of `KayAgentPluginApi`. It removes
+ * the `kay.agent` api's `filesystem` broker, the `filesystem.read` / `filesystem.write`
+ * permissions it was gated by, the `{ root: "filesystem", selector }` URI backing and the URI
+ * module `verbs` that went with it: plugins use `@bonsai/plugin-sdk/fs`, `userFiles` or
+ * `familyFolder` instead. No plugin used them. Stored grants naming the retired permissions are
+ * ignored, not refused. For the api surface this is a clean break with no shim and deliberately
+ * NOT a load refusal, like 0.12.0: every earlier release stays in the retention list, so a
+ * plugin compiled against 0.12.x that reads `api.filesystem` gets `undefined` at the call. The
+ * manifest is different: a manifest that still declares URI-module `verbs` or
+ * `filesystemBacking: { root: "filesystem" }` fails to parse and is refused at load (no plugin
+ * declared either). A plugin that imports
+ * `@bonsai/plugin-sdk/fs` or calls `familyFolder` declares `^0.13.0`, so an older host refuses a
+ * directory or repository plugin at load.
+ *
+ * 0.13.1 adds the signal engine to `@bonsai/plugin-sdk/signals`: `SignalDefinition`,
+ * `createSignalEngine` and `signalAnswersPass` (a plugin declares its Jev signals as data and the
+ * engine evaluates them, upstreams first, through `app.signals.observe`), plus `signalDigest`.
+ * `observe` gains three optional input fields, `subject`, `after` and `reuse`, and an observation
+ * and a read signal carry the stored `subject` and `upstreamId` back. Additive: a plugin compiled
+ * against 0.13.0 never sends or reads them. A plugin that imports the engine declares `^0.13.1`,
+ * so an older host refuses a directory or repository plugin at load.
+ *
+ * 0.13.2 adds `app.tools` (`KayAppTools`): `describe(sessionId, refs)` returns, for each tool name
+ * or address a live session can use, the text the agent sees for it, where it comes from, and
+ * whether it is one of Bonsai's own (`ownedByBonsai`). Checked per call against the new
+ * `tools.describe` claim. It also adds the manifest's top-level `ownedByBonsai` flag, honoured only
+ * for a plugin that ships with Bonsai. Additive: a plugin compiled against 0.13.1 never reads the
+ * member. A plugin that calls it declares `^0.13.2`, so an older host refuses a directory or
+ * repository plugin at load. The flag is new schema, so an older host refuses a manifest that sets
+ * it at parse, like 0.12.3's page open kind.
+ *
+ * 0.13.3 adds `app.usage` (`KayAppUsage`, `createUnavailableUsage`): `uriActivity({ prefix })`
+ * returns read and change activity for resources under one of the plugin's OWN registered URI
+ * schemes, checked per call (any other prefix answers `refused`). It also adds
+ * `KayAppAgentDefinition.maintains`, the URI schemes a registered agent definition's runs maintain;
+ * reads by such a run and its session family are not counted. Additive: a plugin compiled against
+ * 0.13.2 never reads the member or sets the field. A plugin that calls `app.usage` or declares
+ * `maintains` declares `^0.13.3`, so an older host refuses a directory or repository plugin at
+ * load; an older host's strict definition schema would refuse a definition that sets `maintains`.
+ *
+ * 0.13.4 caps reads through `@bonsai/plugin-sdk/fs`: a whole-file `readFile` (a file handle's too)
+ * and a single `read` reject past 64 MiB with `EFBIG` instead of copying the bytes into the daemon.
+ * No API changes: a plugin compiled against 0.13.3 runs unchanged unless it reads more than 64 MiB
+ * 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.
+ *
+ * 0.13.7 adds four subpaths. `@bonsai/plugin-sdk/vendored-mcp` re-exports
+ * `@bonsai/vendored-mcp-integration` (`createVendoredMcpUriModule` and its descriptor types; not
+ * the MCP read-port types). `transcript-review` and `agent-conversation` re-export the session
+ * folds Bonsai's own Sessions and Hindsight plugins share. `app-data` carries the app-data size
+ * caps on an entry with no other import, for code a `kay.ui` page also loads. The protocol it
+ * ships also carries three new capability-claim slugs (`mcp.host-server`, `prompt.resident`,
+ * `skills.declared-source`). Additive: a plugin compiled against 0.13.6 never imports the new
+ * subpaths, and its manifest parses unchanged. A plugin that imports one declares `^0.13.7`, so
+ * an older host refuses a directory or repository plugin at load instead of the import failing.
+ *
+ * 0.13.8 takes the PATCH slot under the addition rule, as `api.withJev` did in 0.8.1: one new
+ * member on the api a plugin RECEIVES, `api.systemOne` / `app.systemOne` (`@bonsai/plugin-sdk/
+ * system-one`), the System One client for `decide` and `extract` on Jev, Clef, Clef Flash and
+ * Clairic. It is non-optional for the same reason `withJev` is, and a host with no System One
+ * binds a client that throws `not-served`. `withJev` stays for every compatible plugin. A
+ * plugin that calls `systemOne` declares `^0.13.8`, so an older host refuses it at load instead
+ * of the member being absent.
+ *
+ * 0.13.9 adds `@bonsai/plugin-sdk/zod`: the host's `z` on an entry with no other import, for
+ * code a `kay.ui` page also loads (`kay-agent` exports the same `z`). Additive: a plugin compiled
+ * against 0.13.8 never imports it. A plugin that imports it declares `^0.13.9`, so an older host
+ * refuses a directory or repository plugin at load instead of the import failing.
+ *
+ * 0.13.10 adds two optional manifest fields. An `external-cli` auth scheme's `cli` says how the host
+ * connects it (the binary, its probe and sign-in argv, the hints, the install command), which the
+ * host read from its own tables before. An auth grant's `frontDoor` names the product a person
+ * connects a shared identity through (`gmail` over `google.account`), with an optional file picker.
+ * Additive: a manifest without them parses unchanged. A plugin that declares one declares
+ * `^0.13.10`, so an older host refuses it at load with that reason rather than a schema error.
+ *
+ * 0.14.0 removes `withJev`: `api.withJev` on `kay.agent`, `app.withJev` on `kay.app`, the
+ * `@bonsai/plugin-sdk/jev` subpath and every `Jev*` type it exported. A plugin uses `api.systemOne`
+ * / `app.systemOne` (`@bonsai/plugin-sdk/system-one`) instead. The `jev.use` capability claim is
+ * renamed `systemOne.use`, and stored grants are rewritten to the new slug. The signals subpath
+ * types its own surface now: observe options by `KayAppSignalObserveOptions`, state by
+ * `KayAppSignalState`, and questions and answers by `DecideQuestions` and `DecideAnswer`. For the
+ * api surface this is a clean break with no shim and deliberately NOT a load refusal, like 0.13.0:
+ * every earlier release stays in the retention list, so a plugin compiled against 0.13.x that
+ * reads `api.withJev` gets `undefined` at the call, and one that imports a value from
+ * `@bonsai/plugin-sdk/jev` fails at load. No plugin used either.
+ *
+ * 0.14.1 adds the owned-service `kay.app` auth list operation and `listAccounts`.
+ * Existing resolve-only `has` callers retain account bounds and now probe metadata without
+ * resolving credentials. Plugins using list declare `^0.14.1` so older hosts refuse at load.
+ *
+ * 0.15.0 replaces plugin-event publish arguments and requires resource URI declarations.
+ * Pre-0.15 SDK contracts are no longer retained: their publishers cannot satisfy this contract.
+ *
+ * 0.15.1 adds plugin-event automation conditions and public event-identity run matches.
+ * The host retains 0.15.0; plugins using the new condition declare ^0.15.1.
+ *
+ * 0.15.2 lets a plugin workflow start on the plugin's own events (a `plugin-event` trigger, with
+ * the event handed to the run as `ctx.match`) and declare `concurrency`. The host retains 0.15.0
+ * and 0.15.1; a plugin using either declares ^0.15.2, so an older host refuses it at load instead
+ * of `define` throwing inside activation.
+ *
+ * 0.15.3 adds `owner: "user"` to `app.automations.create`, with the `spawn-session` effect it
+ * allows: an automation the user owns, which outlives the calling session. Additive; plugins
+ * using it declare ^0.15.3 so an older host, which would ignore the field and make the calling
+ * session the owner, refuses them at load.
+ *
+ * 0.16.0 adds declared app-lifetime approval types and their brokered registration API.
+ * Plugins using approval types declare ^0.16.0; the host retains the 0.15 contracts.
+ *
+ * 0.16.1 adds `api.log` on both targets: a logger whose lines land in Bonsai's own log under the
+ * plugin's id. Additive; plugins calling it declare ^0.16.1 so an older host, which has no
+ * `api.log`, refuses them at load instead of activation throwing.
+ *
+ * 0.16.2 adds `api.vendoredMcp` on `kay.agent`: a port to a vendored MCP server the plugin declares,
+ * bound to that plugin, with its `VendoredMcpPort` / `VendoredMcpOutcome` types on
+ * `@bonsai/plugin-sdk/vendored-mcp`. Additive; plugins calling it declare ^0.16.2 so an older host,
+ * which has no `api.vendoredMcp`, refuses them at load instead of activation throwing.
+ *
+ * 0.16.3 adds `app.sessionEvents.subscribeSessionDeleted`: a notice for every deleted session, so
+ * a plugin can delete what it derived from it. Additive; plugins calling it declare ^0.16.3.
+ *
+ * 0.17.0 consolidates `app.corpus` into the always-present `app.sessions`. Read methods retain
+ * the `corpus.read` claim; control methods retain their own claims and are absent on read-only
+ * hosts. The summary helper takes `sessions` and stored-session DTOs use session names. The host
+ * no longer implements earlier runtime contracts, so declared 0.15/0.16 ranges are refused.
+ *
+ * 0.17.1 adds `app.skills.diff` and `app.skills.revision` under `skills.read`, `uncommitted` on a
+ * history result, refs by app-inventory row id, and `app.skills.writeFile`, `install` and `delete`
+ * under the new `skills.write` claim. Additive; plugins calling them declare ^0.17.1.
+ *
+ * 0.17.2 adds `app.account.activeOrganization()` (ungated) and `app.account.refreshBilling()`
+ * (under the `account.assert` grant), and an optional `refresh()` on an app-data source definition.
+ * Additive; plugins using them declare ^0.17.2.
+ *
+ * 0.17.3 adds `app.sealing` on `kay.app` (encrypt small values under a key only the plugin's id
+ * can use; the daemon holds it) and `api.endpoints` on `kay.agent` (call an endpoint the plugin's
+ * own `kay.app` part registered, by local id). Additive; plugins calling either declare ^0.17.3 so
+ * an older host, which has neither member, refuses them at load instead of activation throwing.
+ *
+ * 0.17.4 adds the optional `app.sessions.readCost(sessionId)` (a stored session's spend, models,
+ * and providers, under the same `corpus.read` grant as the other session reads). Additive.
+ *
+ * 0.17.5 adds `app.modelSelection.registerPolicy` on `kay.app`, a private method under the
+ * `model-selection.register` claim (only plugins Bonsai ships). Additive; a host without it leaves
+ * `app.modelSelection` undefined.
+ *
+ * 0.17.6 renames the stored-session read claim `corpus.read` to `sessions.read`, next to
+ * `sessions.run`, `sessions.create` and `sessions.update`; stored grants are rewritten to the new
+ * slug. The manifest's `contributes.corpusConsumers` becomes `contributes.sessionReaders` (kind
+ * `sessionReader`), a clean break: no plugin outside this repo declares it.
+ *
+ * 0.18.0 adds the calls hindsight moved onto (#14533): `app.sessions.annotate` and
+ * `app.sessions.compact` (claims `sessions.annotate`, `sessions.compact`), the session-state read,
+ * `app.models.listTiers({ provider })`, `app.usage.skillInvocations`, an optional `cause` on
+ * `app.models.complete` and `app.systemOne.decide`, `app.skills.registerSuggestionExplainer`, and
+ * the private `app.soul` (claim `soul.write`). Additive; plugins calling them declare ^0.18.0.
+ *
+ * 0.18.1 adds `servedSimulators` on both targets (`KayServedSimulators`): the simulators a
+ * simulating Bonsai daemon (evals, dev, tests) serves a plugin, keyed by adapter id. Optional and
+ * absent unless such a daemon serves it, so no plugin needs it to load; additive, so it takes the
+ * patch slot. A plugin need not declare a range to read it: an older host serves none, the same as
+ * a production daemon, and code that reads it already runs without it. It also deletes the other
+ * route a plugin could get a simulator by: a per-dispatch handle on a URI call's `ctx.auth`, and
+ * the type that `@bonsai/plugin-sdk/kay-agent` exported for it. Only Slack read it. It entered the
+ * source after 0.17.3's bump, and no SDK since 0.15.3 has been published, so no released contract
+ * loses a member and the removal does not spend the minor slot.
+ *
+ * 0.18.2 adds the marketplace calls the kay plugin moved onto (#14530):
+ * `app.skills.sourceContributors`, `app.skills.shareDestinations` and `app.skills.prepareShare`
+ * under `skills.read`, `app.skills.setMarketplaceAdded` under `skills.write`, and two private
+ * methods, `app.skills.confirmShare` (claim `skills.share`) and `app.plugins.setEnabled` (claim
+ * `plugins.set-enabled`). Additive; plugins calling them declare ^0.18.2.
+ *
+ * 0.18.3 adds `app.systemPrompt.register` on `kay.app`, a private method under the
+ * `system-prompt.register` claim (only plugins Bonsai ships): text a plugin adds to every chat's
+ * system prompt, rendered by the daemon and reused across chats. Additive; a host without it leaves
+ * `app.systemPrompt` undefined.
+ *
+ * 0.18.4 adds `api.compiler.bundleBrowser` on `kay.agent` (#14896): the host compiles
+ * caller-supplied bytes with caller-owned import resolution, without filesystem or network
+ * fallback. Additive and ungated; plugins calling it declare ^0.18.4.
+ *
+ * 0.19.0 makes the host resolve the credential of a tool or search provider that declares
+ * `requiresAuth` before calling it, as it already did for URI verbs (#15102). The credential
+ * arrives on the call as `ctx.credential` (`ResolvedCredential`, the one type all three share,
+ * replacing `ResolvedAuth` and `UriResolvedCredential`); tools and search providers no longer
+ * receive the `ctx.auth` resolver. `defineAuthedTool`, `withResolvedAuth` and
+ * `withResolvedSearchProvider` keep their shapes and read the credential off the call. A plugin
+ * built against an earlier SDK carries wrappers that ask `ctx.auth`, so the host no longer
+ * implements earlier runtime contracts and declared 0.17/0.18 ranges are refused.
+ *
+ * 0.19.1 adds `app.memory` note operations and `app.skills.propose` for pending suggestions.
+ *
+ * 0.19.2 adds the optional `app.sessions.readPage` (one bounded page of a stored transcript, or a
+ * typed reason there is none) and `app.sessions.listSessionPage` (a page of the session index, or
+ * rows by id), both under `sessions.read`; `app.knowledgeSearch` on `kay.app` under the `kay.app`
+ * `knowledgeSearch` grant; and re-exports the record-kind helpers (`storedTranscriptKindOf`,
+ * `parseStoredTranscriptKindFilter`) the daemon's reader numbers records with. Additive and
+ * optional, so it takes the patch slot; plugins calling them feature-detect.
+ *
+ * 0.20.0 removes the unused activation-free advertisement helpers and their types from
+ * `kay-agent` (#15160). No plugin used them, so 0.19.x stays served rather than refused, as with
+ * 0.14.0; a 0.19.x plugin that imported one would now fail at load.
+ *
+ * 0.20.1 deletes `preflight.acceptsPayloadlessWrite` from URI modules (#15164). A `write` call
+ * with neither `content` nor `source` now reaches the module's `write` with `content: undefined`,
+ * and the module decides: a route that takes no body (a folder create) proceeds, and one that
+ * needs a body refuses, naming what is missing. Only gdrive and microsoft declared the member,
+ * and no SDK since 0.15.3 has been published, so the removal does not spend the minor slot.
+ *
+ * 0.20.2 lets a `kay.agent` manifest describe a tool whole (#15152): `parameters` (and with it a
+ * required `description`), an `authService`/`authScheme` binding, and a `permission` (kind, rule
+ * key, and the string arguments that name its resources). The host builds the tool from that entry,
+ * and code supplies only the call through `api.implementTool(localId, execute)`. A plugin that runs
+ * in the plugin host must describe its tools this way, because the daemon never loads its code.
+ * Additive for every other plugin, so it takes the patch slot; plugins describing a tool declare
+ * ^0.20.2.
+ *
+ * 0.21.0 makes sign-in manifest data (#15151). The host builds every auth service and scheme from
+ * the manifest's `auth.services`, which gains OAuth endpoints, a public `clientId`, api-key
+ * `inputLabel`/`fields`/`setup`/`validates` and a service `summary`. `api.auth` keeps only the
+ * functions: `registerValidator` and `registerAccountResolver` replace `advertiseService` and the
+ * `declare{OAuthPkce,ApiKey,ExternalCli}Scheme` calls. 0.19.x and 0.20.x stay served, as with
+ * 0.20.0: most plugins declare no sign-in in code and are unaffected. One that does stops working
+ * until it is rebuilt against 0.21: a manifest `oauth2` scheme without the now-required endpoints
+ * is refused at load, and an activation that calls a removed member throws, so the plugin loses
+ * its tools and URI modules too.
+ *
+ * 0.21.1 lets a URI module's `read` return its index form on `RawResource.observation`, from the
+ * same fetch as the content, and deletes what steered the old second read (#15163): `observes`
+ * on URI modules, `format: "observation"` on the read context, and `owns` on knowledge sources.
+ * A plugin that still declares `owns` or `observes` loads, and the member is ignored. One that
+ * omits `owns` needs this host, since an older one requires it. No SDK since 0.15.3 has been
+ * published, so the removals take the patch slot, as in 0.20.1. It also adds `knownResourcesView`,
+ * which marks a list or search rendered from the known-resources ledger so the host does not
+ * record it back.
+ *
+ * 0.21.2 adds same-plugin informational tooltip apps to reference presentations, matched by
+ * canonical resource URI patterns, and context-only apps excluded from standalone navigation.
+ * Plugins declaring either require ^0.21.2.
+ *
+ * 0.22.0 deletes URI-module members the daemon used to call in a plugin's code (#15150):
+ * `authActions.classifyOperation` (sign-in actions come from `authActions.rules`), `preflight` (the
+ * verb rejects a bad call when it runs), `permission`, and `toMarkdown` (a verb's result carries
+ * its own `markdown`); `@bonsai/plugin-sdk/kay-agent` stops re-exporting
+ * `UriOperationPreflightPolicy`. A `kay.app` module also loses `matches`, `normalize` and
+ * `describe`: it routes, spells and links its addresses through its claims' `normalizeTo`, `title`
+ * and `sourceUrl`. The host drops these members from a 0.20.x or 0.21.x module rather than calling
+ * them, and a module already claims every scheme it declares, so both stay served.
+ *
+ * 0.22.1 renames `RawResource.observation` to `observations`, a list (#15168), so one read can
+ * index several documents: a Gmail thread read indexes each of its messages. A module that still
+ * returns `observation` loads, and its read is not indexed. No SDK since 0.15.3 has been
+ * published, so the rename takes the patch slot, as in 0.21.1. Plugins that return observations
+ * and declare a floor require ^0.22.1.
+ *
+ * 0.22.2 lets a converter decline a file its `matches` claimed (#15153): `convert` may resolve
+ * `undefined`, and the read pipeline tries the next converter that claimed the file. A plugin
+ * whose converters only convert is unaffected; one that declines requires ^0.22.2, since an older
+ * host reads the result's `content`. Additive, so it takes the patch slot.
+ *
+ * 0.23.0 trims the message approval type (#15154): `prepare` returns a promise, so the host can
+ * call it across a process boundary; `tighten` is gone (no plugin set it, and an unknown member
+ * is ignored); `resolveResource` is optional, for a provider that keeps no saved draft. A 0.22
+ * plugin's synchronous `prepare` is still read correctly, because the host awaits what it
+ * returns, so 0.22.x stays served.
+ *
+ * 0.23.0 also deletes `definePoller`'s `resolveCredential` option (#15154): the helper asks
+ * `app.backgroundAuth` itself, and `requiredScopes` on a background credential request becomes
+ * optional. Omitted, the host asks for the first scope of the manifest's `background-job` grant
+ * (`allowedScopes`) that the account holds, and answers `requires-auth` when it holds none. A
+ * 0.22.x plugin that passes `resolveCredential` still loads; the option is ignored, so its poller
+ * needs a `background-job` grant whose `allowedScopes` the host can choose from.
+ *
+ * 0.23.0 also deletes `timezone` from a cron schedule (#15394): every schedule, a workflow trigger's
+ * and an automation's, runs in the computer's current time zone and follows it when it changes.
+ * A `define` or create that still passes `timezone` is refused, so a 0.22.x plugin that pins a
+ * cron zone stops loading its workflow until it drops the field; every other 0.22.x plugin is
+ * unaffected and stays served. Plugins that declare a cron trigger declare ^0.23.0, since an
+ * older host requires the zone.
+ *
+ * 0.24.0 lets the daemon build a hosted plugin's URI module from its manifest alone (#15141).
+ * The module facts gain `verbs.searchable`; resolved modules carry `displayName` and
+ * `authServiceId`. Asana and Figma use their services' single auth scheme.
+ *
+ * 0.25.0 unifies URI writes (#15402): `write(input, content, sources, ctx)` receives an
+ * empty sources array for ordinary writes. Modules that accept files declare
+ * `acceptsWriteSources: true` in their manifest. Earlier SDK contracts are no longer served.
+ *
+ * 0.26.0 folds `writeBytes` into `write` (#15433): a binary `source` copy reaches `write` as a
+ * `Uint8Array` content, named and typed by `ctx.writeSource`, and only for a module that declares
+ * `acceptsBytes: true` in its manifest. A module that still defines `writeBytes` never receives
+ * bytes. Earlier SDK contracts are no longer served.
+ *
+ * 0.26.1 turns the revision check into a conditional `read` (#15423). `ctx.knownRevision` carries
+ * the revision the session holds, and a module that has verified the source has not moved returns
+ * `{ content: "", unchanged: true, metadata: { revision } }` with no body. The module's `revision`
+ * member is gone (the host drops a leftover one), so is `fallback` and `locate` (the host's own
+ * modules keep them), and so is the manifest's `filesystemBacking`, which no plugin declared.
+ * Additive for a plugin that never used them. A plugin that answers `unchanged` declares ^0.26.1.
+ *
+ * 0.26.2 lets a hosted URI module describe its calls for the approval card (#15423): a manifest
+ * URI module sets `describesOperations: true` when its code defines `describeOperation`, and the
+ * daemon calls the plugin host for it. `amendOperation` is gone: the host applies an "Allow with
+ * edits" answer itself, replacing top-level string properties of the payload, so a preview field
+ * is editable only when the payload is an object with that key as a string. `labelResource` is
+ * gone: a verb's result carries the transcript row's name as `label`. The SDK stops re-exporting
+ * `UriOperationAmendment`, `UriResourceLabelRequest` and `UriPreviewEdit`. The host ignores a
+ * leftover `amendOperation` or `labelResource`, so this is additive for a plugin that never sets
+ * the flag; a plugin whose manifest sets `describesOperations` declares ^0.26.2.
+ *
+ * 0.26.3 gives a plugin's own sign-in back what #15151 left behind (#15195). Every `oauth2` sign-in a
+ * plugin runs says where its account comes from: `account` is `"resolveAccountId"`,
+ * `"resolveAccounts"` or, on a hosted (`confidential`) sign-in whose broker names the account,
+ * `"sign-in"`, so each account a person signs in with is saved apart. `api.auth.registerAccountResolver`
+ * registers the named function on any such scheme, its own client's included, and the SDK refuses a
+ * plugin whose lookup and manifest disagree. An own-client (`pkce`) scheme may carry the
+ * `clientSecret` that goes with its `clientId`. A plugin with an `oauth2` sign-in declares ^0.26.3.
+ */
+declare const KAY_PLUGIN_SDK_VERSION: "0.26.3";
+
+declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
+
+/** Browser compilation over caller-supplied bytes, without filesystem or network authority. */
+declare interface KayAgentCompiler {
+    /** Rejects on compilation or source callback failure, and when the host composed no compiler. */
+    bundleBrowser(request: KayBrowserBundleRequest, sources: KayBrowserSources): Promise<KayBrowserBundle>;
+}
+
+/**
+ * The plugin-facing `kay.agent` own-endpoint call: a plugin's agent part calls an endpoint its own
+ * `kay.app` part registered. SDK 0.17.3; a plugin that calls it declares `compatibility.sdk`
+ * `^0.19.0`.
+ *
+ * A plugin's two parts load as separate modules and share no memory, so this is how agent code
+ * reaches state its app part keeps (a worker, a database). The manifest says which endpoints the
+ * agent part may call: the `kay.app` target declares the endpoint with a `register` grant, and
+ * `permissions.byTarget["kay.agent"].endpoints` lists it with `invoke`. No other plugin's endpoint
+ * is nameable.
+ *
+ * An endpoint whose only `invoke` grant is the plugin's own `kay.agent` target is not reachable
+ * from Bonsai's surfaces (its pages and runtime clients), so an action the agent takes after the
+ * session's approval card cannot be taken around it.
+ */
+/** Why an {@link KayAgentEndpoints.invoke} call produced no value. */
+declare type KayAgentEndpointFailureReason = 
+/** The manifest grants this plugin's `kay.agent` target no `invoke` on this endpoint. */
+"not-declared"
+/** The plugin's `kay.app` part is not running, or registered no handler for it. */
+| "unavailable"
+/** The handler did not answer within the host's fixed deadline (10 seconds). It may still finish. */
+| "timed-out"
+/** The caller's `signal` aborted. The handler may still finish. */
+| "cancelled"
+/** The handler threw; `message` is its error's message. */
+| "failed"
+/** The request or the handler's response does not match the endpoint's declared schema. */
+| "invalid";
+
+declare type KayAgentEndpointOutcome = {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly reason: KayAgentEndpointFailureReason;
+    readonly message: string;
+};
+
+declare interface KayAgentEndpoints {
+    /**
+     * Call `endpoint`, the local id this plugin's manifest declares on its `kay.app` target. Never
+     * rejects: every failure is an outcome. Nothing is queued: when the app part is not running the
+     * answer is `unavailable` at once.
+     */
+    invoke(endpoint: string, payload: unknown, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<KayAgentEndpointOutcome>;
+}
+
 /**
  * Publishes the plugin's declared events from agent code. See {@link KayAgentPluginApi.events}.
  */
@@ -1681,7 +2464,7 @@ declare interface KayAgentInteractionSurfaces {
     readonly desktop: InteractionSurface;
 }
 
-/** One knowledge-index hit — a reference and within-list rank score, never a snippet. */
+/** One knowledge-index hit - a reference and within-list rank score, never a snippet. */
 declare interface KayAgentKnowledgeHit {
     readonly uri: string;
     /** Comparable only with other hits returned by this search call. */
@@ -1691,7 +2474,7 @@ declare interface KayAgentKnowledgeHit {
 /**
  * Query the daemon's shared knowledge index, scoped to this plugin's own declared `kay.agent`
  * schemes. Deny-by-default: `api.knowledgeSearch` is absent unless the manifest requests the
- * `knowledgeSearch` grant AND the host effectively grants it — a plugin must feature-detect the
+ * `knowledgeSearch` grant AND the host effectively grants it - a plugin must feature-detect the
  * capability. (It is WIRING, so absence is still the signal here, unlike the claim-checked
  * capabilities around it.) The host pre-scopes every call to the
  * plugin's OWN declared URI schemes; a caller-supplied `uriPrefixes` outside that scope is dropped
@@ -1707,7 +2490,7 @@ declare type KayAgentKnowledgeSearch = (query: string, opts?: {
 /**
  * One row of the daemon's known-resources ledger: a resource the host has
  * observed flowing through one of this plugin's own URI modules (or recorded
- * through a host-side grant flow). Metadata facts, never content — content
+ * through a host-side grant flow). Metadata facts, never content - content
  * understanding stays with the knowledge index.
  */
 declare interface KayAgentKnownResource {
@@ -1722,7 +2505,7 @@ declare interface KayAgentKnownResource {
     readonly seenVia: KayAgentKnownResourceSeenVia;
     /**
      * Durable grant provenance (`picked` for a Drive-picker grant). Unlike `seenVia`, a later
-     * ordinary sighting never erases it — the row permanently remembers it entered the corpus
+     * ordinary sighting never erases it - the row permanently remembers it entered the corpus
      * through an explicit user grant.
      */
     readonly grantedVia?: string;
@@ -1741,12 +2524,12 @@ declare interface KayAgentKnownResource {
  * (the host-recorded memory that `contributes.uriModules[].knownResources`
  * opts a module's traffic into). Deny-by-default: `api.knownResources` is
  * absent unless the manifest requests the `knownResources` grant AND the host
- * effectively grants it — feature-detect it exactly like
+ * effectively grants it - feature-detect it exactly like
  * {@link KayAgentKnowledgeSearch}, the other WIRING capability. Every call is host-scoped to the plugin's
  * OWN declared module ids; there is no way to widen it. Read-only by design:
  * rows are created only by the host's recording wrap and host-side grant
  * writers, so a plugin can render its memory but never invent it. The ledger
- * is a cache of CLAIMS, not an authority — a returned row proves the resource
+ * is a cache of CLAIMS, not an authority - a returned row proves the resource
  * was once seen, never that it is still reachable.
  */
 declare interface KayAgentKnownResources {
@@ -1776,7 +2559,7 @@ declare interface KayAgentKnownResources {
  * How a known-resource row was MOST RECENTLY seen: one of the recording
  * wrap's verbs, or a host-side grant writer's `granted:<label>` (e.g. a
  * Drive picker completion writing `granted:picked`). The closed template
- * union keeps the contract honest without enumerating grant labels — a
+ * union keeps the contract honest without enumerating grant labels - a
  * plain-string widening here would silently admit junk provenance.
  */
 declare type KayAgentKnownResourceSeenVia = "read" | "list" | "search" | `granted:${string}`;
@@ -1785,7 +2568,7 @@ declare type KayAgentKnownResourceSeenVia = "read" | "list" | "search" | `grante
  * Claim-checked outbound HTTP. The handle is always present; authority is the CALL, not the handle.
  *
  * The signature is `fetch`'s on purpose: a plugin that already speaks `fetch` changes the object it
- * calls, not the code around it. What differs is invisible from here — the host builds an exact
+ * calls, not the code around it. What differs is invisible from here - the host builds an exact
  * `network.connect {connect}` claim from the live URL (and again from each redirect hop), checks it
  * against the user's grant ledger, and rejects with a {@link KayAgentCapabilityError} rather than
  * performing the request. There is no `allowedHosts` to read: a plugin cannot enumerate its own
@@ -1810,13 +2593,19 @@ declare interface KayAgentPluginApi {
     readonly knowledgeSearch?: KayAgentKnowledgeSearch;
     /** Absent unless the `knownResources` grant is requested and effectively granted. */
     readonly knownResources?: KayAgentKnownResources;
+    /**
+     * Optional: absent unless a simulating Bonsai daemon serves this plugin a simulator (SDK 0.18.1).
+     * A production daemon never does. In this version only plugins the release carries are served;
+     * any plugin may ship a `./simulator` later. See {@link KayServedSimulators}.
+     */
+    readonly servedSimulators?: KayServedSimulators;
     /**
      * Present when the host composes Whiteboard. Each operation is checked against its exact
      * `whiteboard.<operation> {scope}` claim; handle presence is not consent.
      */
     readonly whiteboard?: KayAgentWhiteboard;
     /**
-     * Always present; each request — and each redirect hop — is checked against
+     * Always present; each request - and each redirect hop - is checked against
      * `network.connect {connect}` for the host it is about to reach.
      */
     readonly network: KayAgentNetwork;
@@ -1847,6 +2636,8 @@ declare interface KayAgentPluginApi {
      * (SDK 0.13.8).
      */
     readonly systemOne: SystemOneClient;
+    /** Always present and ungated; compiles only caller-supplied bytes. SDK 0.18.4. */
+    readonly compiler: KayAgentCompiler;
     /**
      * The daemon's clock and the time zone the user is in, read together on each `snapshot()` call.
      * Always present and ungated: it confers no authority, since a plugin runs in the daemon's
@@ -1869,18 +2660,50 @@ declare interface KayAgentPluginApi {
      */
     readonly events: KayAgentEvents;
     /**
-     * Register a tool (a named function the agent can call). Parallel to the kernel's `registerTool`.
-     * To auth-gate a tool, build the definition with {@link withResolvedAuth}: it stamps the
-     * `requiresAuth` binding onto the definition and resolves a live token from the kernel-injected
-     * `ctx.auth` before the body runs — the same wrapper the built-in service tools use. A definition
-     * with no `requiresAuth` is an ordinary always-on tool.
+     * A logger whose lines land in Bonsai's own log under this plugin's id, filed on this
+     * activation's session. Always present and ungated, like {@link time}. Use it instead of
+     * `console`; see {@link KayPluginLog}.
+     */
+    readonly log: KayPluginLog;
+    /**
+     * Calls tools on the vendored MCP servers this plugin declares (`kay.app`
+     * `contributes.mcpServers`), signed in through the plugin's own auth service. A port reaches
+     * only this plugin's own server, and only while Bonsai hosts it for this plugin under its
+     * `mcp.host-server` grant; it never reaches another plugin's server or one the user configured.
+     * It calls any tool the server has, writes included. Always present; a host with no MCP host
+     * answers each call `failed`. Types: `@bonsai/plugin-sdk/vendored-mcp` (SDK 0.16.2).
+     */
+    readonly vendoredMcp: KayAgentVendoredMcp;
+    /**
+     * Calls the endpoints this plugin's own `kay.app` part registered and the manifest grants this
+     * target `invoke` on, by local id. Never another plugin's. Every failure is an outcome, never a
+     * rejection; the host fixes a 10-second deadline. Always present; a host with no app part
+     * answers each call `unavailable`. See {@link KayAgentEndpoints} (SDK 0.17.3).
+     */
+    readonly endpoints: KayAgentEndpoints;
+    /**
+     * Supply the `execute` of a tool kay-plugin.json describes (its entry declares `parameters`),
+     * by the entry's `localId`. The host builds the rest of the tool - name, label, description,
+     * parameters, auth binding and permission - from that entry. Build `execute` with
+     * {@link toolExecute}. For a tool declaring `authService`, a session resolves the credential
+     * onto `ctx.credential` before each call (for the account its `accountId` argument names, when
+     * the tool declares one) and never calls `execute` without one; outside a session it may be
+     * absent (SDK 0.20.2).
+     */
+    implementTool(localId: string, execute: KayAgentToolExecute): void;
+    /**
+     * Register a whole tool definition, for a declared tool whose entry has no `parameters` because
+     * part of its policy is code. Such a plugin cannot run in the plugin host; prefer
+     * {@link implementTool}. To auth-gate one, build the definition with {@link withResolvedAuth}
+     * (or `defineAuthedTool`).
      */
     registerTool(definition: ToolDefinition): void;
     /**
      * Register a web search provider (a backend behind the single `web_search` tool). Parallel to the
-     * kernel's `registerSearchProvider`. An own-credential provider carries its `requiresAuth` binding —
-     * build it with {@link withResolvedSearchProvider}, which stamps the binding and resolves the token
-     * from `ctx.auth`. A provider without a binding reuses inference credentials or needs none.
+     * kernel's `registerSearchProvider`. An own-credential provider carries its `requiresAuth` binding -
+     * build it with {@link withResolvedSearchProvider}, which stamps the binding; the host resolves the
+     * credential before each call and hands it to the body. A provider without a binding reuses
+     * inference credentials or needs none.
      */
     registerSearchProvider(provider: SearchProvider): void;
     /**
@@ -1899,23 +2722,34 @@ declare interface KayAgentPluginApi {
     registerConverter(converter: ContentConverter): void;
     /**
      * Always present; the registration is checked against `tool-interception.register`. Register
-     * a tool-call interceptor — the neutral around-execution seam over EVERY tool call in the session
+     * a tool-call interceptor - the neutral around-execution seam over EVERY tool call in the session
      * (any layer's tools, subagent sessions included): observe a call, delegate to the real tool via
      * `next()`, or return a substitute result so the real tool never runs. Materially higher
      * privilege than `registerTool` (which owns only its own tool), which is why the registration is
-     * a claim of its own. The permission gate still runs before execution — an interceptor can
+     * a claim of its own. The permission gate still runs before execution - an interceptor can
      * substitute results, never widen what is callable.
      */
     interceptToolCall(interceptor: ToolCallInterceptor): void;
+    /**
+     * Sign-in. The plugin's manifest (`auth.services`) declares every service and scheme and the
+     * facts the host shows and runs; plugin code registers only the functions a scheme needs.
+     */
     readonly auth: {
-        advertiseService(descriptor: PluginServiceDescriptor): void;
-        declareOAuthPkceScheme(serviceId: string, scheme: PluginOAuthPkceScheme): void;
-        declareApiKeyScheme(serviceId: string, scheme: PluginApiKeyScheme): void;
-        declareExternalCliScheme(serviceId: string, scheme: PluginExternalCliScheme): void;
+        /**
+         * The check for an `api-key` scheme the manifest marks `validates: true`. `serviceId` and
+         * `schemeId` are the manifest's global ids (`github.account`, `github.pat`).
+         */
+        registerValidator(serviceId: string, schemeId: string, validate: ValidatePluginApiKeyCredential): void;
+        /**
+         * The account lookup for an `oauth2` scheme whose manifest names it as where the account comes
+         * from (`account: "resolveAccountId"` or `"resolveAccounts"`), registering that function only.
+         * Refused on any other scheme.
+         */
+        registerAccountResolver(serviceId: string, schemeId: string, resolver: PluginAccountResolver): void;
         /**
          * Declare a delegated scheme (plugin-provided connect/refresh over opaque material) for a
-         * service. Mirrors the other three declarations; the host maps it onto the kernel's
-         * `DelegatedAuthScheme` and drives its `connect` from `service_connect`.
+         * service. The host maps it onto the kernel's `DelegatedAuthScheme` and drives its `connect`
+         * from `service_connect`.
          */
         declareDelegatedScheme(serviceId: string, scheme: PluginDelegatedScheme): void;
         /**
@@ -1935,7 +2769,7 @@ declare interface KayAgentPluginApi {
  * {@link KayAgentProcessRunResult.exitCode} always means the command itself failed, never that
  * permission did. Two DIFFERENT things reject, and a caller should handle both: a refusal rejects
  * with {@link KayAgentCapabilityError}, and cancelling through
- * {@link KayAgentProcessRunRequest.signal} rejects with an `AbortError` carrying a fixed message —
+ * {@link KayAgentProcessRunRequest.signal} rejects with an `AbortError` carrying a fixed message -
  * the host terminates the child and settles its output first, and deliberately does not echo back
  * the `reason` you aborted with. A user cancelling a run is not a crash. A timeout is NOT a
  * rejection: it resolves with exit code 124. The termination bound covers the DIRECT child only: a
@@ -1959,12 +2793,12 @@ declare interface KayAgentProcessRunRequest {
     readonly command: string;
     readonly argvClass: string;
     readonly args: readonly string[];
-    /** Abort the run; the host kills the DIRECT child and rejects — a forked descendant may outlive it (#6153). */
+    /** Abort the run; the host kills the DIRECT child and rejects - a forked descendant may outlive it (#6153). */
     readonly signal?: AbortSignal;
 }
 
 /**
- * A finished run. `stdout`/`stderr` are decoded text, and the host CAPS them — a truncation flag is
+ * A finished run. `stdout`/`stderr` are decoded text, and the host CAPS them - a truncation flag is
  * set rather than the output silently ending, so a plugin parsing the stream can tell "the command
  * printed this" apart from "the command printed more than we kept".
  */
@@ -1976,6 +2810,28 @@ declare interface KayAgentProcessRunResult {
     readonly stderrTruncated?: boolean;
 }
 
+/** The `execute` a plugin supplies for a tool its manifest describes. */
+declare type KayAgentToolExecute = ToolDefinition["execute"];
+
+/**
+ * Calls tools on the plugin's own vendored MCP servers. See {@link KayAgentPluginApi.vendoredMcp}.
+ */
+declare interface KayAgentVendoredMcp {
+    /**
+     * The port to `server`, a name this plugin declares in its `kay.app` target's
+     * `contributes.mcpServers`. Throws when the plugin declares no server of that name. A declared
+     * server that Bonsai does not host for this plugin still returns a port; each call then answers
+     * `unknown-server`. Its message names the plugin that holds the name, or else lists the possible
+     * reasons (no approved `mcp.host-server` grant, a sign-in the server cannot use, or a name that
+     * a plugin Bonsai ships or another installed plugin also claims) and points at the plugin's load
+     * diagnostic.
+     *
+     * A port reaches this plugin's own server only. To use another plugin's data, declare that
+     * plugin in the manifest's `dependencies.plugins`; a later SDK surface reaches it.
+     */
+    port<TTool extends string = string>(server: string): VendoredMcpPort<TTool>;
+}
+
 /**
  * Authenticated requests through the host's embedded-browser partition. The host confines every
  * call to the exact origin/path rows declared in the plugin manifest (segment-bounded), never
@@ -2094,7 +2950,7 @@ declare interface KayAgentWhiteboardUpdateInput {
 /**
  * `app.time` / `api.time`: host facts about time. Added to `kay.app` in SDK 0.12.1 and to
  * `kay.agent` with the calendar zone-of-record work: a plugin that calls it declares
- * `compatibility.sdk` `^0.12.1`, so an older Bonsai refuses a directory or repository plugin at
+ * `compatibility.sdk` `^0.19.0`, so an older Bonsai refuses a directory or repository plugin at
  * load instead of the call failing.
  */
 declare interface KayAppTime {
@@ -2104,9 +2960,7 @@ declare interface KayAppTime {
      * Every call asks the host again and returns a new object; nothing is cached. Call it where you
      * need the value (inside a tool, a handler or a workflow step), not inside `activate()`: a value
      * read there is as old as the activation, and the host can run a bundled plugin's `activate()`
-     * against a recording api that has no `time`, so a read there throws. The exception is a
-     * directory plugin that declares a workflow with a cron `timezone`: `workflows.define` is legal
-     * only during `activate()`, so it reads the zone there, and the schedule then keeps that zone.
+     * against a recording api that has no `time`, so a read there throws.
      * Keep the result for as long as you use it, and not across a long wait (a sleep, a timer, a
      * queued run): the zone can change while you wait. On a daemon that runs on the user's machine,
      * a change of the process's `TZ` shows in the next call. A `TZ` that names a zone wins over the
@@ -2197,7 +3051,7 @@ declare interface KayAppUserFileListing {
  * File I/O in user folders, run by the host off the daemon's main thread. Every path is absolute.
  * No method rejects; each answers a {@link KayAppUserFilesResult}. This is not a sandbox: it does
  * not limit which paths a plugin may touch. Added in SDK 0.12.5: a plugin that calls it declares
- * `compatibility.sdk` `^0.12.5`, so an older Bonsai refuses a directory or repository plugin at
+ * `compatibility.sdk` `^0.19.0`, so an older Bonsai refuses a directory or repository plugin at
  * load instead of the call failing.
  */
 declare interface KayAppUserFiles {
@@ -2293,6 +3147,119 @@ declare interface KayAppUserFileWalkEntry {
     readonly kind: KayAppUserFileKind;
 }
 
+declare interface KayBrowserBundle {
+    readonly outputs: readonly {
+        readonly path: string;
+        readonly text: string;
+    }[];
+    readonly warnings: readonly string[];
+}
+
+declare interface KayBrowserBundleRequest {
+    readonly entry: {
+        readonly path: string;
+    } | {
+        readonly path: string;
+        readonly contents: string;
+        readonly loader: "js" | "css";
+    };
+    readonly target: string;
+    readonly format: "iife" | "esm";
+    readonly charset: "ascii" | "utf8";
+    readonly minifyWhitespace: boolean;
+    readonly legalComments: "none" | "inline";
+}
+
+/** Import edges the host reports to a browser bundle's source resolver. */
+declare type KayBrowserImportKind = "entry-point" | "import-statement" | "require-call" | "dynamic-import" | "require-resolve" | "import-rule" | "composes-from" | "url-token";
+
+/** All imports and bytes come from these callbacks; the host performs no fallback I/O. */
+declare interface KayBrowserSources {
+    resolve(request: {
+        readonly path: string;
+        readonly importer: string;
+        readonly kind: KayBrowserImportKind;
+    }): Promise<{
+        readonly path: string;
+        readonly external?: boolean;
+        readonly suffix?: string;
+    }>;
+    load(request: {
+        readonly path: string;
+    }): Promise<{
+        readonly contents: string | Uint8Array;
+        readonly loader: "js" | "css" | "json" | "dataurl";
+    }>;
+}
+
+/**
+ * Each method writes one line. `name` is a stable event name (`sync-failed`), the same for every
+ * line of one kind, so the line can be found by name; put what varies in `message` and
+ * `attributes`. A call never throws, and it keeps working after the plugin is disabled.
+ */
+declare interface KayPluginLog {
+    debug(name: string, message: string, details?: KayPluginLogDetails): void;
+    info(name: string, message: string, details?: KayPluginLogDetails): void;
+    warn(name: string, message: string, details?: KayPluginLogDetails): void;
+    error(name: string, message: string, details?: KayPluginLogDetails): void;
+    /** A logger that adds these attributes to every line it writes, after the line's own. */
+    child(attributes: KayPluginLogAttributes): KayPluginLog;
+}
+
+/**
+ * The plugin-facing log contract: a logger each plugin gets as `api.log`, whose lines land in
+ * Bonsai's own log beside the daemon's.
+ *
+ * Ungated and always present, like `api.time`. It confers no authority: a line is written under the
+ * plugin's own id, which the host stamps and the plugin cannot set, and a plugin can already print
+ * to the console. The host records each line as `<pluginId>.<name>`, files it on a session's log
+ * when it knows the session, and keeps an error's stack, so a built-in plugin's failure reaches
+ * Error Tracking. Lines from a plugin the user added stay on the user's machine.
+ *
+ * This is a leaf module. It lives beside both target SDKs (rather than inside `kay-app`) so the
+ * `kay.agent` SDK can expose the same logger without importing the `kay.app` surface.
+ */
+/**
+ * Metadata only: ids, closed values, counts. Never session content. The host drops any value that
+ * is not a string, a boolean or a finite number.
+ */
+declare type KayPluginLogAttributes = Readonly<Record<string, string | number | boolean>>;
+
+declare interface KayPluginLogDetails {
+    /** The error object. The host keeps its message, its stack and its `cause` chain. */
+    readonly error?: unknown;
+    /**
+     * The session this line is about. Defaults to the session of the call the plugin is handling,
+     * when the host knows it (a tool call or a URI read); the line then lands on that session's
+     * `kay-log://events`. Pass it from an endpoint, a session-event handler or a timer. Work a call
+     * starts (a timer, a subscription) keeps that call's session unless a line names another.
+     */
+    readonly sessionId?: string;
+    readonly attributes?: KayPluginLogAttributes;
+}
+
+declare const KayPluginProtocolVersion: z.ZodLiteral<"kay.plugin.v1">;
+
+declare type KayPluginProtocolVersion = z.infer<typeof KayPluginProtocolVersion>;
+
+/**
+ * The simulators a simulating Bonsai daemon (evals, dev, tests) serves this plugin, keyed by the
+ * adapter id its simulated URI connection rows name. The daemon builds each from the plugin's own
+ * dev-only `./simulator` subpath; the plugin never imports its simulator.
+ *
+ * The member that carries this, `servedSimulators` on both plugin APIs, is optional and absent
+ * unless a simulating daemon serves it. A production daemon never does, so treat absence as the
+ * normal case. In this version the daemon serves it only to plugins the release carries; the seam
+ * is not specific to them, and any plugin may ship a `./simulator` later.
+ */
+declare interface KayServedSimulators {
+    /**
+     * What this plugin's simulator built for `adapterId`, or `undefined` when none was served for
+     * that id. The shape is the plugin's own simulator contract; narrow it before use.
+     */
+    get(adapterId: string): unknown;
+}
+
 /** Applies a KeyOf action to the given type. */
 declare function KeyOf<Type extends TSchema>(type: Type, options?: TSchemaOptions): TKeyOf_2<Type>;
 
@@ -2398,6 +3365,10 @@ declare function LiteralStringMapping(input: string): unknown;
 
 declare function LiteralTypeName<Value extends TLiteralValue>(value: Value): TLiteralTypeName<Value>;
 
+declare const LocalContributionId: z.ZodString;
+
+declare type LocalContributionId = z.infer<typeof LocalContributionId>;
+
 /** Applies a Lowercase action to the given type. */
 declare function Lowercase_2<Type extends TSchema>(type: Type, options?: TSchemaOptions): TLowercase<Type>;
 
@@ -2471,7 +3442,7 @@ declare type MidTurnCompactionRequest = {
      * Settles exactly once and never rejects, including abort and teardown paths.
      *
      * NEVER `await` this inside `execute`. The only thing that settles it is
-     * post-run compaction, and that cannot begin until this tool call returns —
+     * post-run compaction, and that cannot begin until this tool call returns -
      * so awaiting it here hangs the run behind itself, which is the exact
      * deadlock this capability replaced. Attach a callback and return.
      */
@@ -2481,6 +3452,10 @@ declare type MidTurnCompactionRequest = {
     readonly reason: "already-pending" | "maintenance-in-flight";
 };
 
+declare const MimeTypeString: z.ZodString;
+
+declare type MimeTypeString = z.infer<typeof MimeTypeString>;
+
 /** Compatibility settings for the Mistral chat API. */
 declare interface MistralConversationsCompat extends Static<typeof MistralConversationsCompatSchema> {
 }
@@ -2516,7 +3491,7 @@ declare interface Model<TApi extends Api> extends BaseModel<TApi> {
 }
 
 /**
- * The canonical model-facing content type — the single source of truth for what
+ * The canonical model-facing content type - the single source of truth for what
  * a `read`/`finalize` boundary emits and what an {@link AgentToolResult.content}
  * carries (it IS the same `(TextContent | ImageContent)` union). When pi-ai later
  * adds audio, this one alias widens and every consumer follows.
@@ -2601,6 +3576,8 @@ declare const NeverPattern = "(?!)";
 
 declare const NewLine = "\n";
 
+declare const NonEmptyString: z.ZodString;
+
 /** Applies a NonNullable action to the given type. */
 declare function NonNullable_2<Type extends TSchema>(type: Type, options?: TSchemaOptions): TNonNullable<Type>;
 
@@ -2622,33 +3599,12 @@ declare const NumberKey = "^-?(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$";
 
 declare const NumberPattern = "-?(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?";
 
-/**
- * Who may supply the OAuth client for a scheme: Bonsai's embedded client, or one the user pastes in
- * (BYOOC). An UNORDERED SET — list order carries no meaning (nothing reads it as a preference).
- */
-declare type OAuthClientSupplier = "kay" | "user";
-
 /** What the provider hands back at the redirect URI after the user approves. */
 declare interface OAuthRedirectResult {
     readonly code: string;
     readonly state: string;
 }
 
-/**
- * The two client-supply axes, structured so the illegal cell is unrepresentable: a `confidential`
- * exchange's secret may only ever be Bonsai's (held by the host's broker, never pasted by a
- * customer), so `confidential` types `clientSuppliers` as `readonly ["kay"]` — `confidential ×
- * user` is a compile-time impossibility in v1, not a runtime refusal. `pkce`'s `clientSuppliers`
- * is a non-empty set; {@link createOAuthPkceAuthScheme} dedupes it and refuses empty.
- */
-declare type OAuthSchemeClientAxes = {
-    readonly exchange: "pkce";
-    readonly clientSuppliers: readonly OAuthClientSupplier[];
-} | {
-    readonly exchange: "confidential";
-    readonly clientSuppliers: readonly ["kay"];
-};
-
 /** Creates an Object type. */
 declare function _Object_<Properties extends TProperties>(properties: Properties, options?: TObjectOptions): TObject<Properties>;
 
@@ -2667,6 +3623,79 @@ declare type ObjectLike_4 = Record<PropertyKey, any>;
 /** Extracts options from a TObject. */
 declare function ObjectOptions(type: TObject): TObjectOptions;
 
+/**
+ * A source-native read of one URI, shaped for downstream indexing rather than
+ * direct model consumption. A module's read returns it in
+ * `RawResource.observations`, built from the same fetch as the content, once
+ * per document it wants indexed; absence means "not indexed".
+ *
+ * Gone signal: the index retires a doc when a read throws `UriNotFoundError`
+ * or an error whose `.status === 404`. A module whose vendor signals "gone"
+ * differently (HTTP 410, a 200-body `{ok:false}`/`archived:true`, a
+ * 403/404-ambiguous lost-access response) must translate that into one of
+ * those two shapes itself; losing access to a resource counts as gone too.
+ * A read that cannot build a complete observation (a secondary fetch failed)
+ * returns none rather than a partial one.
+ *
+ * Account-qualified identity: a module whose read can resolve against more
+ * than one connected account (the account selector is stripped before route
+ * parsing, so two accounts reading the same opaque provider id would
+ * otherwise collide on one doc key) must fold `ctx.auth.credential.accountId`
+ * into `uri` - e.g. `gmail://@<accountId>/threads/<threadId>` - never the
+ * user-renamable connection/selector label. `ctx.auth.credential` is the
+ * reliable source of the resolved account at a `requiresAuth` module's
+ * `read()`: it is always populated once auth resolution runs (an
+ * `authContext`-style check already throws first when no credential
+ * resolved). `ctx.connection` may ALSO be populated by dispatch - a
+ * connection-required module receives it whenever the host has a tracked
+ * connection for the account - so do not assume it is absent; a module that
+ * wants the human-facing label rather than the account id reads
+ * `ctx.connection?.displayName`.
+ *
+ * `accountId` is guaranteed stable only for the life of the stored credential
+ * record, not necessarily across a disconnect/reconnect of the same
+ * real-world provider account. A scheme that mints an opaque id at connect
+ * time (the default for an api-key or delegated scheme, absent a
+ * provider-derived override) gets a fresh id on every connect; a scheme that
+ * instead derives the id from provider data (an oauth2-pkce scheme supplying
+ * `resolveAccountId`, e.g. reading an OIDC `sub`) keeps the same id across
+ * reconnect. A module on a scheme without a provider-stable id has two honest
+ * choices: derive its own stable identity from provider data at read time
+ * (call the provider's own account/"who am I" endpoint with the resolved
+ * credential and fold THAT into `uri` instead of `accountId`), or
+ * account-qualify with `accountId` knowing a disconnect/reconnect of the same
+ * real-world account re-keys its documents under a new id rather than
+ * updating them in place - nothing on the host side reconciles the old and
+ * new keys.
+ */
+declare interface ObservationMaterial {
+    /** Canonical URI of the observed resource - may differ from the input URI. */
+    readonly uri: string;
+    /** Scheme-prefixed content type, e.g. `"github.pr"`, `"gmail.thread"`, `"wikipedia.article"`. */
+    readonly kind: string;
+    readonly title?: string;
+    /** Source-native seams: one element per message/comment/section, in source order. */
+    readonly text?: readonly string[];
+    /** ISO-8601 creation time; provenance only - not persisted by the store yet. */
+    readonly createdAt?: string;
+    /** ISO-8601 last-update time; provenance only - not persisted by the store yet. */
+    readonly updatedAt?: string;
+    /** Source-native revision/version marker, when the source exposes one. */
+    readonly version?: string;
+    /**
+     * How long this resource stays worth semantically searching, measured from
+     * the LAST time it was observed - not from when it was first indexed. Every
+     * observation of an unchanged resource pushes the deadline out again, so a
+     * thread that keeps getting read keeps living and a quiet one ages out.
+     *
+     * Retention is opt-in per resource: absent means the index keeps the
+     * resource until its source says it is gone. A route declares this only
+     * when staleness is real for that shape - a chat thread or an inbox
+     * conversation goes cold, a durable note the user wrote does not.
+     */
+    readonly retainForMs?: number;
+}
+
 /** Applies a Omit action using the given types. */
 declare function Omit_2<Type extends TSchema, Indexer extends PropertyKey[]>(type: Type, indexer: readonly [...Indexer], options?: TSchemaOptions): TOmit<Type, TKeysToIndexer<Indexer>>;
 
@@ -2789,6 +3818,10 @@ declare const OptionalSemiColon: (input: string) => [unknown, string] | [];
 
 declare function OptionalSemiColonMapping(input: [unknown] | []): unknown;
 
+declare const PackageAssetPath: z.ZodString;
+
+declare type PackageAssetPath = z.infer<typeof PackageAssetPath>;
+
 /** Creates a Parameter type. */
 declare function Parameter<Name extends string, Extends extends TSchema, Equals extends TSchema>(name: Name, extends_: Extends, equals: Equals): TParameter<Name, Extends, Equals>;
 
@@ -3156,32 +4189,15 @@ declare function Pick_2<Type extends TSchema, Indexer extends TSchema>(type: Typ
 /** Creates a deferred Pick action. */
 declare function PickDeferred<Type extends TSchema, Indexer extends TSchema>(type: Type, indexer: Indexer, options?: TSchemaOptions): TPickDeferred<Type, Indexer>;
 
-declare interface PluginApiKeyScheme {
-    readonly id: string;
-    /** Human-facing flow name; distinguish the key's purpose when sibling flows exist. */
-    readonly displayName: string;
-    /** What this flow unlocks and when to choose it over another. */
-    readonly agentHint?: PluginSchemeAgentHint;
-    /** What this flow unlocks, for the person: one plain sentence, no identifiers or URIs. */
-    readonly summary?: string;
-    readonly inputLabel: string;
-    /**
-     * Two or more labeled inputs for an irreducibly multi-part secret (e.g. a Cloudflare Access
-     * service token's client-id + client-secret pair). The connect prompt collects one value per
-     * field; handlers read them from `ctx.auth.credential.fields`, keyed by field id. Index 0 is
-     * the primary field (mirrored as `accessToken`). Absent means the classic single-secret prompt;
-     * when present, ids must be unique and non-empty and there must be at least two entries — the
-     * kernel rejects an invalid declaration at activation.
-     */
-    readonly fields?: readonly PluginApiKeySchemeField[];
-    readonly setup?: PluginApiKeySchemeSetup;
-    readonly validate?: ValidatePluginApiKeyCredential;
+/**
+ * How a plugin learns which provider account a fresh OAuth token belongs to: one account, or every
+ * account the grant reaches. Registered with `api.auth.registerAccountResolver`.
+ */
+declare interface PluginAccountResolver {
+    readonly resolveAccountId?: ResolvePluginAccountId;
+    readonly resolveAccounts?: ResolvePluginAccounts;
 }
 
-declare type PluginApiKeySchemeField = ApiKeyAuthSchemeField;
-
-declare type PluginApiKeySchemeSetup = ApiKeyAuthSchemeSetup;
-
 /** The kinds of capability a plugin service can advertise (mirrors the host capability taxonomy). */
 declare type PluginCapabilityKind = "uri-module" | "tool" | "search-provider";
 
@@ -3198,12 +4214,12 @@ declare interface PluginDelegatedRevokeContext {
 }
 
 /**
- * A protocol-agnostic scheme whose connect/refresh choreography the plugin provides — the host owns
+ * A protocol-agnostic scheme whose connect/refresh choreography the plugin provides - the host owns
  * only vault persistence, gating, and single-flight refresh over the opaque material. Use this when
  * the auth dance is not a fixed OAuth-PKCE shape the host can drive itself (e.g. a runtime-discovered
- * authorization server: 401 sniff → RFC 9728/8414 discovery → RFC 7591 dynamic client registration →
+ * authorization server: 401 sniff -> RFC 9728/8414 discovery -> RFC 7591 dynamic client registration ->
  * PKCE). `connect` receives the host's browser-redirect capability (`ctx.redirectUri`/`ctx.authorize`)
- * when one is configured, and both are absent when the host has none — the scheme decides whether it
+ * when one is configured, and both are absent when the host has none - the scheme decides whether it
  * needs them and fails its connect with an actionable message if it does and they are missing.
  */
 declare interface PluginDelegatedScheme {
@@ -3253,83 +4269,18 @@ declare const PluginEventPublishInput: z.ZodObject<{
         poller: z.ZodOptional<z.ZodString>;
         runId: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
-    payload: z.ZodOptional<z.ZodType<JsonValue_2, unknown, z.core.$ZodTypeInternals<JsonValue_2, unknown>>>;
+    payload: z.ZodOptional<z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>;
 }, z.core.$strict>;
 
 declare type PluginEventPublishInput = z.infer<typeof PluginEventPublishInput>;
 
-/**
- * An external-CLI readiness scheme the plugin declares: a non-injectable marker for a
- * host-probed local binary (e.g. `osascript`, `gh`). Connecting runs `binary probeArgs`
- * through the host's bounded spawn — success mints a readiness record, never token
- * material. Verb handlers gated on such a scheme receive `ctx.auth.externalCli`, a
- * host-owned runner pinned to the declared binary; the plugin itself never spawns.
- * The manifest twin must declare the binary under `permissions.byTarget["agent.harness"].process`.
- */
-declare interface PluginExternalCliScheme {
-    readonly id: string;
-    readonly displayName: string;
-    /** What this flow unlocks and when to choose it over another. */
-    readonly agentHint?: PluginSchemeAgentHint;
-    /** What this flow unlocks, for the person: one plain sentence, no identifiers or URIs. */
-    readonly summary?: string;
-    /** The local binary the host probes and runs (bare name resolved on PATH, or absolute). */
-    readonly binary: string;
-    /** Argv for the readiness probe; exit 0 means connected. */
-    readonly probeArgs: readonly string[];
-    /** Optional argv whose stdout is recorded as the CLI version on connect. */
-    readonly versionArgs?: readonly string[];
-    /** Probe/run timeout; the host default applies when absent. */
-    readonly timeoutMs?: number;
-    /** Actionable copy when the binary is missing (install path, platform requirement). */
-    readonly installHint: string;
-    /** Actionable copy when the probe fails (login step, OS permission grant). */
-    readonly loginHint: string;
-}
+declare const PluginId: z.ZodString;
 
-/**
- * An OAuth2-PKCE scheme the plugin declares. The host owns acquisition, refresh, and broker
- * routing; the plugin supplies only public metadata plus an optional account-id resolver.
- *
- * Intersects {@link PluginOAuthSchemeClientAxes} (BYOOC — bring-your-own-OAuth-client):
- * `clientId`/`clientSecret` are optional and mean ONLY "the Kay-supplied embedded client" —
- * present iff `exchange: "pkce"` and the host ships one. A `confidential` scheme never carries
- * them; that secret lives with the host's broker, never with the plugin.
- */
-declare type PluginOAuthPkceScheme = PluginOAuthSchemeClientAxes & {
-    readonly id: string;
-    readonly displayName: string;
-    /** What this flow unlocks and when to choose it over another. */
-    readonly agentHint?: PluginSchemeAgentHint;
-    /** What this flow unlocks, for the person: one plain sentence, no identifiers or URIs. */
-    readonly summary?: string;
-    readonly authorizationUrl: string;
-    readonly tokenUrl: string;
-    /** The Bonsai-supplied embedded client id; omit for a `confidential` scheme or a `pkce` scheme
-     *  the host ships no client for. */
-    readonly clientId?: string;
-    /**
-     * An embedded, **non-confidential** client secret for a broker-free PKCE scheme — the case where a
-     * desktop-app OAuth client requires `client_secret` at the token endpoint but the secret is public
-     * by design (e.g. Google installed-app clients). Omit for brokered schemes, where the confidential
-     * secret lives in the broker and never reaches the plugin. A scheme is broker-free purely by virtue
-     * of its `id` not being in the host's brokered-scheme map; supplying this never routes it anywhere.
-     */
-    readonly clientSecret?: string;
-    readonly scopes: readonly string[];
-    /** Extra params merged into the authorize query. */
-    readonly extraAuthorizeParams?: Readonly<Record<string, string>>;
-    readonly resolveAccountId?: ResolvePluginAccountId;
-    /**
-     * Enumerate every provider account a fresh OAuth grant powers. Present only for providers whose
-     * consent can grant multiple accounts; the host commits one account binding per result while
-     * keeping one shared token lifecycle.
-     */
-    readonly resolveAccounts?: ResolvePluginAccounts;
-};
+declare type PluginId = z.infer<typeof PluginId>;
 
-/** BYOOC — the herd canonical client-axes union, aliased (never copied) for plugin authors. */
-declare type PluginOAuthSchemeClientAxes = OAuthSchemeClientAxes;
+declare const PluginNamespace: z.ZodString;
+
+declare type PluginNamespace = z.infer<typeof PluginNamespace>;
 
 /** What one connection flow unlocks and when an agent should choose it; grants no authority. */
 declare type PluginSchemeAgentHint = string;
@@ -3341,7 +4292,7 @@ declare interface PluginServiceCapability {
     readonly summary: string;
 }
 
-/** A service the plugin owns — advertised for discovery and used to gate auth-backed contributions. */
+/** A service the plugin owns - advertised for discovery and used to gate auth-backed contributions. */
 declare interface PluginServiceDescriptor {
     readonly id: string;
     readonly display: string;
@@ -3349,6 +4300,28 @@ declare interface PluginServiceDescriptor {
     readonly capabilities: readonly PluginServiceCapability[];
 }
 
+declare const PluginSourceClass: z.ZodEnum<{
+    bundled: "bundled";
+    "org-shared": "org-shared";
+    "user-local": "user-local";
+    "verified-marketplace": "verified-marketplace";
+    freeform: "freeform";
+}>;
+
+declare type PluginSourceClass = z.infer<typeof PluginSourceClass>;
+
+declare const PluginTargetName: z.ZodEnum<{
+    "kay.agent": "kay.agent";
+    "kay.app": "kay.app";
+    "kay.ui": "kay.ui";
+}>;
+
+declare type PluginTargetName = z.infer<typeof PluginTargetName>;
+
+declare const PluginToolName: z.ZodString;
+
+declare type PluginToolName = z.infer<typeof PluginToolName>;
+
 /**
  * What a run did to a URI. The words match the automation run wire's artifact actions. When one
  * run both creates and updates a URI, the reader reports `created`.
@@ -3357,7 +4330,7 @@ declare type ProducedResourceAction = "created" | "updated";
 
 /** One URI a tool call created or updated as a side effect. */
 declare interface ProducedResourceDeclaration {
-    /** A `scheme://…` URI or an absolute local file path, compared as an exact string. */
+    /** A `scheme://...` URI or an absolute local file path, compared as an exact string. */
     readonly uri: string;
     readonly action: ProducedResourceAction;
 }
@@ -3454,7 +4427,7 @@ declare type ProviderId = KnownProvider | string;
 declare interface ProxiedToolCall {
     /** The registered tool the carrier will invoke. */
     readonly toolName: string;
-    /** The input that tool will be invoked with — what the gate must classify. */
+    /** The input that tool will be invoked with - what the gate must classify. */
     readonly input: Record<string, unknown>;
 }
 
@@ -3464,6 +4437,28 @@ declare interface RawResource {
     readonly mimeType: string;
     readonly metadata?: RawResourceMetadata;
     readonly selector?: SelectorDisposition;
+    /**
+     * The indexable forms of this resource, built from the same fetch as
+     * `content`: one per document the read wants indexed (a thread read offers
+     * one per message). Absent or empty means nothing is indexed. The read tool
+     * takes them off before the cache and the model; other host reads
+     * (out-of-band host reads) return them untouched.
+     */
+    readonly observations?: readonly ObservationMaterial[];
+    /** How long the host may cache this result; see {@link UriCachePolicy.ttlMs}. */
+    readonly cachePolicy?: Pick<UriCachePolicy, "ttlMs">;
+    /**
+     * A short name for the resource this call touched, for the transcript row; absent shows the
+     * address. Render-only: the host stamps it on the tool result's `details`, never in `content`.
+     */
+    readonly label?: UriResourceLabel;
+    /**
+     * Answer to a `read` called with `ctx.knownRevision`: the module checked the source's current
+     * revision and it equals `knownRevision`, so `content` is empty and `metadata.revision` equals
+     * `knownRevision`. Set it only when that check was made and matched; a module that cannot
+     * check cheaply, or that found a different revision, returns the full resource without it.
+     */
+    readonly unchanged?: true;
 }
 
 declare interface RawResourceCacheControl {
@@ -3507,7 +4502,7 @@ declare interface RawResourceMetadata {
     readonly resourceIdentity?: RawResourceIdentity;
     /**
      * The resource's stable public address when `uri` reports something more
-     * specific than the address a consumer names it by — a retained revision
+     * specific than the address a consumer names it by - a retained revision
      * (`skill://<id>/@revision/<version>`) served for a `skill://<source>/<name>`
      * read. Present only when the two differ. Consumers that attribute by name
      * (the read tool's `skillName` detail, and everything keyed off it) read
@@ -3582,6 +4577,29 @@ declare function Refine<Type extends TSchema, Value = Static<Type>>(type: Type,
 /** Applies a Refine check to the given type. */
 declare function RefineAdd<Type extends TSchema>(type: Type, refinement: TRefinement<Type>): TRefineAdd<Type>;
 
+/**
+ * The web-session scope-confinement refinement, coined ONCE and shared by both
+ * web-session boundaries: `loginUrl` and `probe.url` must each fall within a
+ * declared `cookieDomains` entry. The manifest boundary
+ * (`PluginWebSessionDeclaration`) enforces it because those URLs are
+ * authenticated-navigation/request primitives a third-party manifest hands the
+ * host; the resolved/wire boundary (`ResolvedPluginWebSession`) re-runs the SAME
+ * check rather than trust it survived resolution (its parse is the surface's
+ * only validation against a skewed daemon). Two copies of the check itself would
+ * be one edit away from disagreeing across those hops.
+ */
+declare function refineWebSessionScopeConfined(webSession: {
+    readonly cookieDomains: readonly string[];
+    readonly loginUrl: string;
+    readonly probe: {
+        readonly url: string;
+    };
+}, ctx: z.RefinementCtx): void;
+
+declare const RegistrableDomain: z.ZodString;
+
+declare type RegistrableDomain = z.infer<typeof RegistrableDomain>;
+
 /** Applies an RemoveImmutable action to a type. */
 declare function RemoveImmutable<Type extends TSchema>(type: Type, options?: TSchemaOptions): TRemoveImmutable<Type>;
 
@@ -3612,7 +4630,7 @@ declare function RequiredDeferred<Type extends TSchema>(type: Type, options?: TS
 declare type RequiredKeys<Properties extends TProperties, Result extends PropertyKey = keyof Omit<Properties, ReadonlyOptionalKeys<Properties> | ReadonlyKeys<Properties> | OptionalKeys<Properties>>> = Result;
 
 /**
- * The capability⇄service auth binding. A registration carrying this is gated on `serviceId`'s
+ * The capability<->service auth binding. A registration carrying this is gated on `serviceId`'s
  * connectivity; the runtime answers "is this capability authorized?" from this plus vault state.
  */
 declare interface RequiresAuth {
@@ -3620,7 +4638,7 @@ declare interface RequiresAuth {
     /**
      * Optional scheme preference. Absent means the binding is service-level: any injectable scheme
      * of the service satisfies it, and resolution picks each account's own backing scheme. Present,
-     * it names the scheme resolution tries first — an account connected under a sibling injectable
+     * it names the scheme resolution tries first - an account connected under a sibling injectable
      * scheme still satisfies the binding and resolves against its own scheme. A non-injectable
      * capability (`external-cli`) MUST name its scheme: it is a scheme-exact island.
      */
@@ -3628,7 +4646,7 @@ declare interface RequiresAuth {
     /**
      * The scopes this capability needs to do its job. Threaded through `resolveToken` into the
      * vault load so a grant-enforcing vault (the daemon's authority-backed vault) can refuse a
-     * plugin whose granted scopes don't cover them (`scopesCovered`) — per call, per plugin. Absent
+     * plugin whose granted scopes don't cover them (`scopesCovered`) - per call, per plugin. Absent
      * means the capability declares no scope requirement (the single-user local path never checks
      * scopes; it is a daemon per-plugin enforcement input). Also read by the scope-aware half of
      * `isBindingSatisfied` when the host supplies a granted-scopes reader.
@@ -3640,11 +4658,11 @@ declare interface RequiresAuth {
      */
     readonly scopeRequirement?: ScopeRequirement;
     /**
-     * The service id to NAME in connect guidance when this capability is gated — a host-composed
+     * The service id to NAME in connect guidance when this capability is gated - a host-composed
      * FRONT DOOR whose `service_connect` grants exactly what this binding needs (e.g. Gmail's
      * modules resolve under the shared `google.account` credential but connect via the `gmail`
      * front door, which expands only Gmail's scopes onto it). Guidance only: credential resolution
-     * still keys on `(serviceId, schemeId)`. Absent, guidance names `serviceId` — which for a
+     * still keys on `(serviceId, schemeId)`. Absent, guidance names `serviceId` - which for a
      * scoped binding on a shared multi-product credential would send the agent to a connect that
      * classifies resolved and no-ops, never granting the missing scopes.
      */
@@ -3652,22 +4670,931 @@ declare interface RequiresAuth {
 }
 
 /**
- * What the resolver hands a tool body: a live token for a concrete account + identity.
- * `accessToken` is `apiKey` for an api-key scheme or the (refreshed) bearer for oauth.
+ * The credential the host resolved for one call to plugin code that declares `requiresAuth`: a URI
+ * verb (`ctx.auth.credential`), a tool (`ctx.credential`) or a search provider (`ctx.credential`).
+ * Plain data, so it crosses a process boundary with the call; plugin code never asks for one.
  */
-declare interface ResolvedAuth {
+declare interface ResolvedCredential {
+    /** Bearer for OAuth schemes, apiKey for api-key schemes. Host-resolved and refreshed. */
     readonly accessToken: string;
-    readonly account: AuthAccount;
-    readonly identityMode: IdentityMode;
+    readonly accountId: string;
     readonly schemeId: string;
     readonly scopes?: readonly string[];
     /**
-     * Every value of a multi-field api-key credential, keyed by the scheme's field id;
-     * `accessToken` mirrors the primary (first) field. Absent for single-secret schemes.
+     * Every value of a multi-field api-key credential, keyed by the scheme's declared field id
+     * (`accessToken` mirrors the primary field). Absent for single-secret schemes.
      */
     readonly fields?: Readonly<Record<string, string>>;
 }
 
+declare const ResolvedPluginContractV1: z.ZodObject<{
+    protocol: z.ZodLiteral<"kay.plugin.v1">;
+    pluginId: z.ZodString;
+    namespace: z.ZodString;
+    contributions: z.ZodArray<z.ZodObject<{
+        target: z.ZodEnum<{
+            "kay.agent": "kay.agent";
+            "kay.app": "kay.app";
+            "kay.ui": "kay.ui";
+        }>;
+        kind: z.ZodEnum<{
+            tool: "tool";
+            resource: "resource";
+            endpoint: "endpoint";
+            storage: "storage";
+            command: "command";
+            authService: "authService";
+            app: "app";
+            uriModule: "uriModule";
+            configSection: "configSection";
+            skill: "skill";
+            converter: "converter";
+            artifactUriModule: "artifactUriModule";
+            cliBinding: "cliBinding";
+            searchProvider: "searchProvider";
+            interactionDriver: "interactionDriver";
+            entityResolver: "entityResolver";
+            agentRenderer: "agentRenderer";
+            eventDefinition: "eventDefinition";
+            eventSubscription: "eventSubscription";
+            appDataSource: "appDataSource";
+            whiteboardType: "whiteboardType";
+            approvalType: "approvalType";
+            contextContributor: "contextContributor";
+            transcriptionProvider: "transcriptionProvider";
+            deviceDelegation: "deviceDelegation";
+            sessionReader: "sessionReader";
+            mcpServer: "mcpServer";
+            uiCommand: "uiCommand";
+            uiSlot: "uiSlot";
+            settingsPanel: "settingsPanel";
+            resultRenderer: "resultRenderer";
+            referencePresentation: "referencePresentation";
+            view: "view";
+            theme: "theme";
+        }>;
+        localId: z.ZodString;
+        globalId: z.ZodString;
+    }, z.core.$strict>>;
+    consumesAuthServices: z.ZodArray<z.ZodString>;
+    explicitDependencies: z.ZodArray<z.ZodString>;
+    authServices: z.ZodArray<z.ZodObject<{
+        localId: z.ZodString;
+        globalId: z.ZodString;
+        displayName: z.ZodString;
+        summary: z.ZodOptional<z.ZodString>;
+        schemes: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodDiscriminatedUnion<[z.ZodObject<{
+            exchange: z.ZodLiteral<"pkce">;
+            clientSuppliers: z.ZodArray<z.ZodEnum<{
+                user: "user";
+                kay: "kay";
+            }>>;
+            clientId: z.ZodOptional<z.ZodString>;
+            clientSecret: z.ZodOptional<z.ZodString>;
+            account: z.ZodOptional<z.ZodEnum<{
+                resolveAccountId: "resolveAccountId";
+                resolveAccounts: "resolveAccounts";
+            }>>;
+            localId: z.ZodString;
+            globalId: z.ZodString;
+            kind: z.ZodLiteral<"oauth2">;
+            scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            authorizationUrl: z.ZodURL;
+            tokenUrl: z.ZodURL;
+            extraAuthorizeParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            displayName: z.ZodOptional<z.ZodString>;
+            agentHint: z.ZodOptional<z.ZodString>;
+            summary: z.ZodOptional<z.ZodString>;
+            provisioning: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                displayName: z.ZodString;
+                description: z.ZodString;
+                remediationUrl: z.ZodOptional<z.ZodURL>;
+                probe: z.ZodObject<{
+                    url: z.ZodURL;
+                    method: z.ZodEnum<{
+                        GET: "GET";
+                    }>;
+                    verdictStatuses: z.ZodArray<z.ZodNumber>;
+                    nonEmptyArrayAt: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>, z.ZodObject<{
+            exchange: z.ZodLiteral<"confidential">;
+            clientSuppliers: z.ZodTuple<[z.ZodLiteral<"kay">], null>;
+            account: z.ZodEnum<{
+                resolveAccountId: "resolveAccountId";
+                resolveAccounts: "resolveAccounts";
+                "sign-in": "sign-in";
+            }>;
+            localId: z.ZodString;
+            globalId: z.ZodString;
+            kind: z.ZodLiteral<"oauth2">;
+            scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            authorizationUrl: z.ZodURL;
+            tokenUrl: z.ZodURL;
+            extraAuthorizeParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            displayName: z.ZodOptional<z.ZodString>;
+            agentHint: z.ZodOptional<z.ZodString>;
+            summary: z.ZodOptional<z.ZodString>;
+            provisioning: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                displayName: z.ZodString;
+                description: z.ZodString;
+                remediationUrl: z.ZodOptional<z.ZodURL>;
+                probe: z.ZodObject<{
+                    url: z.ZodURL;
+                    method: z.ZodEnum<{
+                        GET: "GET";
+                    }>;
+                    verdictStatuses: z.ZodArray<z.ZodNumber>;
+                    nonEmptyArrayAt: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>], "exchange">, z.ZodObject<{
+            localId: z.ZodString;
+            globalId: z.ZodString;
+            kind: z.ZodLiteral<"api-key">;
+            scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            inputLabel: z.ZodString;
+            fields: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                label: z.ZodString;
+            }, z.core.$strict>>>;
+            setup: z.ZodOptional<z.ZodObject<{
+                instructions: z.ZodString;
+                url: z.ZodURL;
+            }, z.core.$strict>>;
+            validates: z.ZodOptional<z.ZodLiteral<true>>;
+            displayName: z.ZodOptional<z.ZodString>;
+            agentHint: z.ZodOptional<z.ZodString>;
+            summary: z.ZodOptional<z.ZodString>;
+            provisioning: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                displayName: z.ZodString;
+                description: z.ZodString;
+                remediationUrl: z.ZodOptional<z.ZodURL>;
+                probe: z.ZodObject<{
+                    url: z.ZodURL;
+                    method: z.ZodEnum<{
+                        GET: "GET";
+                    }>;
+                    verdictStatuses: z.ZodArray<z.ZodNumber>;
+                    nonEmptyArrayAt: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>, z.ZodObject<{
+            localId: z.ZodString;
+            globalId: z.ZodString;
+            kind: z.ZodLiteral<"delegated">;
+            scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            displayName: z.ZodOptional<z.ZodString>;
+            agentHint: z.ZodOptional<z.ZodString>;
+            summary: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            localId: z.ZodString;
+            globalId: z.ZodString;
+            kind: z.ZodLiteral<"external-cli">;
+            scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            cli: z.ZodOptional<z.ZodObject<{
+                binary: z.ZodString;
+                probe: z.ZodObject<{
+                    args: z.ZodArray<z.ZodString>;
+                    timeoutMs: z.ZodOptional<z.ZodNumber>;
+                    signedOutMarker: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+                }, z.core.$strict>;
+                login: z.ZodOptional<z.ZodObject<{
+                    args: z.ZodArray<z.ZodString>;
+                    timeoutMs: z.ZodOptional<z.ZodNumber>;
+                    pasteCode: z.ZodOptional<z.ZodObject<{
+                        args: z.ZodArray<z.ZodString>;
+                        label: z.ZodString;
+                    }, z.core.$strict>>;
+                }, z.core.$strict>>;
+                install: z.ZodOptional<z.ZodObject<{
+                    command: z.ZodString;
+                    args: z.ZodArray<z.ZodString>;
+                }, z.core.$strict>>;
+                hints: z.ZodObject<{
+                    install: z.ZodString;
+                    login: z.ZodString;
+                }, z.core.$strict>;
+            }, z.core.$strict>>;
+            displayName: z.ZodOptional<z.ZodString>;
+            agentHint: z.ZodOptional<z.ZodString>;
+            summary: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>], "kind">>;
+        purposes: z.ZodArray<z.ZodString>;
+        webSession: z.ZodOptional<z.ZodObject<{
+            importance: z.ZodEnum<{
+                required: "required";
+                recommended: "recommended";
+            }>;
+            loginUrl: z.ZodURL;
+            cookieDomains: z.ZodArray<z.ZodString>;
+            probe: z.ZodObject<{
+                url: z.ZodURL;
+                method: z.ZodEnum<{
+                    GET: "GET";
+                    POST: "POST";
+                }>;
+                signedInStatuses: z.ZodArray<z.ZodNumber>;
+            }, z.core.$strict>;
+            oauthVenue: z.ZodEnum<{
+                external: "external";
+                embedded: "embedded";
+            }>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    grants: z.ZodOptional<z.ZodObject<{
+        byTarget: z.ZodObject<{
+            "kay.agent": z.ZodOptional<z.ZodObject<{
+                auth: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    operations: z.ZodArray<z.ZodEnum<{
+                        status: "status";
+                        list: "list";
+                        connect: "connect";
+                        disconnect: "disconnect";
+                        resolve: "resolve";
+                    }>>;
+                    purposes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    allowedScopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    requiredScopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    connectScopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    scopeRequirement: z.ZodOptional<z.ZodObject<{
+                        purpose: z.ZodString;
+                        alternatives: z.ZodArray<z.ZodObject<{
+                            allOf: z.ZodArray<z.ZodObject<{
+                                scope: z.ZodString;
+                                reason: z.ZodExactOptional<z.ZodString>;
+                            }, z.core.$strict>>;
+                        }, z.core.$strict>>;
+                    }, z.core.$strict>>;
+                    scopeDefinitions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        id: z.ZodString;
+                        label: z.ZodString;
+                        description: z.ZodString;
+                        documentationUrl: z.ZodOptional<z.ZodURL>;
+                    }, z.core.$strict>>>;
+                    frontDoor: z.ZodOptional<z.ZodObject<{
+                        id: z.ZodString;
+                        displayName: z.ZodString;
+                        resourcePicker: z.ZodOptional<z.ZodObject<{
+                            effect: z.ZodEnum<{
+                                selection: "selection";
+                                "resource-grant": "resource-grant";
+                            }>;
+                            mimeTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                            successNote: z.ZodOptional<z.ZodString>;
+                        }, z.core.$strict>>;
+                    }, z.core.$strict>>;
+                    service: z.ZodString;
+                    schemes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    accountSelectors: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                        kind: z.ZodLiteral<"active">;
+                    }, z.core.$strict>, z.ZodObject<{
+                        kind: z.ZodLiteral<"account-id">;
+                        accountId: z.ZodString;
+                    }, z.core.$strict>, z.ZodObject<{
+                        kind: z.ZodLiteral<"record-id">;
+                        recordId: z.ZodString;
+                    }, z.core.$strict>], "kind">>;
+                }, z.core.$strict>>>;
+                storage: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    kind: z.ZodEnum<{
+                        sqlite: "sqlite";
+                        dataDir: "dataDir";
+                    }>;
+                    operations: z.ZodArray<z.ZodEnum<{
+                        open: "open";
+                        read: "read";
+                        write: "write";
+                    }>>;
+                }, z.core.$strict>>>;
+                events: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    event: z.ZodString;
+                    operations: z.ZodArray<z.ZodEnum<{
+                        subscribe: "subscribe";
+                        publish: "publish";
+                    }>>;
+                }, z.core.$strict>>>;
+                endpoints: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    operations: z.ZodArray<z.ZodEnum<{
+                        register: "register";
+                        invoke: "invoke";
+                    }>>;
+                    endpoint: z.ZodString;
+                }, z.core.$strict>>>;
+                webSession: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    origin: z.ZodString;
+                    pathPrefixes: z.ZodArray<z.ZodString>;
+                    csrf: z.ZodOptional<z.ZodObject<{
+                        sourceUrl: z.ZodURL;
+                        selector: z.ZodString;
+                        attribute: z.ZodString;
+                        header: z.ZodString;
+                        bodyField: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strict>>;
+                }, z.core.$strict>>>;
+                knowledgeSearch: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    scope: z.ZodLiteral<"own-schemes">;
+                }, z.core.$strict>>>;
+                knownResources: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    scope: z.ZodLiteral<"own-modules">;
+                }, z.core.$strict>>>;
+            }, z.core.$strict>>;
+            "kay.app": z.ZodOptional<z.ZodObject<{
+                auth: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    operations: z.ZodArray<z.ZodEnum<{
+                        status: "status";
+                        list: "list";
+                        connect: "connect";
+                        disconnect: "disconnect";
+                        resolve: "resolve";
+                    }>>;
+                    purposes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    allowedScopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    requiredScopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    connectScopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    scopeRequirement: z.ZodOptional<z.ZodObject<{
+                        purpose: z.ZodString;
+                        alternatives: z.ZodArray<z.ZodObject<{
+                            allOf: z.ZodArray<z.ZodObject<{
+                                scope: z.ZodString;
+                                reason: z.ZodExactOptional<z.ZodString>;
+                            }, z.core.$strict>>;
+                        }, z.core.$strict>>;
+                    }, z.core.$strict>>;
+                    scopeDefinitions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        id: z.ZodString;
+                        label: z.ZodString;
+                        description: z.ZodString;
+                        documentationUrl: z.ZodOptional<z.ZodURL>;
+                    }, z.core.$strict>>>;
+                    frontDoor: z.ZodOptional<z.ZodObject<{
+                        id: z.ZodString;
+                        displayName: z.ZodString;
+                        resourcePicker: z.ZodOptional<z.ZodObject<{
+                            effect: z.ZodEnum<{
+                                selection: "selection";
+                                "resource-grant": "resource-grant";
+                            }>;
+                            mimeTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                            successNote: z.ZodOptional<z.ZodString>;
+                        }, z.core.$strict>>;
+                    }, z.core.$strict>>;
+                    service: z.ZodString;
+                    schemes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    accountSelectors: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                        kind: z.ZodLiteral<"active">;
+                    }, z.core.$strict>, z.ZodObject<{
+                        kind: z.ZodLiteral<"account-id">;
+                        accountId: z.ZodString;
+                    }, z.core.$strict>, z.ZodObject<{
+                        kind: z.ZodLiteral<"record-id">;
+                        recordId: z.ZodString;
+                    }, z.core.$strict>], "kind">>;
+                }, z.core.$strict>>>;
+                storage: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    kind: z.ZodEnum<{
+                        sqlite: "sqlite";
+                        dataDir: "dataDir";
+                    }>;
+                    operations: z.ZodArray<z.ZodEnum<{
+                        open: "open";
+                        read: "read";
+                        write: "write";
+                    }>>;
+                }, z.core.$strict>>>;
+                events: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    event: z.ZodString;
+                    operations: z.ZodArray<z.ZodEnum<{
+                        subscribe: "subscribe";
+                        publish: "publish";
+                    }>>;
+                }, z.core.$strict>>>;
+                endpoints: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    operations: z.ZodArray<z.ZodEnum<{
+                        register: "register";
+                        invoke: "invoke";
+                    }>>;
+                    endpoint: z.ZodString;
+                }, z.core.$strict>>>;
+                webSession: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    origin: z.ZodString;
+                    pathPrefixes: z.ZodArray<z.ZodString>;
+                    csrf: z.ZodOptional<z.ZodObject<{
+                        sourceUrl: z.ZodURL;
+                        selector: z.ZodString;
+                        attribute: z.ZodString;
+                        header: z.ZodString;
+                        bodyField: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strict>>;
+                }, z.core.$strict>>>;
+                knowledgeSearch: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    scope: z.ZodLiteral<"own-schemes">;
+                }, z.core.$strict>>>;
+                knownResources: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    scope: z.ZodLiteral<"own-modules">;
+                }, z.core.$strict>>>;
+            }, z.core.$strict>>;
+            "kay.ui": z.ZodOptional<z.ZodObject<{
+                auth: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    operations: z.ZodArray<z.ZodEnum<{
+                        status: "status";
+                        list: "list";
+                        connect: "connect";
+                        disconnect: "disconnect";
+                        resolve: "resolve";
+                    }>>;
+                    purposes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    allowedScopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    requiredScopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    connectScopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    scopeRequirement: z.ZodOptional<z.ZodObject<{
+                        purpose: z.ZodString;
+                        alternatives: z.ZodArray<z.ZodObject<{
+                            allOf: z.ZodArray<z.ZodObject<{
+                                scope: z.ZodString;
+                                reason: z.ZodExactOptional<z.ZodString>;
+                            }, z.core.$strict>>;
+                        }, z.core.$strict>>;
+                    }, z.core.$strict>>;
+                    scopeDefinitions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        id: z.ZodString;
+                        label: z.ZodString;
+                        description: z.ZodString;
+                        documentationUrl: z.ZodOptional<z.ZodURL>;
+                    }, z.core.$strict>>>;
+                    frontDoor: z.ZodOptional<z.ZodObject<{
+                        id: z.ZodString;
+                        displayName: z.ZodString;
+                        resourcePicker: z.ZodOptional<z.ZodObject<{
+                            effect: z.ZodEnum<{
+                                selection: "selection";
+                                "resource-grant": "resource-grant";
+                            }>;
+                            mimeTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                            successNote: z.ZodOptional<z.ZodString>;
+                        }, z.core.$strict>>;
+                    }, z.core.$strict>>;
+                    service: z.ZodString;
+                    schemes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    accountSelectors: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                        kind: z.ZodLiteral<"active">;
+                    }, z.core.$strict>, z.ZodObject<{
+                        kind: z.ZodLiteral<"account-id">;
+                        accountId: z.ZodString;
+                    }, z.core.$strict>, z.ZodObject<{
+                        kind: z.ZodLiteral<"record-id">;
+                        recordId: z.ZodString;
+                    }, z.core.$strict>], "kind">>;
+                }, z.core.$strict>>>;
+                storage: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    kind: z.ZodEnum<{
+                        sqlite: "sqlite";
+                        dataDir: "dataDir";
+                    }>;
+                    operations: z.ZodArray<z.ZodEnum<{
+                        open: "open";
+                        read: "read";
+                        write: "write";
+                    }>>;
+                }, z.core.$strict>>>;
+                events: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    event: z.ZodString;
+                    operations: z.ZodArray<z.ZodEnum<{
+                        subscribe: "subscribe";
+                        publish: "publish";
+                    }>>;
+                }, z.core.$strict>>>;
+                endpoints: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    operations: z.ZodArray<z.ZodEnum<{
+                        register: "register";
+                        invoke: "invoke";
+                    }>>;
+                    endpoint: z.ZodString;
+                }, z.core.$strict>>>;
+                webSession: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    origin: z.ZodString;
+                    pathPrefixes: z.ZodArray<z.ZodString>;
+                    csrf: z.ZodOptional<z.ZodObject<{
+                        sourceUrl: z.ZodURL;
+                        selector: z.ZodString;
+                        attribute: z.ZodString;
+                        header: z.ZodString;
+                        bodyField: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strict>>;
+                }, z.core.$strict>>>;
+                knowledgeSearch: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    scope: z.ZodLiteral<"own-schemes">;
+                }, z.core.$strict>>>;
+                knownResources: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    scope: z.ZodLiteral<"own-modules">;
+                }, z.core.$strict>>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    kayAgentUriModules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        claims: z.ZodExactOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"scheme">;
+            scheme: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"uriPattern">;
+            pattern: z.ZodObject<{
+                protocol: z.ZodExactOptional<z.ZodString>;
+                hostname: z.ZodExactOptional<z.ZodString>;
+                pathname: z.ZodExactOptional<z.ZodString>;
+                search: z.ZodExactOptional<z.ZodString>;
+            }, z.core.$strict>;
+            normalizeTo: z.ZodExactOptional<z.ZodString>;
+            route: z.ZodExactOptional<z.ZodString>;
+            sourceUrl: z.ZodExactOptional<z.ZodString>;
+            title: z.ZodExactOptional<z.ZodString>;
+            examples: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"urlPattern">;
+            pattern: z.ZodObject<{
+                protocol: z.ZodExactOptional<z.ZodString>;
+                hostname: z.ZodExactOptional<z.ZodString>;
+                pathname: z.ZodExactOptional<z.ZodString>;
+                search: z.ZodExactOptional<z.ZodString>;
+            }, z.core.$strict>;
+            normalizeTo: z.ZodExactOptional<z.ZodString>;
+            route: z.ZodExactOptional<z.ZodString>;
+            examples: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>], "kind">>>;
+        templates: z.ZodExactOptional<z.ZodArray<z.ZodObject<{
+            uri: z.ZodString;
+            description: z.ZodString;
+            operations: z.ZodExactOptional<z.ZodArray<z.ZodEnum<{
+                search: "search";
+                delete: "delete";
+                list: "list";
+                read: "read";
+                write: "write";
+                help: "help";
+                edit: "edit";
+            }>>>;
+            operationDocs: z.ZodExactOptional<z.ZodRecord<z.ZodEnum<{
+                search: "search";
+                delete: "delete";
+                list: "list";
+                read: "read";
+                write: "write";
+                help: "help";
+                edit: "edit";
+            }> & z.core.$partial, z.ZodString>>;
+            operationDefaults: z.ZodExactOptional<z.ZodRecord<z.ZodEnum<{
+                search: "search";
+                delete: "delete";
+                list: "list";
+                read: "read";
+                write: "write";
+                help: "help";
+                edit: "edit";
+            }> & z.core.$partial, z.ZodEnum<{
+                never: "never";
+                allow: "allow";
+                ask: "ask";
+            }>>>;
+        }, z.core.$strict>>>;
+        verbs: z.ZodExactOptional<z.ZodObject<{
+            readable: z.ZodBoolean;
+            writable: z.ZodBoolean;
+            editable: z.ZodBoolean;
+            deletable: z.ZodExactOptional<z.ZodBoolean>;
+            listable: z.ZodBoolean;
+            searchable: z.ZodExactOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+        verbDocs: z.ZodExactOptional<z.ZodObject<{
+            read: z.ZodExactOptional<z.ZodString>;
+            list: z.ZodExactOptional<z.ZodString>;
+            search: z.ZodExactOptional<z.ZodString>;
+            write: z.ZodExactOptional<z.ZodString>;
+            edit: z.ZodExactOptional<z.ZodString>;
+            delete: z.ZodExactOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        permissionDefaults: z.ZodExactOptional<z.ZodObject<{
+            read: z.ZodExactOptional<z.ZodEnum<{
+                never: "never";
+                allow: "allow";
+                ask: "ask";
+            }>>;
+            write: z.ZodExactOptional<z.ZodEnum<{
+                never: "never";
+                allow: "allow";
+                ask: "ask";
+            }>>;
+            edit: z.ZodExactOptional<z.ZodEnum<{
+                never: "never";
+                allow: "allow";
+                ask: "ask";
+            }>>;
+            delete: z.ZodExactOptional<z.ZodEnum<{
+                never: "never";
+                allow: "allow";
+                ask: "ask";
+            }>>;
+        }, z.core.$strict>>;
+        authActions: z.ZodExactOptional<z.ZodObject<{
+            actions: z.ZodRecord<z.ZodString, z.ZodObject<{
+                purpose: z.ZodString;
+                alternatives: z.ZodArray<z.ZodObject<{
+                    allOf: z.ZodArray<z.ZodObject<{
+                        scope: z.ZodString;
+                        reason: z.ZodExactOptional<z.ZodString>;
+                    }, z.core.$strict>>;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
+            rules: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                action: z.ZodString;
+                operations: z.ZodExactOptional<z.ZodArray<z.ZodEnum<{
+                    search: "search";
+                    delete: "delete";
+                    list: "list";
+                    read: "read";
+                    write: "write";
+                    help: "help";
+                    edit: "edit";
+                }>>>;
+                routes: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
+                query: z.ZodExactOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            }, z.core.$strict>, z.ZodObject<{
+                public: z.ZodLiteral<true>;
+                operations: z.ZodExactOptional<z.ZodArray<z.ZodEnum<{
+                    search: "search";
+                    delete: "delete";
+                    list: "list";
+                    read: "read";
+                    write: "write";
+                    help: "help";
+                    edit: "edit";
+                }>>>;
+                routes: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
+                query: z.ZodExactOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            }, z.core.$strict>]>>;
+        }, z.core.$strict>>;
+        requiresConnection: z.ZodExactOptional<z.ZodLiteral<true>>;
+        acceptsSourceCopy: z.ZodExactOptional<z.ZodLiteral<false>>;
+        acceptsWriteSources: z.ZodExactOptional<z.ZodLiteral<true>>;
+        acceptsBytes: z.ZodExactOptional<z.ZodLiteral<true>>;
+        ownsLineSelectors: z.ZodExactOptional<z.ZodLiteral<true>>;
+        description: z.ZodExactOptional<z.ZodString>;
+        agentHint: z.ZodExactOptional<z.ZodObject<{
+            summary: z.ZodString;
+            commonFlows: z.ZodExactOptional<z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                when: z.ZodExactOptional<z.ZodString>;
+                example: z.ZodString;
+            }, z.core.$strict>>>;
+            helpUri: z.ZodExactOptional<z.ZodString>;
+            triggers: z.ZodExactOptional<z.ZodObject<{
+                keywords: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
+                patterns: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>;
+            skills: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+        localId: z.ZodString;
+        globalId: z.ZodString;
+        schemes: z.ZodArray<z.ZodString>;
+        displayName: z.ZodOptional<z.ZodString>;
+        authServiceId: z.ZodOptional<z.ZodString>;
+        knownResources: z.ZodOptional<z.ZodLiteral<true>>;
+        describesOperations: z.ZodOptional<z.ZodLiteral<true>>;
+    }, z.core.$strict>>>;
+    kayAgentArtifactUriModules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        localId: z.ZodString;
+        globalId: z.ZodString;
+        scheme: z.ZodString;
+        editable: z.ZodBoolean;
+        listable: z.ZodBoolean;
+        deletable: z.ZodBoolean;
+        appendable: z.ZodBoolean;
+        storageScope: z.ZodEnum<{
+            session: "session";
+            family: "family";
+        }>;
+    }, z.core.$strict>>>;
+    kayAgentEntityResolvers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        localId: z.ZodString;
+        globalId: z.ZodString;
+        displayName: z.ZodOptional<z.ZodString>;
+        uriModule: z.ZodString;
+        entityTypes: z.ZodArray<z.ZodString>;
+        uriHint: z.ZodString;
+    }, z.core.$strict>>>;
+    kayAgentGitHostClaims: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        host: z.ZodString;
+        authServiceId: z.ZodString;
+        authSchemeIds: z.ZodArray<z.ZodString>;
+        authServiceDisplayName: z.ZodString;
+        basicAuthUser: z.ZodString;
+    }, z.core.$strict>>>;
+    kayAgentTools: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        displayName: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>>;
+        requiresAuth: z.ZodOptional<z.ZodObject<{
+            serviceId: z.ZodString;
+            schemeId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        permission: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodEnum<{
+                read: "read";
+                mutate: "mutate";
+                destructive: "destructive";
+                execute: "execute";
+            }>;
+            ruleKey: z.ZodOptional<z.ZodString>;
+            resourceArgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+        localId: z.ZodString;
+        globalId: z.ZodString;
+        toolName: z.ZodString;
+    }, z.core.$strict>>>;
+    kayAppTools: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        localId: z.ZodString;
+        globalId: z.ZodString;
+        toolName: z.ZodString;
+    }, z.core.$strict>>>;
+    kayAppApprovalTypes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        localId: z.ZodString;
+        globalId: z.ZodString;
+        kind: z.ZodEnum<{
+            message: "message";
+            change: "change";
+            action: "action";
+            access: "access";
+        }>;
+    }, z.core.$strict>>>;
+    kayAppDataSources: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        localId: z.ZodString;
+        globalId: z.ZodString;
+        scope: z.ZodEnum<{
+            session: "session";
+            runtime: "runtime";
+            account: "account";
+        }>;
+        snapshot: z.ZodObject<{
+            version: z.ZodNumber;
+            schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strict>;
+        change: z.ZodObject<{
+            version: z.ZodNumber;
+            schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            semantics: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"incremental">;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"snapshot-replacement">;
+                maxEncodedBytes: z.ZodNumber;
+                rationale: z.ZodString;
+            }, z.core.$strict>], "kind">>;
+        }, z.core.$strict>;
+        read: z.ZodOptional<z.ZodObject<{
+            request: z.ZodObject<{
+                version: z.ZodNumber;
+                schema: z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>;
+            }, z.core.$strict>;
+            result: z.ZodObject<{
+                version: z.ZodNumber;
+                schema: z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>;
+            }, z.core.$strict>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>;
+    kayAppWhiteboardTypes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        localId: z.ZodString;
+        globalId: z.ZodString;
+        displayName: z.ZodString;
+        schemaVersion: z.ZodNumber;
+        storage: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"json">;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"payload">;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"markdown">;
+            bodyField: z.ZodString;
+        }, z.core.$strict>], "kind">;
+        valueSchema: z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>;
+        presentation: z.ZodOptional<z.ZodObject<{
+            app: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>;
+    kayAppMcpServers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        pluginId: z.ZodString;
+        url: z.ZodString;
+        auth: z.ZodEnum<{
+            oauth: "oauth";
+            "api-key": "api-key";
+            none: "none";
+        }>;
+        authServiceId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    kayAgentConverters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        localId: z.ZodString;
+        globalId: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        mimeTypes: z.ZodArray<z.ZodString>;
+        extensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>>;
+    referencePresentations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        localId: z.ZodString;
+        globalId: z.ZodString;
+        uriModule: z.ZodString;
+        resourceKind: z.ZodString;
+        open: 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">;
+        variants: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            resourceKind: z.ZodString;
+            presentationPluginId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        claims: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            kind: z.ZodLiteral<"urlPattern">;
+            pattern: z.ZodObject<{
+                hostname: z.ZodString;
+                pathname: z.ZodOptional<z.ZodString>;
+                search: z.ZodOptional<z.ZodString>;
+                protocol: z.ZodEnum<{
+                    http: "http";
+                    https: "https";
+                }>;
+            }, z.core.$strict>;
+            brandIcon: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        tooltip: z.ZodOptional<z.ZodObject<{
+            app: z.ZodString;
+            pattern: z.ZodObject<{
+                protocol: z.ZodString;
+                hostname: z.ZodString;
+                pathname: z.ZodOptional<z.ZodString>;
+                search: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>;
+    kayUiApps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        localId: z.ZodString;
+        globalId: z.ZodString;
+        displayName: z.ZodString;
+        contextOnly: z.ZodOptional<z.ZodLiteral<true>>;
+        activityRail: z.ZodOptional<z.ZodObject<{
+            section: z.ZodOptional<z.ZodEnum<{
+                primary: "primary";
+                plugins: "plugins";
+            }>>;
+            order: z.ZodOptional<z.ZodNumber>;
+            icon: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                svg: z.ZodString;
+            }, z.core.$strict>]>>;
+        }, z.core.$strict>>;
+        description: z.ZodOptional<z.ZodString>;
+        icon: z.ZodOptional<z.ZodString>;
+        runtime: z.ZodLiteral<"kay.react-app.v1">;
+        sdk: z.ZodObject<{
+            range: z.ZodString;
+        }, z.core.$strict>;
+        entrypoint: z.ZodObject<{
+            module: z.ZodString;
+            export: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        styles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        assets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        capabilities: z.ZodOptional<z.ZodObject<{
+            endpoints: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                localId: z.ZodString;
+                globalId: z.ZodString;
+            }, z.core.$strict>>>;
+            host: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                "sessions.create": "sessions.create";
+                "memory.read": "memory.read";
+                "skills.read": "skills.read";
+                "automations.run": "automations.run";
+                "artifacts.read": "artifacts.read";
+                "navigation.open-session": "navigation.open-session";
+                "artifacts.preview": "artifacts.preview";
+                "cost.read": "cost.read";
+                "billing.read": "billing.read";
+                "context.read": "context.read";
+                "usage.read": "usage.read";
+                "self-improvement.read": "self-improvement.read";
+                "automations.read": "automations.read";
+                "shared-artifacts.read": "shared-artifacts.read";
+                "workspace.place-pane": "workspace.place-pane";
+                "workspace.pane-header": "workspace.pane-header";
+                "workspace.arrange": "workspace.arrange";
+            }>>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+
+declare type ResolvedPluginContractV1 = z.infer<typeof ResolvedPluginContractV1>;
+
 declare type ResolveExternalCliFailureReason = "not-external-cli" | "no-connection" | "account-ambiguous" | "account-not-found" | "not-authorized" | "host-unavailable";
 
 declare type ResolveExternalCliResult = {
@@ -3683,7 +5610,7 @@ declare type ResolveExternalCliResult = {
 
 /**
  * Derive a stable provider account id (and optional label) from a freshly connected access token,
- * plus — when known — who the account belongs to.
+ * plus - when known - who the account belongs to.
  *
  * A resolver almost always calls the provider's profile endpoint to derive `accountId` at all, so
  * the identity fields are already in the response: return them rather than flattening the person
@@ -3706,7 +5633,7 @@ declare type ResolvePluginAccounts = (accessToken: string) => Promise<readonly {
 declare interface ResolveTokenFailure {
     readonly ok: false;
     readonly reason: ResolveTokenFailureReason;
-    /** Actionable text the wrapper surfaces verbatim to the agent. */
+    /** Actionable text the host surfaces verbatim to the agent. */
     readonly message: string;
     /** When ambiguous, the candidate accounts so the agent can pick one. */
     readonly accounts?: readonly AuthAccount[];
@@ -3719,7 +5646,7 @@ declare type ResolveTokenResult = ResolveTokenSuccess | ResolveTokenFailure;
 
 declare interface ResolveTokenSuccess {
     readonly ok: true;
-    readonly auth: ResolvedAuth;
+    readonly credential: ResolvedCredential;
 }
 
 /** Match remaining characters in the buffer until end. If no characters are in buffer, no match */
@@ -3735,7 +5662,7 @@ declare function ReturnType_2<Type extends TSchema>(type: Type, options?: TSchem
 declare function ReturnTypeDeferred<Type extends TSchema>(type: Type, options?: TSchemaOptions): TReturnTypeDeferred<Type>;
 
 /** Observed cause of a failed request or interrupted run. */
-declare const RUN_FAILURE_REASONS: readonly ["auth", "cancelled", "content_blocked", "context_overflow", "invalid_request", "model_disabled", "model_unavailable", "network", "organization_unavailable", "overloaded", "quota_exhausted", "rate_limit", "runtime_interrupted", "safeguard_block", "seat_unpaid", "server_error", "sign_in_required", "stream_interrupted", "timeout", "unknown"];
+declare const RUN_FAILURE_REASONS: readonly ["account_unreachable", "auth", "cancelled", "content_blocked", "context_overflow", "final_output_missing", "invalid_request", "model_disabled", "model_unavailable", "network", "organization_unavailable", "overloaded", "quota_exhausted", "rate_limit", "runtime_interrupted", "safeguard_block", "seat_unpaid", "server_error", "sign_in_required", "stream_interrupted", "timeout", "unknown"];
 
 declare type RunFailureReason = (typeof RUN_FAILURE_REASONS)[number];
 
@@ -4161,7 +6088,7 @@ declare interface SearchParams {
     readonly query: string;
     /**
      * Pure time filter narrowing results to a window. Providers MUST treat this as
-     * a time filter only — never as a signal to change topic scope, content domain,
+     * a time filter only - never as a signal to change topic scope, content domain,
      * or ranking (oh-my-pi's Tavily `topic=news` coupling silently dropped docs).
      * Providers without temporal filtering MUST ignore it silently.
      */
@@ -4175,7 +6102,7 @@ declare interface SearchParams {
 /**
  * A web search backend behind the single `web_search` tool. Directly analogous
  * to a `UriModule` behind `read`/`write`: registered through `ExtensionApi`,
- * merged per session, dispatched by the registry. Stateless and shareable —
+ * merged per session, dispatched by the registry. Stateless and shareable -
  * per-call context (the abort signal and the {@link SearchProviderContext}) is
  * threaded into `search` and `isAvailable`.
  */
@@ -4191,17 +6118,18 @@ declare abstract class SearchProvider {
      */
     abstract readonly providerId: string;
     /**
-     * The capability⇄scheme binding when this provider resolves its OWN credential through the
+     * The capability<->scheme binding when this provider resolves its OWN credential through the
      * service-extension auth system (stamped by {@link withResolvedSearchProvider}). `undefined`
-     * for providers that reuse inference credentials (the builtins) or need no auth. The runner
-     * reads it to surface the provider in `auth_status` as gated-until-connected, parallel to a
-     * tool's or URI module's `requiresAuth`.
+     * for providers that reuse inference credentials (the builtins) or need no auth. When set, the
+     * host resolves the credential onto {@link SearchProviderContext.credential} before it asks or
+     * calls the provider, and `auth_status` lists the provider as gated-until-connected, parallel to
+     * a tool's or URI module's `requiresAuth`.
      */
     readonly requiresAuth?: RequiresAuth;
     /**
-     * Cheap availability check (typically: does a usable credential resolve?). An own-credential
-     * provider returns `false` until its auth scheme has a connected account, so the chain skips
-     * it gracefully — the gating counterpart to a tool/module's discoverable-but-disallowed state.
+     * Cheap availability check. The host never asks a provider with `requiresAuth` whose credential
+     * did not resolve: it is unavailable, so the chain skips it - the gating counterpart to a
+     * tool/module's discoverable-but-disallowed state.
      */
     abstract isAvailable(ctx?: SearchProviderContext): Promise<boolean> | boolean;
     /** Run the search. Throw {@link SearchProviderError} on a provider failure. */
@@ -4210,15 +6138,16 @@ declare abstract class SearchProvider {
 
 /**
  * Per-call context threaded into a provider's {@link SearchProvider.isAvailable} and
- * {@link SearchProvider.search}. Carries the execute-time auth surface — the SAME
- * `ctx.auth` a tool or URI module receives — scoped to the provider's OWNING extension,
- * so a provider that declares its own credential (an api-key/oauth scheme via the
- * service-extension auth system) can resolve a token. `auth` is absent for builtins
- * (no owning extension; they reuse inference credentials through the host model execution capability)
- * and outside a live session.
+ * {@link SearchProvider.search}.
  */
 declare interface SearchProviderContext {
-    readonly auth?: ExtensionAuthContext;
+    /**
+     * The credential the host resolved for a provider that declares
+     * {@link SearchProvider.requiresAuth}, for the session-active account. The host neither asks
+     * nor calls such a provider when none resolves. Absent for a provider without `requiresAuth`
+     * (builtins reuse inference credentials through the host model execution capability).
+     */
+    readonly credential?: ResolvedCredential;
 }
 
 /** Registry id of a search provider, e.g. `builtin:anthropic`. Open-ended for extensions. */
@@ -4277,19 +6206,19 @@ declare type SelectorDisposition = {
  * rebuilds it on each `AgentSession.reroot` (`@herd/herd-agent`) (the only event that
  * moves `cwd`), then evaluates every tool's predicate against it exactly once per change.
  *
- * **CLOSED-CONTEXT INVARIANT (load-bearing — do not violate when extending this type).** This object
- * carries ONLY primary facts that are *independent of tool availability* — `cwd`, `repoRoot`, and the
+ * **CLOSED-CONTEXT INVARIANT (load-bearing - do not violate when extending this type).** This object
+ * carries ONLY primary facts that are *independent of tool availability* - `cwd`, `repoRoot`, and the
  * planned `mode`/`platform`. It MUST NEVER carry the tool list, the active/effective set, or anything
  * else derived from availability. If a predicate's input could depend on another predicate's output,
  * evaluation would have to reach a fixpoint and could cycle. Because the context is closed, the kernel
  * evaluates each predicate ONCE per context change (one pass, no fixpoint) and caches the result. Keep
  * every future field in this same closed class so the single-pass guarantee survives.
  *
- * Predicates reading this MUST be **pure and synchronous** — same context in ⇒ same answer out, no I/O,
+ * Predicates reading this MUST be **pure and synchronous** - same context in => same answer out, no I/O,
  * no side effects. The host resolves the VCS facts (`repoRoot`); the predicate only inspects them.
  */
 declare interface SessionContext {
-    /** The session's current working directory (the live, re-rootable cwd — not the launch dir). */
+    /** The session's current working directory (the live, re-rootable cwd - not the launch dir). */
     readonly cwd: string;
     /**
      * The enclosing VCS repository root for {@link cwd}, or `null` when `cwd` is not inside a repo.
@@ -4299,6 +6228,10 @@ declare interface SessionContext {
     readonly repoRoot: string | null;
 }
 
+declare const SignedInStatusCode: z.ZodNumber;
+
+declare type SignedInStatusCode = z.infer<typeof SignedInStatusCode>;
+
 /** Matches from Start and End capturing everything in-between. Start and End are consumed. */
 declare function Span<Start extends string, End extends string, MultiLine extends boolean, Input extends string>(start: Start, end: End, multiLine: MultiLine, input: Input): TSpan<Start, End, MultiLine, Input>;
 
@@ -4411,12 +6344,25 @@ declare const StringPattern = ".*";
 /** Creates a Symbol type. */
 declare function Symbol_2(options?: TSchemaOptions): TSymbol;
 
+/** Structurally the plugin SDK's `KayAppSessionEventCause`: only the fields the host reads. */
+declare interface SystemOneCallCause {
+    readonly kind?: "session-event" | "backfill";
+    readonly handler: string;
+    readonly sourceSessionId: string;
+}
+
 declare interface SystemOneCallOptions {
     readonly signal?: AbortSignal;
     /** Bounds the whole call, retries included. */
     readonly timeoutMs?: number;
     /** What the call is for, carried to the host's usage accounting. Never sent to a provider. */
     readonly purpose?: string;
+    /**
+     * The session event a plugin's call answers, so the host charges the call to that session.
+     * The host checks the plugin is handling that session's event right now. Never sent to a
+     * provider.
+     */
+    readonly cause?: SystemOneCallCause;
 }
 
 declare interface SystemOneClient {
@@ -4870,6 +6816,13 @@ declare type TApplyReadonly<Readonly extends TModifierOperation, Type extends T.
 
 declare type TApplyReverse<Types extends TSchema[], Reversed extends boolean> = Reversed extends true ? TReverse<Types> : Types;
 
+declare const TargetEntrypoint: z.ZodObject<{
+    module: z.ZodString;
+    export: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+
+declare type TargetEntrypoint = z.infer<typeof TargetEntrypoint>;
+
 /** Represents an Array type. */
 declare interface TArray<Type extends TSchema = TSchema> extends TSchema {
     '~kind': 'Array';
@@ -6645,7 +8598,7 @@ declare type TOmitInstantiate<Context extends TProperties, State extends TState,
  * classification (the engine records the rejection on an unexplained failure),
  * and a stored record with one reads as none.
  */
-declare const TOOL_CALL_FAILURE_CODES: readonly ["tool.invalid_input", "tool.blocked", "tool.cancelled", "tool.timeout", "tool.not_found", "tool.unavailable", "tool.execution_failed", "provider.http", "provider.api", "provider.transport", "uri.not_found", "uri.unsupported_operation", "uri.not_connected", "uri.auth_unavailable", "permission.denied", "edit.empty_edits", "edit.text_not_found", "edit.text_not_unique", "edit.empty_old_text", "edit.overlapping_edits", "edit.no_change"];
+declare const TOOL_CALL_FAILURE_CODES: readonly ["tool.invalid_input", "tool.blocked", "tool.cancelled", "tool.timeout", "tool.not_found", "tool.unavailable", "tool.execution_failed", "tool.auth_unavailable", "tool.replies_owed", "provider.http", "provider.api", "provider.transport", "uri.not_found", "uri.unsupported_operation", "uri.not_connected", "uri.auth_unavailable", "permission.denied", "edit.empty_edits", "edit.text_not_found", "edit.text_not_unique", "edit.empty_old_text", "edit.overlapping_edits", "edit.no_change"];
 
 /**
  * ---
@@ -6663,14 +8616,14 @@ declare type ToolActionKind = "read" | "mutate" | "destructive" | "execute";
  * A tool's declarative availability gate. `when` is the authoritative predicate the kernel evaluates
  * against the live {@link SessionContext} to decide whether the tool is offered to the model here;
  * `description` is the always-shown, human-readable "why" a UI renders next to a tool the predicate
- * disables (e.g. greyed on the new-session page). The predicate runs in the main process only — a
+ * disables (e.g. greyed on the new-session page). The predicate runs in the main process only - a
  * renderer receives just the resolved `available: boolean` plus this `description`.
  *
  * `when` MUST be pure and synchronous (see {@link SessionContext}); a throw is caught by the kernel,
- * treated as "unavailable", and surfaced as a session diagnostic — it never crashes the tool sync.
+ * treated as "unavailable", and surfaced as a session diagnostic - it never crashes the tool sync.
  */
 declare interface ToolAvailability {
-    /** Pure, synchronous gate. `true` ⇒ the tool may be offered in this context; `false` ⇒ withheld. */
+    /** Pure, synchronous gate. `true` => the tool may be offered in this context; `false` => withheld. */
     when(ctx: SessionContext): boolean;
     /** Human-readable reason the tool is/isn't available, always shown in UI. */
     description: string;
@@ -6698,6 +8651,7 @@ declare const toolCallFailureCauseSchema: z.ZodObject<{
         "not-found": "not-found";
         permission: "permission";
         unavailable: "unavailable";
+        waiting: "waiting";
     }>;
     retryable: z.ZodBoolean;
     action: z.ZodEnum<{
@@ -6706,6 +8660,7 @@ declare const toolCallFailureCauseSchema: z.ZodObject<{
         retry: "retry";
         "correct-input": "correct-input";
         connect: "connect";
+        wait: "wait";
     }>;
     details: z.ZodOptional<z.ZodObject<{
         moduleId: z.ZodOptional<z.ZodString>;
@@ -6714,6 +8669,7 @@ declare const toolCallFailureCauseSchema: z.ZodObject<{
         uri: z.ZodOptional<z.ZodString>;
         path: z.ZodOptional<z.ZodString>;
         validationField: z.ZodOptional<z.ZodString>;
+        validationRule: z.ZodOptional<z.ZodString>;
         errorName: z.ZodOptional<z.ZodString>;
         errorCode: z.ZodOptional<z.ZodString>;
         providerCode: z.ZodOptional<z.ZodString>;
@@ -6728,14 +8684,14 @@ declare type ToolCallFailureCode = (typeof TOOL_CALL_FAILURE_CODES)[number];
 
 /**
  * The neutral around-execution hook: return `next()`'s result (possibly transformed) to run the
- * real tool, or return a result without calling `next()` to substitute one — the tool then never
+ * real tool, or return a result without calling `next()` to substitute one - the tool then never
  * executes. Every downstream consumer (the model, the session log, result clamps, failure
  * attribution) sees whatever is returned exactly as if the tool produced it. Throwing surfaces to
  * the caller as a tool failure, classified like any other.
  *
  * Interceptors compose as middleware: each receives a `next` that runs the REST of the chain, the
  * innermost `next` being the tool itself. `next` may be called at most the caller's own logic
- * demands (zero to short-circuit, once to delegate, more to retry) — the kernel does not police
+ * demands (zero to short-circuit, once to delegate, more to retry) - the kernel does not police
  * arity.
  */
 declare type ToolCallInterceptor = (call: ToolCallInvocation, next: () => Promise<AgentToolResult<unknown>>) => Promise<AgentToolResult<unknown>>;
@@ -6744,7 +8700,7 @@ declare type ToolCallInterceptor = (call: ToolCallInvocation, next: () => Promis
 declare interface ToolCallInvocation {
     readonly toolCallId: string;
     readonly toolName: string;
-    /** The call's arguments, already through `prepareArguments` — the shape `execute` receives. */
+    /** The call's arguments, already through `prepareArguments` - the shape `execute` receives. */
     readonly params: unknown;
     readonly signal: AbortSignal | undefined;
     /**
@@ -6763,7 +8719,7 @@ declare interface ToolCallInvocation {
 
 /**
  * The model the call's result is about to be shown to, as the session holds it at execution
- * time: identity plus pi's `input` list — the SAME field pi's adapters read when they build the
+ * time: identity plus pi's `input` list - the SAME field pi's adapters read when they build the
  * next request, so a capability policy keyed on it agrees with what the provider will accept.
  * Absent when the wrap was built without a resolver; a policy must then treat the capability
  * as unknown, not as absent.
@@ -6798,7 +8754,7 @@ declare type ToolCallPermissionVerdict = {
  * What a tool call ADDRESSES, resolved by the session before execution from facts it already
  * holds for auth scoping: a URI verb's matched module (and the extension that registered it), or
  * an extension-contributed tool's owner. `ownerExtensionId` is absent for builtin/app-owned
- * modules and tools — the session owns those, no extension does. A host policy that keys on
+ * modules and tools - the session owns those, no extension does. A host policy that keys on
  * "which integration is this call about" reads this instead of re-parsing `params`.
  */
 declare type ToolCallTarget = {
@@ -6816,15 +8772,15 @@ declare interface ToolContext {
     readonly cwd: string;
     readonly model: Model<any> | undefined;
     /**
-     * The execute-time auth resolver the SDK tool wrapper (`withResolvedAuth`) reads to resolve a
-     * live token for the active (or per-call-overridden) account. Present when the session is bound
-     * to an `ExtensionAuthRuntime` (`@herd/herd-agent`); absent in always-on contexts
-     * (the wrapper short-circuits with an actionable message when undefined).
+     * The credential the host resolved for this call, for a tool that declares
+     * {@link ToolDefinition.requiresAuth}: the account named by the call's `accountId` argument, else
+     * the session-active one. The host does not call the tool when none resolves. Absent for a tool
+     * without `requiresAuth`, and outside a live session.
      */
-    readonly auth?: ExtensionAuthContext;
+    readonly credential?: ResolvedCredential;
     /**
      * Detached work whose result should re-enter the conversation as a new turn (each completion calls
-     * `nextTurn()` and appears in the Background tasks panel). Not for fire-and-forget side effects —
+     * `nextTurn()` and appears in the Background tasks panel). Not for fire-and-forget side effects -
      * use `ExtensionContext.runEffect`. Absent when the host wires no background-task manager.
      */
     readonly backgroundTasks?: ExtensionBackgroundTasksApi;
@@ -6846,9 +8802,9 @@ declare interface ToolContext {
     /**
      * Re-root the session into `newCwd` mid-run, recomposing the cwd-scoped substrate (builtin tools,
      * the capability registry, the system-prompt project line) in place so subsequent tool calls operate
-     * there — the conversation continues uninterrupted. This is the agent self-reroot seam: the
+     * there - the conversation continues uninterrupted. This is the agent self-reroot seam: the
      * motivating caller is an app tool (e.g. `isolate_worktree`) that does its git ops then calls
-     * `ctx.reroot(worktreePath)` from inside its own `execute`. Safe mid-run — it never gates on idle.
+     * `ctx.reroot(worktreePath)` from inside its own `execute`. Safe mid-run - it never gates on idle.
      * Present only with a live session (absent in session-less inventory/standalone contexts, like
      * {@link auth}). `reason` labels the transition for observability (e.g. `"worktree-isolation"`).
      */
@@ -6889,12 +8845,12 @@ declare interface ToolDefinition<TParams extends ToolParametersWire = ToolParame
     executionMode?: ToolExecutionMode;
     /**
      * How long a single execution may legitimately stay silent (#3785).
-     * - `"fast"` (the default when omitted): the execution is bounded — if it
+     * - `"fast"` (the default when omitted): the execution is bounded - if it
      *   neither settles nor loses the abort race within the fast-tool deadline
      *   (120s), the kernel fails the call with a timeout error the model can
      *   react to. Right for local reads/writes and short network calls, which
      *   finish in seconds or are stuck.
-     * - `"long"`: no deadline — a build under a shell, a parent parked on a
+     * - `"long"`: no deadline - a build under a shell, a parent parked on a
      *   child task. The abort race still applies: a user Stop always wins,
      *   whether or not the tool honors its `signal`.
      * Declare `"long"` only when unbounded silent execution is genuinely part
@@ -6911,29 +8867,29 @@ declare interface ToolDefinition<TParams extends ToolParametersWire = ToolParame
      */
     replaySafe?: true;
     /**
-     * Optional capability⇄scheme binding. When present this tool is auth-gated: discoverable when
-     * unauthed, callable once the binding is satisfied. The SDK's `withResolvedAuth`
-     * stamps this; absent means an ordinary always-on tool (additive — nothing changes for existing
-     * tools that omit it).
+     * Optional capability<->scheme binding. When present this tool is auth-gated: discoverable when
+     * unauthed, callable once the binding is satisfied, and the host resolves its credential onto
+     * {@link ToolContext.credential} before each call. The SDK's `withResolvedAuth` stamps this; absent
+     * means an ordinary always-on tool.
      */
     requiresAuth?: RequiresAuth;
     /**
      * Optional declarative availability gate ({@link ToolAvailability}). When present, the kernel
      * evaluates `availability.when` against the live {@link SessionContext} once per context change
      * (session start + each reroot) and withholds the tool from the model-visible set wherever it
-     * returns `false`. Backward-compatible: **absent ⇒ always available**. Orthogonal to
-     * mode-disallowed sets and to auth/permission gates — availability answers only "does this tool
+     * returns `false`. Backward-compatible: **absent => always available**. Orthogonal to
+     * mode-disallowed sets and to auth/permission gates - availability answers only "does this tool
      * apply in this context", and composes with the others at the same chokepoint.
      */
     availability?: ToolAvailability;
     /**
      * Optional declarative permission classification ({@link ToolPermissionHint}). Consulted by
      * the permission gate ONLY for tools the classifier does not otherwise recognize (extension/app
-     * tools), letting a tool relax the fail-closed `execute` fallback (a pure staging tool → `read`),
+     * tools), letting a tool relax the fail-closed `execute` fallback (a pure staging tool -> `read`),
      * declare its provider `scheme`, derive the `resources` a call touches (a browser
      * navigation's target origin) so per-provider and per-origin rules can gate it.
      * Because it lives on the definition it is
-     * provenance-bound. Backward-compatible: **absent ⇒ the classifier's default (`execute`, no
+     * provenance-bound. Backward-compatible: **absent => the classifier's default (`execute`, no
      * scheme)**.
      */
     permission?: ToolPermissionHint;
@@ -6987,7 +8943,7 @@ declare type ToolParametersWire = unknown;
  * definition (the same shape of author-declared, kernel-read fact as `requiresAuth` and
  * `availability`). Consulted ONLY when the classifier does not otherwise recognize the tool
  * (never overrides `read`/`bash`/URI builtins), so a tool can relax the fail-closed
- * `execute` fallback (e.g. a pure staging tool → `read`) or scope itself for per-provider and
+ * `execute` fallback (e.g. a pure staging tool -> `read`) or scope itself for per-provider and
  * per-origin rules. Because it lives on the registered definition, it is provenance-bound: a
  * tool named the same as another carries its OWN hint, never inherits a first-party one.
  *
@@ -6996,7 +8952,7 @@ declare type ToolParametersWire = unknown;
  * touch protected config must NOT declare `read`. Bonsai's embedded-experience tools never touch
  * `configDir`, so this is safe for them. `read` is also what every capability surface reports as
  * "read-only" (Bonsai's Permissions page groups and defaults on it), so it is a claim about what the
- * tool DOES — never a way to buy silence. A tool that should raise no ask on its own account
+ * tool DOES - never a way to buy silence. A tool that should raise no ask on its own account
  * declares {@link ToolPermissionHint.quiet} and keeps its honest `kind`.
  */
 declare interface ToolPermissionHint {
@@ -7013,8 +8969,8 @@ declare interface ToolPermissionHint {
     readonly ruleKey?: string;
     /**
      * Overrides the ask rail's default human-response window for THIS tool's asks, in ms.
-     * A UX window declaration, not authority: it cannot loosen or tighten what is asked —
-     * kind/ruleKey/scheme/rules/mode all decide that exactly as they would without it —
+     * A UX window declaration, not authority: it cannot loosen or tighten what is asked -
+     * kind/ruleKey/scheme/rules/mode all decide that exactly as they would without it -
      * only how long the prompt waits before it lapses unanswered (`expired`, which the gate
      * already treats as `unanswered`, never `denied`). Bounded use case: a suggestion-shaped
      * tool whose silence means "continue" (e.g. `suggest_compaction`'s 15s ask, chosen to
@@ -7025,26 +8981,26 @@ declare interface ToolPermissionHint {
     /**
      * Derives the resources a call touches from its validated input (e.g. the target origin of
      * a browser navigation). Pure and total; a throw is treated as "no resources" and the call
-     * falls back to the plain classification (fail-closed — never crashes the gate).
+     * falls back to the plain classification (fail-closed - never crashes the gate).
      */
     readonly deriveResources?: (input: Record<string, unknown>) => readonly string[];
     /**
      * Derives a call's classification (`kind`/`ruleKey`/`scheme`) from its validated input, where
      * the static fields above fix them for every call. This is the generalization of
-     * {@link deriveResources} (input → resources) to the rule-matching triple, and of the kernel's
+     * {@link deriveResources} (input -> resources) to the rule-matching triple, and of the kernel's
      * built-in `deriveBashRuleKey` (a bash call's argv sharpens its key) to an author-declared tool.
      *
      * Returns a partial: each present field OVERRIDES the static hint for this call; each absent
      * field (or a wholly `undefined` return) falls back to the static hint, then the fail-closed
      * default. Pure and total; a throw is treated as "no refinement" and the call falls back to the
-     * static hint (fail-closed — never crashes the gate).
+     * static hint (fail-closed - never crashes the gate).
      *
      * It grants no authority the static fields don't already grant: it computes the same
      * kind/ruleKey/scheme the tool could hard-code, per call rather than once. `kind` here matters
      * because the same tool can read on one input and execute on another, which a static `kind`
      * cannot express.
      *
-     * Exemplar — Bonsai's `mcp` proxy tool, one tool spanning every server: `search`/`describe` derive
+     * Exemplar - Bonsai's `mcp` proxy tool, one tool spanning every server: `search`/`describe` derive
      * `{ kind: "read" }` (metadata lookups), while `call` derives
      * `{ kind: "execute", ruleKey: "mcp:<server>::<tool>", scheme: "<server>" }`, so a
      * `{ scheme: "<server>" }` rule gates a whole server and a `{ ruleKey: "mcp:<server>::<tool>" }`
@@ -7061,7 +9017,7 @@ declare interface ToolPermissionHint {
      * deriver is a pure function of its own input and cannot see the target's hint, its service
      * scheme, or the kernel's own recognition of names like `bash` and the URI verbs. Resolution
      * re-enters classification under the target's identity, so a proxied call matches EXACTLY the
-     * rules its direct form would — same kind, same ruleKey, same scheme.
+     * rules its direct form would - same kind, same ruleKey, same scheme.
      *
      * A hop ADDS the target's rules; it never SUBTRACTS the carrier's. The carrier's own
      * classification rides along (`ToolActionPreflight.carrier`) and the controller takes the
@@ -7071,22 +9027,22 @@ declare interface ToolPermissionHint {
      * alone could not.
      *
      * Not consulted at all when the CARRIER is a tool the kernel classifies itself (`bash`, the URI
-     * verbs, the read tools) — the same invariant that governs the rest of this hint. A proxy may
+     * verbs, the read tools) - the same invariant that governs the rest of this hint. A proxy may
      * still freely TARGET one of them.
      *
      * Pure and total. EVERY abnormal outcome falls back to the carrier's own classification, never
      * to an intermediate link: a throw, a malformed return, a blank target name, a non-object input,
      * a cycle, or a chain longer than 4 hops. (Falling back to an intermediate would itself be a
-     * bypass — a crafted 5-link chain could present hop 4's benign classification for a call whose
+     * bypass - a crafted 5-link chain could present hop 4's benign classification for a call whose
      * real target is `bash rm -rf /`.) Only a chain terminating normally, at a tool declaring no
      * further proxy, hops at all.
      *
-     * "Fail-closed" here means the carrier's own classification applies — the identity the call
-     * really had — not that the result is always stricter than the target's. How much gate is left
+     * "Fail-closed" here means the carrier's own classification applies - the identity the call
+     * really had - not that the result is always stricter than the target's. How much gate is left
      * on such a call is exactly how much the CARRIER carries: an `execute` carrier is stricter than
      * a `read` target and equal to a `mutate`/`destructive` one outside allow mode, while a
      * {@link quiet} carrier (Bonsai's own `call_tool`) contributes no mode default at all, so the
-     * fallback leaves nothing but the carrier's rules and the protected-path deny — and the carrier
+     * fallback leaves nothing but the carrier's rules and the protected-path deny - and the carrier
      * names no path, so that deny has nothing to fire on. This is why a carrier must refuse a target
      * that is itself a carrier: no chain long or circular enough to reach the fallback can be built,
      * which is the only thing that keeps the fallback from being toothless. Fail-closed is a
@@ -7097,24 +9053,24 @@ declare interface ToolPermissionHint {
      * Declares that this tool's identity contributes its RULES to the gate but not its MODE
      * DEFAULT. A rule about it still applies in full (a deny denies, an ask asks, an allow
      * allows) and the protected-path hard-deny still fires; what is withheld is the verdict the
-     * MODE would reach from `kind` alone — default/ask mode's "anything but a read asks".
+     * MODE would reach from `kind` alone - default/ask mode's "anything but a read asks".
      *
      * It is a statement about this identity's CONTRIBUTION, never about what the call does.
      * `kind` stays the honest declaration of the strongest effect a call can have, and a quiet
-     * tool declares it exactly as loudly as a noisy one — which is the whole point: buying
+     * tool declares it exactly as loudly as a noisy one - which is the whole point: buying
      * silence with `kind: "read"` instead moves the call below the protected-path hard-deny and
      * reports the tool as read-only on every capability surface.
      *
      * It exists for a PROXY CARRIER ({@link deriveProxiedCall}), and is honest only for a tool
      * whose only effect is invoking the target the gate is already classifying beside it: the
      * target's kind, rules, resources and the protected-path deny all still decide, so a proxied
-     * call is gated exactly like the direct one — no more, and no ask the direct call would never
+     * call is gated exactly like the direct one - no more, and no ask the direct call would never
      * have raised. Bonsai's `call_tool` declares `{ kind: "execute", quiet: true }` (owner ruling,
      * 2026-08-18): honest about everything it can reach, silent on its own account.
      *
      * Quiet is not ungated, but it IS nearly all the gate a lone carrier has. On a call that
      * classifies as the carrier because no hop resolved (a cycle, an over-long chain), a quiet
-     * carrier leaves only its own rules — see {@link deriveProxiedCall}'s fail-closed paragraph
+     * carrier leaves only its own rules - see {@link deriveProxiedCall}'s fail-closed paragraph
      * for why a carrier must therefore refuse a carrier as a target.
      */
     readonly quiet?: boolean;
@@ -8317,32 +10273,43 @@ declare interface UriAgentHint {
     readonly triggers?: UriHintTriggers;
     /**
      * Skill invocation names (flat `localId`s, e.g. `"gmail-email-triage"`) that hold this module's
-     * deeper workflow judgment — the name a `read skill://<name>` dispatch resolves, not a display
+     * deeper workflow judgment - the name a `read skill://<name>` dispatch resolves, not a display
      * title or a path. Point here only at skills that actually exist in the composed skill roster;
      * a dangling name sends the agent to a `skill://` read for nothing.
      */
     readonly skills?: readonly string[];
 }
 
-declare type UriAuthActionClassification = {
-    readonly kind: "action";
-    readonly actionId: string;
-} | {
-    readonly kind: "public";
-};
-
 /**
- * Finite authorization actions plus the pure route classifier that selects one before dispatch.
- * An exception, an unknown action id, or `undefined` classification fails closed in the host.
+ * Finite authorization actions plus the rules that select one before dispatch. A call no rule
+ * matches, or a rule naming an action that is not in `actions`, fails closed in the host.
  */
 declare interface UriAuthActionPolicy {
     readonly actions: Readonly<Record<string, ScopeRequirement>>;
-    classifyOperation(request: {
-        readonly operation: UriOperation;
-        readonly uri: string;
-    }): UriAuthActionClassification | undefined;
+    /** Absent matches no call, so every call fails closed. */
+    readonly rules?: readonly UriAuthActionRule[];
 }
 
+/**
+ * One row of a module's sign-in action rules: which calls need which action. A row matches a call
+ * when every condition it names holds; a condition it leaves out matches anything. The first
+ * matching row decides, so a row with no conditions at the end means "everything else".
+ */
+declare type UriAuthActionRule = {
+    /** The verbs this row covers. */
+    readonly operations?: readonly UriOperation[];
+    /** The claim `route` ids this row covers, matched against the call's address. */
+    readonly routes?: readonly string[];
+    /** Query parameters the address must carry with exactly these values (`{ permanent: "true" }`). */
+    readonly query?: Readonly<Record<string, string>>;
+} & ({
+    /** The {@link UriAuthActionPolicy.actions} entry the call needs. */
+    readonly action: string;
+} | {
+    /** The call needs no credential. */
+    readonly public: true;
+});
+
 declare interface UriAuthRef {
     readonly serviceId: string;
     readonly schemeId: string;
@@ -8364,7 +10331,7 @@ declare interface UriAuthRequirement {
      */
     readonly requiredScopes?: readonly string[];
     /**
-     * The service id connect guidance should NAME when this module is gated — a host-composed
+     * The service id connect guidance should NAME when this module is gated - a host-composed
      * front door whose connect grants exactly this module's scopes (e.g. `gmail` expanding onto
      * the shared `google.account` credential). Guidance only; resolution keys on
      * `(serviceId, schemeId)`. Absent, guidance names `serviceId`.
@@ -8410,6 +10377,21 @@ declare type UriCachePolicyResolver = (operation: UriOperation, cacheUri: string
 
 declare type UriClaim = UriSchemeClaim | UriPatternClaim | UrlPatternClaim;
 
+/**
+ * A URL with `:name` placeholders for the claim's captures. Each capture is escaped for where it
+ * lands: lowercased in the host, one path segment (a `:name*` capture keeps its `/`), or a query
+ * or fragment value. `{transform(...)}` runs one named, built-in transform over the text inside
+ * it, captures pasted in unescaped, and escapes the output for where it lands:
+ *
+ * - `base64`: unpadded base64 of the UTF-8 text (`{base64(:id :calendar)}`).
+ * - `slackTimestamp`: a Slack archive message token as the API's timestamp
+ *   (`p1783350000000100` becomes `1783350000.000100`).
+ *
+ * A transform that cannot read its input fills nothing. A claim whose `normalizeTo` fills nothing
+ * does not match; a `sourceUrl` that fills nothing paints no link.
+ */
+declare type UriClaimTemplate = string;
+
 declare interface UriCommonFlow {
     readonly label: string;
     readonly when?: string;
@@ -8459,41 +10441,28 @@ declare interface UriExample {
     readonly operation?: UriOperation;
 }
 
-declare interface UriExtensionModule extends Omit<UriModule, "verbs"> {
+/**
+ * A plugin's URI module. Its claims route, spell and describe its addresses, so it has no
+ * `matches`, `normalize` or `describe`. It also has no `fallback` (a plugin's addresses are always
+ * claimed) and no `locate` (a plugin has no file on disk for the daemon to open).
+ */
+declare interface UriExtensionModule extends Omit<UriModule, "verbs" | "normalize" | "matches" | "describe" | "fallback" | "locate"> {
     readonly verbs: UriVerbSupport;
     /** Human-facing per-verb effect docs; see {@link UriVerbDocs}. */
     readonly verbDocs?: UriVerbDocs;
     /**
      * Plugin-declared default permission per verb group. A verb group set to `"ask"`
-     * compiles into a defaults-level ask rule — the user is prompted by default but can
+     * compiles into a defaults-level ask rule - the user is prompted by default but can
      * override with an explicit allow. Undeclared = `"allow"` (fail-open).
      * See {@link UriPermissionDefaults}.
      */
     readonly permissionDefaults?: UriPermissionDefaults;
     /** Requires a resolved URI connection before any verb handler runs. */
     readonly requiresConnection?: boolean;
-    /** Pure route-aware permission facts; see {@link UriExtensionOperationPermissionPolicy}. */
-    readonly permission?: UriExtensionOperationPermissionPolicy;
     /** False rejects generic write-tool `source` copies before source fetch. */
     readonly acceptsSourceCopy?: boolean;
 }
 
-declare interface UriExtensionOperationPermissionPolicy {
-    /**
-     * Classify one canonical route, purely. `write`/`edit`/`delete` may only be made stricter
-     * than the verb default; `help`/`read`/`list`/`search` must stay `"read"` (a `ruleKey` is
-     * allowed), because the kernel reruns a crash-interrupted read without asking again. Any
-     * other answer, or a throw, fails the call closed.
-     */
-    classifyOperation(request: {
-        readonly operation: UriOperation;
-        readonly uri: string;
-    }): {
-        readonly kind: "read" | "mutate" | "destructive" | "execute";
-        readonly ruleKey?: string;
-    } | undefined;
-}
-
 declare interface UriExternalCliRunner {
     readonly run: (request: UriExternalCliRunRequest) => Promise<UriExternalCliRunResult>;
 }
@@ -8528,6 +10497,8 @@ declare interface UriHelp {
      * than text the module's author wrote. Absent: the module's own text.
      */
     readonly thirdPartyContent?: true;
+    /** The module's own markdown for this result, shown instead of the host's default rendering. */
+    readonly markdown?: string;
 }
 
 declare interface UriHintTriggers {
@@ -8567,6 +10538,12 @@ declare interface UriListResult {
     readonly items: readonly UriListItem[];
     readonly nextCursor?: string;
     readonly metadata?: UriListMetadata;
+    /** How long the host may cache this result; see {@link UriCachePolicy.ttlMs}. */
+    readonly cachePolicy?: Pick<UriCachePolicy, "ttlMs">;
+    /** The module's own markdown for this result, shown instead of the host's default rendering. */
+    readonly markdown?: string;
+    /** The touched resource's name for the transcript row, as on `RawResource.label`. */
+    readonly label?: UriResourceLabel;
 }
 
 declare type UriLocateContext = Pick<UriResolveContext, "cwd" | "signal" | "connection" | "sessionId" | "paths"> & {
@@ -8584,31 +10561,13 @@ declare type UriLocateResult = {
     readonly kind: "not-disk-backed";
 };
 
-declare type UriMarkdownRenderInput = {
-    readonly operation: "help";
-    readonly uri: string;
-    readonly result: UriHelp;
-} | {
-    readonly operation: "list";
-    readonly uri: string;
-    readonly result: UriListResult;
-} | {
-    readonly operation: "search";
-    readonly uri: string;
-    readonly result: UriSearchResult;
-} | {
-    readonly operation: Extract<UriOperation, "write" | "edit" | "delete">;
-    readonly uri: string;
-    readonly result: UriMutationResult;
-};
-
 declare interface UriModule {
     readonly id: string;
     /**
      * Explicit human-readable name for catalog/display purposes (the plugin
      * manifest's `contributes.uriModules[].displayName`, threaded through by
-     * hand since there is no automatic manifest→runtime-module composition
-     * step). Falls back to a mechanical id-derived title when absent — see
+     * hand since there is no automatic manifest->runtime-module composition
+     * step). Falls back to a mechanical id-derived title when absent - see
      * `uriCatalogTitle`.
      */
     readonly title?: string;
@@ -8628,14 +10587,26 @@ declare interface UriModule {
      * calls `parseLineSelector` itself and reports what it did through `RawResource.selector`.
      */
     readonly ownsLineSelectors?: boolean;
+    /** Opt in to host-resolved supplementary sources; absent means unsupported. */
+    readonly acceptsWriteSources?: boolean;
+    /**
+     * Opt in to raw bytes as `write`'s content; absent means text and JSON only. The `write`
+     * tool's `source` copy leg is the only producer: a provider's binary resource (an attachment,
+     * an image, a PDF) reaches a module that declares this as a `Uint8Array`, never decoded into
+     * the model's context, and a binary copy to any other module is refused before it runs.
+     */
+    readonly acceptsBytes?: boolean;
     readonly claims?: readonly UriClaim[];
+    /**
+     * The routes the module's scheme-root `help` lists, as data, so a host can list them without
+     * calling `help`.
+     */
+    readonly templates?: readonly UriTemplate[];
     /** Migration-only prompt summary until structured help/catalog coverage replaces prose. */
     readonly description?: string;
     readonly agentHint?: UriAgentHint;
     readonly requiresAuth?: UriAuthRequirement;
     readonly authActions?: UriAuthActionPolicy;
-    /** Pure route/payload validation applied before a consequential permission ask. */
-    readonly preflight?: UriOperationPreflightPolicy;
     /**
      * Structured facts for approval surfaces, or `undefined` when unavailable.
      * A one-line description must name the whole consequence; `preview` instead
@@ -8645,120 +10616,46 @@ declare interface UriModule {
      * of covered payload fields and query parameters. Unknown fields cost the summary.
      * The host owns framing, the whole-quote fit (no elision) and display-safety admission.
      *
-     * Unlike preflight, this hook is async and may do I/O. Resolve names through `ctx`,
+     * This hook is async and may do I/O. Resolve names through `ctx`,
      * the same dispatch context used by execution, never an ambient or cached account. A name
      * the module resolved under that account may be cached for a bounded time, keyed by that
      * account's identity and never answered to another account or after a failed lookup.
-     * The host calls it once before raising the ask, enforces the short `ctx.signal`
-     * deadline and discards late answers. A throw yields no summary and a module-attributed
-     * diagnostic; declining costs a click into the app, never an under-described approval.
-     */
-    describeOperation?(request: {
-        readonly operation: UriOperation;
-        readonly uri: string;
-        readonly payload: unknown;
-    }, ctx: UriResolveContext): Promise<UriOperationDescription | undefined>;
-    /**
-     * Rebuild a call from the person's "Allow with edits" answer: the same payload
-     * {@link describeOperation} was given, with the values the person typed into the preview's
-     * `editable` fields put in their place. Implement it beside any preview that marks a field
-     * `editable`; without it the host drops every editable marker from that module's previews, so
-     * a field is never offered for editing that cannot be honoured.
-     *
-     * Pure and fast: it must not send, write or otherwise act, and it should not do I/O (it gets
-     * the dispatch context `ctx` only so a name can be resolved the way `describeOperation` does).
-     * Return the COMPLETE amended payload in the shape the module's own handler reads. Validate it
-     * with the handler's own schema, so an amended call is exactly as valid as one the model made.
-     * Decline by returning `undefined` or throwing; either denies the call with nothing done.
-     *
-     * The host calls it once, after the person allowed the call, never for a denial, and only for
-     * a `write` whose payload this module described. The kernel passes the `edits` through
-     * unchanged. Bonsai's daemon has already refused, before the ask settled, a key that is not an
-     * `editable` field of the preview it showed, a repeated key, a blank value and a value past the
-     * field's `maxLength`, but another host may not, so refuse each of those here yourself (return
-     * `undefined`).
+     * The host calls it once before raising the ask and waits for the answer, with no deadline;
+     * `ctx.signal` fires when the host stops waiting (the session closes, or a caller gives up),
+     * and a late answer is discarded. A throw yields no
+     * summary and a module-attributed diagnostic; declining costs a click into the app, never an
+     * under-described approval.
      *
-     * The host then holds the amended call to what the person was shown, in two steps, and runs it
-     * only if both pass. It classifies the amended call again and requires the same tool, rule key,
-     * kind, resources, scheme and target address, so an edit cannot reach a different route. It then
-     * calls {@link describeOperation} on the amended call and requires that preview to read exactly
-     * as the one the person saw, apart from the values of the fields they edited: the same title, the
-     * same fields in the same order, each with the same label, key, `editable` marker and
+     * "Allow with edits": a field marked `editable` may be rewritten by the person on the card.
+     * The host rebuilds the call itself (see the field's `editable`), then holds the rebuilt call to
+     * what the person was shown, in two steps, and runs it only if both pass. It classifies the
+     * rebuilt call again and requires the same tool, rule key, kind, resources, scheme and target
+     * address. It then calls this hook on the rebuilt call and requires that preview to read exactly
+     * as the one the person saw, apart from the values of the fields they edited: the same title,
+     * the same fields in the same order, each with the same label, key, `editable` marker and
      * `maxLength`, and every read-only field with the same value. Anything else refuses the call
-     * with nothing done: a mismatch, and also a describer that is missing, declines, throws or
-     * overruns its deadline. The `description` line is not compared.
-     *
-     * So rebuild from the original payload and change only the fields you offered. A recipient, a
-     * thread or an attachment list that an amendment changed is caught by the second step, but only
-     * where the preview shows it: put whatever says where a call goes, or what it does beyond its
+     * with nothing done: a mismatch, and also an answer of `undefined` or a throw. The `description`
+     * line is not compared. So put whatever says where a call goes, or what it does beyond its
      * editable fields, in the preview's `title` or a field, never only in its `description`, and
      * keep recipients, destinations and thread bindings out of `editable` fields.
      */
-    amendOperation?(request: {
+    describeOperation?(request: {
         readonly operation: UriOperation;
         readonly uri: string;
         readonly payload: unknown;
-        readonly edits: readonly UriPreviewEdit[];
-    }, ctx: UriResolveContext): Promise<UriOperationAmendment | undefined>;
-    /**
-     * A short, render-only name for the resource a settled call on `request.uri` touched, which the
-     * host stamps on the tool result's `details` so a transcript row can name it where it would
-     * otherwise print the address (`#lane-analytics` and `thread`, not a channel id). Answer
-     * `undefined` for any address you cannot honestly name.
-     *
-     * Called once per successful URI verb call, AFTER the verb handler has returned, with the same
-     * dispatch context. Resolve names through `ctx` and nothing else, and prefer a cache your own
-     * verb handlers warm, keyed by the executing account: a name one account saw is never answered
-     * to another, and a failed, blank or aborted lookup is never cached. The host bounds the wait
-     * (a finished result is held at most a quarter of a second), gives `ctx.signal` a hard deadline,
-     * and drops a late, thrown or refused answer without failing the call; a throw is reported as a
-     * module-attributed diagnostic. The label is a label, never an identity: the address remains the
-     * click target, hover text and accessible name. It is UI-only, so it never enters the tool
-     * result's content and no telemetry reads it.
-     *
-     * Unlike `describeOperation` this is not an approval surface: it carries no consequence, no
-     * quote and no coverage claim, and nothing may gate a permission on it.
-     */
-    labelResource?(request: UriResourceLabelRequest, ctx: UriResolveContext): Promise<UriResourceLabel | undefined>;
-    /**
-     * Per-resource observability: does a `format: "observation"` read of THIS
-     * uri render source-native material ({@link UriResolveContext.format})?
-     * Route-parse only — cheap, side-effect-free, no I/O, no auth (the same
-     * discipline as `matches`); a throw is treated as `false`. Returning true
-     * is the resource's contract that its observation read returns an
-     * observation render and that failures under that format throw typed,
-     * status-bearing errors rather than resolving a friendly fallback page.
-     * The kernel stamps the answer onto the resource's access events, which is
-     * what ambient index consumers replay on — so "PRs are observable" is
-     * declared here, route by route, never module-wide. Absent means no read
-     * of this module is observable. A vendor's own gone-vocabulary (HTTP 410,
-     * a 200-body "ok:false"/"archived:true"/"status:cancelled", or a
-     * 403/404-ambiguous lost-access response) is this module's job to
-     * translate into `UriNotFoundError` or a `status: 404` error under the
-     * observation format — the fold that retires a doc never learns vendor
-     * vocabulary (see `ObservationMaterial`'s doc comment).
-     */
-    observes?(uri: string): boolean;
-    /**
-     * Head-only revision probe: the resource's CURRENT source-native revision
-     * without fetching its body, or `undefined` when that cannot be known
-     * cheaply. The host calls it before a repeat `read` of an address the
-     * session already holds, with `ctx.expectedRevision` set to the revision
-     * that read reported (`RawResourceMetadata.revision`); a value equal to it
-     * means "unchanged" and the fetch is skipped, anything else falls through
-     * to the ordinary read. A module whose read revision embeds more than the
-     * head can know (a content digest beside a stat stamp) may answer relative
-     * to `expectedRevision` — return it when the cheap part matches, `undefined`
-     * when it does not — but must never return a value it has not verified.
-     * `undefined` is always safe: it costs one fetch, never a wrong answer.
-     * Must be cheaper than the read (a metadata request, a `stat`); a throw is
-     * treated as `undefined`.
-     */
-    revision?(uri: string, ctx: UriResolveContext): Promise<string | undefined>;
+    }, ctx: UriResolveContext): Promise<UriOperationDescription | undefined>;
     readonly getCachePolicy?: UriCachePolicyResolver;
-    /** Retained matching escape hatch; future dispatch should prefer compiled claims. */
-    matches(input: string, ctx: UriResolveContext): boolean;
+    /**
+     * Code matching, for the host's own modules whose addresses no claim can describe (a bare file
+     * path). A plugin module has none; it routes through its `claims` alone.
+     */
+    matches?(input: string, ctx: UriResolveContext): boolean;
+    /** The official spelling, for the host's own modules; a plugin's comes from its claims' `normalizeTo`. */
     normalize?(input: string, ctx: UriResolveContext): UriNormalizeResult | undefined;
+    /**
+     * The pill's title and link, for the host's own modules only; a plugin module has none, and its
+     * pill comes from its claims' `title` and `sourceUrl`.
+     */
     describe?(input: string, ctx: UriDescribeContext): UriResourceDescription | undefined;
     locate?(input: string, ctx: UriLocateContext): Promise<UriLocateResult>;
     /**
@@ -8771,33 +10668,21 @@ declare interface UriModule {
     read(input: string, ctx: UriResolveContext): Promise<RawResource>;
     /** Observes only; see {@link read}. */
     help?(input: string, ctx: UriResolveContext): Promise<UriHelp>;
-    write?(input: string, content: UriPayload, ctx: UriResolveContext): Promise<UriMutationResult | void>;
-    /** Opt-in structured write with one or more host-resolved resources delivered beside the content. */
-    writeWithSources?(input: string, content: UriPayload, sources: readonly UriWriteSource[], ctx: UriResolveContext): Promise<UriMutationResult | void>;
-    /**
-     * Opt-in byte sink: write RAW BYTES to this address, no UTF-8 round trip.
-     * `UriPayload` is text/JSON by contract, so a module that can store bytes
-     * declares it here instead of stretching `write`. The only caller today is
-     * the `write` tool's `source` copy leg, which is how a provider's binary
-     * resource — a Gmail attachment, an image, a PDF, a zip — reaches a
-     * byte-capable destination without ever being decoded into the model's
-     * context. A module that omits it is text-only, and a binary copy targeting
-     * it is refused with an error naming a byte-capable destination.
-     *
-     * `source` describes what the bytes are: a filesystem-backed sink can ignore
-     * it (the target path already carries the name), while a remote provider
-     * sink needs it to name and type the stored file. It sits before `ctx` so a
-     * forwarding wrapper that fails to thread it is a compile error, not a
-     * silent drop.
+    /**
+     * `sources` is empty for ordinary writes; populated only with `acceptsWriteSources: true`.
+     * `content` is a `Uint8Array` only with `acceptsBytes: true`, and then `ctx.writeSource`
+     * names and types it. It is `undefined` when the call carried neither `content` nor `source`.
+     * The module decides what that means: a route that takes no body (a folder
+     * create) proceeds, and a route that needs one refuses with an error naming
+     * what is missing. Never treat it as empty content.
      */
-    writeBytes?(input: string, bytes: Uint8Array, source: UriSourceDescriptor, ctx: UriResolveContext): Promise<UriMutationResult | void>;
+    write?(input: string, content: UriPayload | Uint8Array | undefined, sources: readonly UriWriteSource[], ctx: UriResolveContext): Promise<UriMutationResult | void>;
     edit?(input: string, patch: UriPayload, ctx: UriResolveContext): Promise<UriMutationResult>;
     /** Observes only; see {@link read}. */
     list?(input: string, params: UriListParams, ctx: UriResolveContext): Promise<UriListResult>;
     /** Observes only; see {@link read}. */
     search?(input: string, params: UriSearchParams, ctx: UriResolveContext): Promise<UriSearchResult>;
     delete?(input: string, ctx: UriResolveContext): Promise<UriMutationResult>;
-    toMarkdown?(input: UriMarkdownRenderInput, ctx: UriResolveContext): string | undefined;
 }
 
 /** Authoritative lifecycle facts for a successful record-like URI mutation. */
@@ -8823,6 +10708,12 @@ declare interface UriMutationResult {
     readonly receipt?: UriMutationReceipt;
     /** Opaque source-native revision after this successful mutation. */
     readonly revision?: string;
+    /** Cached reads this mutation made stale; see {@link UriCachePolicy.invalidate}. */
+    readonly cachePolicy?: Pick<UriCachePolicy, "invalidate">;
+    /** The module's own markdown for this result, shown instead of the host's default rendering. */
+    readonly markdown?: string;
+    /** The touched resource's name for the transcript row, as on `RawResource.label`. */
+    readonly label?: UriResourceLabel;
 }
 
 declare interface UriNodeCapability {
@@ -8843,11 +10734,6 @@ declare interface UriNormalizeResult {
 
 declare type UriOperation = "help" | "read" | "write" | "edit" | "list" | "search" | "delete";
 
-/** The call {@link UriModule.amendOperation} rebuilt: the whole payload, in the shape the module reads. */
-declare interface UriOperationAmendment {
-    readonly payload: unknown;
-}
-
 declare interface UriOperationDescription {
     /** Static verb phrase authored by the module. Never interpolated from input. */
     readonly action: string;
@@ -8870,9 +10756,11 @@ declare interface UriOperationDescription {
              */
             readonly key?: string;
             /**
-             * `true` offers this field to the person for editing on the approval card. Offer it only
-             * when the module implements {@link UriModule.amendOperation} for this call and can honour
-             * any value within `maxLength`; the host drops the offer otherwise. Absent means read-only.
+             * `true` offers this field to the person for editing on the approval card. The host applies
+             * an edit itself: it copies the payload and replaces the value of the top-level string
+             * property named `key`. So offer a field only when the payload is an object, `key` is one
+             * of its string properties, and the module would send any value within `maxLength` as it
+             * sends the model's; the host drops the offer otherwise. Absent means read-only.
              */
             readonly editable?: true;
             /** Longest edited value, in UTF-16 code units. Meaningful only with `editable`. */
@@ -8890,56 +10778,6 @@ declare interface UriOperationDescription {
     };
 }
 
-/**
- * Pure, route-aware validation that runs before permission policy can surface an ask.
- *
- * This is deliberately narrower than execution: it receives only the canonical URI,
- * operation, and operation payload, performs no I/O, and returns a user-actionable
- * rejection for calls that the module already knows cannot succeed. The handler must
- * still validate again when it executes because approval is not an authority boundary.
- */
-declare interface UriOperationPreflightPolicy {
-    /**
-     * The rejection half. Optional since kay#7684: a module whose only preflight
-     * fact is affirmative (`acceptsPayloadlessWrite`) must not have to stub a
-     * validator that never rejects.
-     */
-    validateOperation?(request: {
-        readonly operation: UriOperation;
-        readonly uri: string;
-        readonly payload: unknown;
-    }): string | undefined;
-    /**
-     * Route-level affirmative: may a `write` to this URI carry NO payload at all
-     * — neither `content` nor `source`? (The canonical case is folder creation,
-     * e.g. `?type=folder`.) The write tool's generic shape rule requires exactly
-     * one payload form; a route answers `true` here when a payloadless write is
-     * meaningful FOR THAT ROUTE, and the rule then admits the call.
-     *
-     * This exists because an empty body is not always sendable: on some
-     * model/provider paths a top-level empty-string argument (`content: ""`)
-     * never reaches the host — the key arrives absent, indistinguishable from an
-     * omitted argument (kay#7684). A contract that can only be invoked with an
-     * empty string is unreachable on those paths, so a route whose write is
-     * meaningful with no body must declare it and let the caller omit the
-     * payload instead.
-     *
-     * Pure and side-effect-free like {@link validateOperation}: route-parse
-     * only, no I/O. A throw NEVER admits the write, but the two consult paths
-     * disagree on purpose about what happens next: pre-ask (permission
-     * resolution, which must never crash the gate) answers no and records a
-     * module-attributed diagnostic; at execute time the write tool asks only
-     * when the call genuinely carries no payload, and a throw there is the
-     * module's own bug surfacing as the call's error — louder than a misleading
-     * \"provide exactly one of content or source\" the model could never
-     * satisfy. Absent means no route of this module accepts a payloadless
-     * write.
-     */
-    acceptsPayloadlessWrite?(request: {
-        readonly uri: string;
-    }): boolean;
-}
-
 declare interface UriParameter {
     readonly name: string;
     readonly in: "uri" | "query" | "selector";
@@ -8949,29 +10787,60 @@ declare interface UriParameter {
     readonly examples?: readonly unknown[];
 }
 
+/**
+ * A claim on a module's own custom-scheme addresses. The pattern matches with or without an
+ * account prefix: `gcal://@work/events/x` is matched as `gcal://events/x`, and the prefix is put
+ * back on the official spelling, so one claim covers both spellings.
+ */
 declare interface UriPatternClaim {
     readonly kind: "uriPattern";
     readonly pattern: UriPatternInit;
     /**
-     * Canonical spelling rebuilt from the captures. When the template keeps the
-     * input's scheme (the module's own addressing), the input's query string is
+     * Canonical spelling rebuilt from the captures (see {@link UriClaimTemplate}). When the template
+     * keeps the input's scheme (the module's own addressing), the input's query string is
      * carried over verbatim so a route flag such as `?permanent=true` survives
      * canonicalization (kay#7859); a template that re-targets to another scheme
      * (a projection to a web link) drops it, as does a pattern that consumed the
      * query itself or a template that spells its own.
      */
-    readonly normalizeTo?: string;
+    readonly normalizeTo?: UriClaimTemplate;
+    /**
+     * Names the route this claim matches, so data keyed by route (a module's sign-in action rules)
+     * can say which addresses it means. Several claims may name the same route.
+     */
+    readonly route?: string;
+    /**
+     * The web page a matched address opens, filled from the captures (see
+     * {@link UriClaimTemplate}). The host matches an address's official spelling and paints its
+     * reference with the source URL of the first matching claim that declares one.
+     */
+    readonly sourceUrl?: UriClaimTemplate;
+    /**
+     * The name a matched address's reference shows: literal text, with each `:name` replaced by
+     * that capture as decoded (`"Flow :flow"`, or a fixed `"BFS"`). The first matching claim that
+     * declares one names the address.
+     */
+    readonly title?: string;
     readonly examples?: readonly string[];
 }
 
 declare interface UriPatternInit {
     readonly protocol?: string;
+    /**
+     * Dot-delimited host pattern. A pattern that is one capture (`:owner`) takes the whole host,
+     * dots included, as a `github://some.org/repo` owner must.
+     */
     readonly hostname?: string;
     /**
      * Slash-delimited path pattern. A final capture may use `:name*` to consume
-     * the remaining path segments, preserving `/` in the captured value.
+     * the remaining path segments, preserving `/` in the captured value. Unless the pattern itself
+     * ends in `/`, an input path ending in one `/` matches as if the slash were absent, so
+     * `threads/t1/` is `threads/t1` (captures and official spelling included) and a lone `/` after a
+     * host is the empty path; a doubled `//` is never dropped, nor the root path of an address with
+     * no host (`bfs:///`).
      */
     readonly pathname?: string;
+    /** `&`-delimited query pattern; `""` matches only an address with no query. */
     readonly search?: string;
 }
 
@@ -8990,7 +10859,7 @@ declare interface UriPayloadContract {
 
 /**
  * The three-state permission vocabulary a plugin declares for its default permissions.
- * Maps to `PermissionRule.effect`: `allow` → allow, `ask` → ask, `never` → deny.
+ * Maps to `PermissionRule.effect`: `allow` -> allow, `ask` -> ask, `never` -> deny.
  */
 declare type UriPermissionDefault = "allow" | "ask" | "never";
 
@@ -9008,19 +10877,6 @@ declare interface UriPermissionDefaults {
     readonly delete?: UriPermissionDefault;
 }
 
-/**
- * One change a person made to an `editable` field of a call's action preview ("Allow with
- * edits"): the field's `key` and the value they want it to hold. Values are message content, so
- * a module must not log or persist them.
- */
-declare interface UriPreviewEdit {
-    readonly key: string;
-    readonly value: string;
-}
-
-/** The read shape a caller may request via {@link UriResolveContext.format}. */
-declare type UriReadFormat = "observation";
-
 declare interface UriResolveContext {
     readonly cwd: string;
     readonly signal?: AbortSignal;
@@ -9029,8 +10885,8 @@ declare interface UriResolveContext {
     readonly auth?: UriResolvedAuth;
     /**
      * Id of the session dispatching this call, stamped by the host at the dispatch site.
-     * It never originates from anything the caller can influence — no verb argument, no write
-     * body — so a module may treat it as trustworthy caller identity and stamp it onto writes.
+     * It never originates from anything the caller can influence - no verb argument, no write
+     * body - so a module may treat it as trustworthy caller identity and stamp it onto writes.
      *
      * Absent when no session owns the dispatch: registry matching and permission pre-checks
      * resolve a URI outside any verb call.
@@ -9038,14 +10894,14 @@ declare interface UriResolveContext {
     readonly sessionId?: string;
     /**
      * WHO the dispatching session acts as, stamped by the host at the same dispatch site as
-     * {@link UriResolveContext.sessionId} and just as un-influenceable by the caller — so a module
+     * {@link UriResolveContext.sessionId} and just as un-influenceable by the caller - so a module
      * writing to a store it owns can record the actor without the agent being able to choose one.
      *
      * Free text minted by the host's own runtime (Bonsai's form is `user`, `subagent`,
      * `system/<surface>`, `followup/<surface>`) rather than a closed union: the surface half is the
      * host's vocabulary, and a second enumeration of it here would drift from the first.
      *
-     * Absent whenever the host has nothing to say — no session owns the dispatch, or the session
+     * Absent whenever the host has nothing to say - no session owns the dispatch, or the session
      * predates the host recording an origin. A module must then omit the actor rather than assume
      * one; an invented actor written into a durable artifact can never be walked back.
      */
@@ -9061,7 +10917,7 @@ declare interface UriResolveContext {
         readonly origin: "model" | "host";
         /**
          * The daemon-assigned id of the run driving this invocation, when the host's own execution
-         * frame carried one. Absent means the frame carried none — never a reason to guess one: a
+         * frame carried one. Absent means the frame carried none - never a reason to guess one: a
          * module recording this onto a durable artifact must treat absence as unresolved provenance,
          * not as "no run was active".
          */
@@ -9070,39 +10926,33 @@ declare interface UriResolveContext {
         readonly toolName?: string;
     };
     /**
-     * An OPAQUE, host-captured context for the mutation this dispatch is about to make —
+     * An OPAQUE, host-captured context for the mutation this dispatch is about to make -
      * the artifact-provenance counterpart of `sessionId`/`actor`, and stamped at the same
      * un-influenceable dispatch site.
      *
      * The host composes it from facts a caller cannot supply: which session is acting, the
      * run driving it, the tool invocation, and whatever the host resolved about how that
-     * session came to exist. The kernel treats it as an uninterpreted JSON value — it never
+     * session came to exist. The kernel treats it as an uninterpreted JSON value - it never
      * reads a field, only checks that the value is lossless JSON before it crosses the
-     * dispatch boundary — so this layer stays ignorant of any one product's provenance
+     * dispatch boundary - so this layer stays ignorant of any one product's provenance
      * semantics. A module that owns a durable artifact carries it to its store and validates
      * it against its OWN schema at the point it persists, where the target revision is known.
      *
      * Absent means the host captured nothing for this dispatch (a read, a host with no
-     * capture resolver, or a capture that failed) — never a claim that there was nothing to
+     * capture resolver, or a capture that failed) - never a claim that there was nothing to
      * capture. Present only on mutating dispatches (`write`/`edit`/`delete`); reads never pay
      * for it.
      */
     readonly captureContext?: Readonly<Record<string, unknown>>;
     /**
-     * Requested read shape. A module may ignore this and return its normal read; honoring
-     * it means returning an `ObservationMaterial` via `observationResource(...)` instead.
-     * Opt-in only — there is no advertisement surface or capability flag.
-     */
-    readonly format?: UriReadFormat;
-    /**
-     * Host-provided writable data root for the OWNING extension of the module handling this call —
+     * Host-provided writable data root for the OWNING extension of the module handling this call -
      * structurally identical to the per-extension `paths` a tool/handler context already receives, so
      * a module authored against both surfaces reads `ctx.paths?.dataDir` uniformly. Lets a URI module
      * own durable local state (a JSON store, a small file tree) instead of the host constructing and
      * injecting it. Host-populated after dispatch selects a module and keyed to that module's owner;
      * always absent during matching, and absent for modules with no owning extension (builtins) or a
      * host that wires no per-module data dir. Unlike a tool context, the host only NAMES this path for
-     * a URI module and does NOT pre-create the directory — create it on first write and tolerate its
+     * a URI module and does NOT pre-create the directory - create it on first write and tolerate its
      * absence on read.
      */
     readonly paths?: {
@@ -9117,6 +10967,15 @@ declare interface UriResolveContext {
      * proceeds as before.
      */
     readonly expectedRevision?: string;
+    /**
+     * The revision this session already holds for the address a `read` is about to fetch: the
+     * `RawResourceMetadata.revision` its last read reported. Set only on a repeat `read`, never
+     * on a mutation (`expectedRevision` is the mutation witness). A module with a cheap
+     * current-revision check (a metadata request, a `stat`) may compare first and, when it has
+     * verified the two are equal, answer {@link RawResource.unchanged} with no body. A module
+     * with no such check ignores it and reads in full, which is always correct.
+     */
+    readonly knownRevision?: string;
     /** Host marks a mediated session that enforces its private revision witness ledger. */
     readonly requiresRevisionWitness?: boolean;
     /** Host-derived descriptor for a top-level copied resource; absent for inline writes. */
@@ -9126,26 +10985,13 @@ declare interface UriResolveContext {
 declare interface UriResolvedAuth {
     readonly connection?: UriConnection;
     /** Present only for verb handlers of a module declaring `requiresAuth`; absent during matching. */
-    readonly credential?: UriResolvedCredential;
+    readonly credential?: ResolvedCredential;
     /** Present for handlers gated by a non-injectable external-CLI readiness scheme. */
     readonly externalCli?: UriExternalCliRunner;
     /** Opaque host metadata; not a credential channel. */
     readonly metadata?: Record<string, unknown>;
 }
 
-declare interface UriResolvedCredential {
-    /** Bearer for OAuth schemes, apiKey for api-key schemes. Host-resolved and refreshed. */
-    readonly accessToken: string;
-    readonly accountId: string;
-    readonly schemeId: string;
-    readonly scopes?: readonly string[];
-    /**
-     * Every value of a multi-field api-key credential, keyed by the scheme's declared field id
-     * (`accessToken` mirrors the primary field). Absent for single-secret schemes.
-     */
-    readonly fields?: Readonly<Record<string, string>>;
-}
-
 declare interface UriResourceDescription {
     readonly uri: string;
     /** Absent when the caller should retain its existing label. */
@@ -9165,12 +11011,9 @@ declare interface UriResourceLabel {
     readonly section?: string;
 }
 
-/** The call a module is asked to label. */
-declare interface UriResourceLabelRequest {
-    readonly operation: UriOperation;
-    /** The dispatch address: selector-stripped, the exact form the module's verb handler received. */
-    readonly uri: string;
-}
+declare const UriScheme: z.ZodString;
+
+declare type UriScheme = z.infer<typeof UriScheme>;
 
 declare interface UriSchemeClaim {
     readonly kind: "scheme";
@@ -9205,15 +11048,21 @@ declare interface UriSearchResult {
      * so the caller knows the matches may be partial.
      */
     readonly metadata?: UriListMetadata;
+    /** How long the host may cache this result; see {@link UriCachePolicy.ttlMs}. */
+    readonly cachePolicy?: Pick<UriCachePolicy, "ttlMs">;
+    /** The module's own markdown for this result, shown instead of the host's default rendering. */
+    readonly markdown?: string;
+    /** The touched resource's name for the transcript row, as on `RawResource.label`. */
+    readonly label?: UriResourceLabel;
 }
 
 /**
  * What a copied resource IS, minus its bytes: the identity half of a mediated
  * source. The host derives it once (filename inferred from the source address,
  * `mimeType` carried from the source module's own `RawResource.mimeType`) and
- * delivers it on both byte-bearing write hooks — inside each `UriWriteSource`,
- * and as the standalone third argument to `writeBytes` — so a remote sink can
- * name and type what it stores without re-deriving either from raw bytes.
+ * delivers it inside each `UriWriteSource`, and on `ctx.writeSource` for a
+ * `source` copy - so a remote sink can name and type what it stores without
+ * re-deriving either from raw bytes.
  */
 declare interface UriSourceDescriptor {
     readonly uri: string;
@@ -9228,11 +11077,11 @@ declare interface UriTemplate {
     /**
      * Per-operation effect docs for this route, keyed by operation. A route
      * whose shared {@link description} spans several verbs ("Read, edit, or
-     * trash a thread") is ambiguous for any surface that groups by verb — a
+     * trash a thread") is ambiguous for any surface that groups by verb - a
      * permission view must not describe `read` with a sentence that mentions
      * trashing. Each entry says what THAT operation concretely does at THIS
      * route; operations without an entry fall back to the shared description.
-     * Additive and optional — existing templates are unaffected.
+     * Additive and optional - existing templates are unaffected.
      */
     readonly operationDocs?: Partial<Record<UriOperation, string>>;
     /**
@@ -9272,13 +11121,13 @@ declare interface UriValidationMessage {
 
 /**
  * Author-declared, human-facing documentation of what each supported verb
- * CONCRETELY does against the provider — the capability half of a module's
+ * CONCRETELY does against the provider - the capability half of a module's
  * boolean verb-support declaration. Written for a permission/capability
  * surface ("what am I allowing?"), not for the model: one plain sentence per
  * verb naming the real-world effect ("Sends mail, creates/updates drafts,
  * applies label changes"), never wire mechanics or URI shapes. Verbs the
  * module does not support are omitted; at runtime a supported verb with no
- * entry simply renders undocumented (fail-open metadata) — but for a plugin's
+ * entry simply renders undocumented (fail-open metadata) - but for a plugin's
  * `kay.agent` URI modules, `auditPluginDisclosure` (`@bonsai/plugin-sdk/
  * disclosure`) enforces coverage of every supported verb at authoring/load
  * time.
@@ -9286,7 +11135,7 @@ declare interface UriValidationMessage {
  * Lives here in the protocol layer (beside {@link UriTemplate.operationDocs},
  * its per-route sibling) so both `@herd/uri-extensions`' `UriExtensionModule`
  * and herd-agent's kernel `UriModule` can carry it without inverting the
- * `@herd/uri` ← `@herd/uri-extensions` dependency.
+ * `@herd/uri` <- `@herd/uri-extensions` dependency.
  */
 declare interface UriVerbDocs {
     /** What a `read` of this address space returns (also covers `help`). */
@@ -9309,6 +11158,7 @@ declare interface UriVerbSupport {
     readonly editable: boolean;
     readonly deletable?: boolean;
     readonly listable: boolean;
+    readonly searchable?: boolean;
 }
 
 /** A mediated resource supplied beside structured write content without entering model context. */
@@ -9316,10 +11166,15 @@ declare interface UriWriteSource extends UriSourceDescriptor {
     readonly content: string | Uint8Array;
 }
 
+/** {@link hostWithinDomain} over a URL's hostname; an unparseable URL is never within. */
+declare function urlHostWithinDomain(url: string, domain: string): boolean;
+
+/** A claim on a public web link (`http` or `https`), usually folded onto the module's own scheme. */
 declare interface UrlPatternClaim {
     readonly kind: "urlPattern";
     readonly pattern: UriPatternInit;
-    readonly normalizeTo?: string;
+    readonly normalizeTo?: UriClaimTemplate;
+    readonly route?: string;
     readonly examples?: readonly string[];
 }
 
@@ -9366,6 +11221,66 @@ declare interface ValidateApiKeyCredentialResult {
 
 declare type ValidatePluginApiKeyCredential = ValidateApiKeyCredential;
 
+/**
+ * ---
+ * responsibility: The one interface through which a vendored-MCP plugin's code calls a tool on its
+ *   own vendored MCP server, so every read-through plugin and the daemon that implements the port
+ *   agree on the same shape by construction.
+ * owns:
+ *   - {@link VendoredMcpPort} - what a plugin's URI module and tools call.
+ *   - {@link VendoredMcpOutcome} - the typed result a plugin decodes, including every failure it
+ *     must surface to the agent rather than swallow.
+ * does_not_own:
+ *   - The implementation. A plugin never dials MCP itself: it takes the port from
+ *     `api.vendoredMcp.port(server)` (`@bonsai/plugin-sdk/kay-agent`), which the daemon binds to the
+ *     plugin's own hosted server over its MCP host. Plugin source stays host-free, and a plugin
+ *     under test substitutes a fake port.
+ *   - Which tool names exist. `TTool` is the plugin's own union of the vendor tools it calls; the
+ *     port is generic so a typo in a tool name fails typecheck inside the plugin.
+ * ---
+ */
+/**
+ * Why a call failed, as the plugin must tell the agent. `needs-auth` carries the exact service to
+ * reconnect (`serviceId`) so a plugin can name it in its error instead of returning an empty
+ * result; today's plugins name their statically declared `requiresAuth` service instead, which is
+ * the same service for a single-service plugin. `unknown-server` and `unknown-tool` are wiring
+ * faults (a server Bonsai does not host for this plugin, or a tool name the server does not have)
+ * and stay loud for the same reason: an unreachable host must never decode as "no data".
+ */
+declare type VendoredMcpFailureReason = "needs-auth" | "unknown-server" | "unknown-tool" | "failed";
+
+declare type VendoredMcpOutcome = 
+/**
+* `value` is the tool's `structuredContent` when it sent one, else its text content parsed as
+* JSON, else that text as a string: a vendor tool that answers in prose (a transcript, a
+* markdown summary) is a result, not a failure. A route that needs a record rejects a string
+* itself, with its own message.
+*/
+    {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly reason: VendoredMcpFailureReason;
+    readonly message: string;
+    /** Exact reconnect target supplied by the MCP host for an auth failure. */
+    readonly serviceId?: string;
+};
+
+/**
+ * One vendored MCP server, as the plugin that declares it calls it. `invoke` calls any tool the
+ * server has, whether it reads or writes. The port checks no permission of its own: a call is as
+ * permitted as the plugin tool or URI verb that makes it.
+ */
+declare interface VendoredMcpPort<TTool extends string = string> {
+    invoke(input: {
+        /** The session's working directory; the host resolves the server binding per cwd. */
+        readonly cwd: string;
+        readonly tool: TTool;
+        readonly args: Readonly<Record<string, unknown>>;
+    }): Promise<VendoredMcpOutcome>;
+}
+
 /** Creates a Void type. */
 declare function Void(options?: TSchemaOptions): TVoid;
 
@@ -9400,8 +11315,8 @@ declare const WhiteboardEntryInfo: z.ZodObject<{
         authorSessionId: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>>;
     state: z.ZodEnum<{
-        available: "available";
         unavailable: "unavailable";
+        available: "available";
         "unsupported-version": "unsupported-version";
         invalid: "invalid";
     }>;
@@ -9422,8 +11337,8 @@ declare const WhiteboardEntryInspection: z.ZodObject<{
         authorSessionId: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>>;
     state: z.ZodEnum<{
-        available: "available";
         unavailable: "unavailable";
+        available: "available";
         "unsupported-version": "unsupported-version";
         invalid: "invalid";
     }>;