@yaklabs-ai/plugin-sdk 0.8.4

package/dist/disclosure.d.ts

@@ -0,0 +1,3431 @@
+import type { TypeSafeClient } from '@typesafe-ai/sdk';
+import { z } from 'zod';
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+declare interface AccountIdentity {
+    /** Provider handle (GitHub `login`, Slack `user`). */
+    readonly username?: string;
+    /** Verified account email, when the provider reports one (Google userinfo). */
+    readonly email?: string;
+    /** The person's name as the provider renders it (e.g. "Alexander Goddijn"). */
+    readonly displayName?: string;
+    /** Absolute URL of the account's avatar. */
+    readonly avatarUrl?: string;
+    /** Issuer-asserted beta-tester flag; only Kay's product-account service sets it. */
+    readonly betaTester?: boolean;
+    /**
+     * 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 Kay's WorkOS
+     * product-account exchange/refresh sets it; every other provider leaves it absent.
+     */
+    readonly providerSessionId?: string;
+}
+
+/**
+ * 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
+ * workspace name, a Slack one is the team name. To describe the person, see {@link AccountIdentity}.
+ */
+declare interface AccountProvenance {
+    /** Provider-side stable id (e.g. an account/user id), when a scheme can resolve one. */
+    readonly externalId?: string;
+    /** Provider name the `externalId` is scoped to. */
+    readonly provider?: string;
+    /** Human-facing account name a scheme can derive (e.g. a workspace/org name). */
+    readonly displayName?: string;
+    /** Audited, non-core-typed provenance extras (e.g. a provider's workspace_id/owner blob). */
+    readonly raw?: Readonly<Record<string, unknown>>;
+}
+
+/** Final or partial result produced by a tool. */
+declare interface AgentToolResult<T = JsonValue_3 | undefined> {
+    /** Text or image content returned to the model. */
+    content: (TextContent | ImageContent)[];
+    /** Arbitrary structured details for logs or UI rendering. */
+    details: T;
+    /** Usage from the final tool execution itself, if available. Not used for main LLM context accounting. */
+    usage?: Usage;
+    /**
+     * Hint that the agent should stop after the current tool batch.
+     * Early termination only happens when every finalized tool result in the batch sets this to true.
+     */
+    terminate?: boolean;
+}
+
+/**
+ * Callback used by tools to stream partial execution updates.
+ *
+ * The callback is scoped to the current `execute()` invocation. Calls made after
+ * the tool promise settles are ignored.
+ */
+declare type AgentToolUpdateCallback<T = any> = (partialResult: AgentToolResult<T>) => void;
+
+declare interface AnthropicAllowedFallbackModel {
+    provider: ProviderId;
+    model: string;
+    cost: ModelCost;
+}
+
+/** Compatibility settings for Anthropic Messages-compatible APIs. */
+declare interface AnthropicMessagesCompat {
+    /**
+     * Whether the provider accepts per-tool `eager_input_streaming`.
+     * When false, the Anthropic provider omits `tools[].eager_input_streaming`
+     * and sends the legacy `fine-grained-tool-streaming-2025-05-14` beta header
+     * for tool-enabled requests.
+     * Default: true.
+     */
+    supportsEagerToolInputStreaming?: boolean;
+    /** Whether the provider supports Anthropic long cache retention (`cache_control.ttl: "1h"`). Default: true. */
+    supportsLongCacheRetention?: boolean;
+    /**
+     * Whether to send the `x-session-affinity` header from `options.sessionId`
+     * when caching is enabled. Required for providers like Fireworks that use
+     * session affinity for prompt cache routing (requests to the same replica
+     * maximize cache hits).
+     * Default: false.
+     */
+    sendSessionAffinityHeaders?: boolean;
+    /** Session-affinity format. `"openrouter"` sends `x-session-id`; when unset, sends `x-session-affinity`. */
+    sessionAffinityFormat?: "openrouter";
+    /**
+     * Whether the provider supports Anthropic-style `cache_control` markers on
+     * tool definitions. When false, `cache_control` is omitted from tool params.
+     * Some Anthropic-compatible providers (e.g., Fireworks) do not support this
+     * field on tools and may reject or ignore it.
+     * Default: true.
+     */
+    supportsCacheControlOnTools?: boolean;
+    /**
+     * Whether the model accepts the Anthropic `temperature` request field.
+     * Claude Opus 4.7+ rejects non-default temperature values.
+     * Default: true.
+     */
+    supportsTemperature?: boolean;
+    /**
+     * Whether to force adaptive thinking (`thinking.type: "adaptive"` plus
+     * `output_config.effort`) regardless of the model id. Built-in models that
+     * require adaptive thinking set this in generated metadata. Custom
+     * Anthropic-compatible providers can set this to `true` for any model whose
+     * upstream requires the adaptive format. Set to `false` to
+     * opt out on overridden built-in models.
+     * Default: false.
+     */
+    forceAdaptiveThinking?: boolean;
+    /** Whether to replay empty thinking signatures as `signature: ""` instead of converting thinking to text. Default: false. */
+    allowEmptySignature?: boolean;
+    /** Whether the provider supports Anthropic strict tool schemas. Default: false; generated Anthropic models enable it explicitly. */
+    supportsStrictTools?: boolean;
+    /** Whether the exact model transport supports effort-only system messages and thinking binding controls. Default: false. */
+    supportsMidConvoEffort?: boolean;
+    /** Whether the exact model accepts system-role messages inside the conversation. When false, later system messages are folded into the top-level system prompt. Default: false. */
+    supportsMidConvoSystemMessages?: boolean;
+    /** Whether the exact model accepts mid-conversation `tool_addition` and `tool_removal` blocks. Requires `supportsMidConvoSystemMessages`. Default: false. */
+    supportsMidConvoToolChanges?: boolean;
+    /**
+     * Models Anthropic accepts in `fallbacks` for server-side refusal fallback,
+     * with local pricing metadata for returned fallback responses. When absent or
+     * empty, callers must omit `fallbacks`; Anthropic rejects the field for models
+     * with no permitted fallback targets.
+     */
+    allowedFallbackModels?: AnthropicAllowedFallbackModel[];
+}
+
+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 Kay. */
+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. */
+    readonly capabilityId: string;
+    readonly displayName: string;
+    readonly status: ApiKeyCapabilityCheckStatus;
+}
+
+/** Whether validation proved the credential can use a capability, proved it cannot, or could not tell. */
+declare type ApiKeyCapabilityCheckStatus = "available" | "unavailable" | "unknown";
+
+/**
+ * Audit every hint-bearing module in `input.modules` (a module with no `agentHint` renders
+ * nothing into the prompt — see `renderUriAgentHints` — so it carries no disclosure surface
+ * to audit) against the rules #1138 locks down. Call from a plugin's own test suite, e.g.:
+ *
+ * ```ts
+ * const violations = await auditPluginDisclosure({
+ *   modules: [gmailModule],
+ *   declaredSkills: gmailPluginManifest.targets!.agent!.harness!.contributes!.skills!,
+ * });
+ * expect(violations).toEqual([]);
+ * ```
+ */
+export declare function auditPluginDisclosure(input: AuditPluginDisclosureInput): Promise<readonly DisclosureViolation[]>;
+
+export declare interface AuditPluginDisclosureInput {
+    readonly modules: readonly UriExtensionModule[];
+    readonly declaredSkills: readonly DeclaredSkillRef[];
+    /**
+     * Skills bound to a declared slash command (`CommandContribution.handler.kind ===
+     * "skill"`). A command-bound skill has an unconditional discovery path — the command
+     * index lists `/<name>` regardless of description keywords — so the unlinked-skill
+     * scheme-in-description fallback does not apply to it.
+     */
+    readonly commandBoundSkillIds?: readonly string[];
+}
+
+/**
+ * The codegen-pair equivalence check every bundled-skill plugin hand-rolled (see
+ * `plugins/ARCHITECTURE.md` → "Bundled skills", step 4): every exported `PluginSkillDefinition`
+ * must have a matching manifest declaration (same `localId`, same `description`), and the
+ * declared `SKILL.md` file's frontmatter + body must match the export byte-for-byte.
+ */
+export declare function auditSkillCodegenPairs(input: AuditSkillCodegenPairsInput): Promise<readonly DisclosureViolation[]>;
+
+export declare interface AuditSkillCodegenPairsInput {
+    readonly declaredSkills: readonly DeclaredSkillContribution[];
+    readonly exportedSkills: readonly PluginSkillDefinition[];
+    /**
+     * The plugin package's root directory, as a `file:` URL — `declaredSkills[].path` resolves
+     * against it. From a test file under `test/`, pass `new URL("../", import.meta.url)`.
+     */
+    readonly packageDir: URL;
+}
+
+/** A connected account under one `(serviceId, schemeId)` — the multi-account unit. */
+declare interface AuthAccount {
+    readonly accountId: string;
+    readonly displayName: string;
+    /**
+     * Who the account belongs to, carried through from the stored credential. This is the
+     * agent-facing account shape (it feeds `auth_accounts` and the ambient facts), so it carries the
+     * human but NOT {@link AccountProvenance}: provenance's `raw` is an unbounded provider blob, and
+     * an account's provider-side record is not something the agent needs to see. Provenance stays on
+     * {@link StoredCredentialSummary} (persistence) and `AuthBrokerAccount` (the host's connection UI).
+     */
+    readonly identity?: AccountIdentity;
+    /**
+     * Trust-lost marker carried through from {@link 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
+     * and point the user at a reconnect; token resolution for it still fails closed.
+     */
+    readonly needsReconnect?: boolean;
+}
+
+declare interface BackgroundTaskAdoptOptions {
+    readonly preferredId?: string;
+    readonly toolCallId?: string;
+    readonly ownerId?: string;
+    readonly inspect?: BackgroundTaskInspector;
+    readonly meta?: Readonly<Record<string, unknown>>;
+    /** Scoped settlement hook for the task created by this adoption only. */
+    readonly onSettled?: (completion: BackgroundTaskCompletion) => void;
+}
+
+declare interface BackgroundTaskCompletion {
+    readonly taskId: string;
+    readonly startedAtMs?: number;
+    readonly completedAtMs?: number;
+    readonly taskKind: BackgroundTaskKind;
+    readonly toolCallId: string;
+    readonly ownerId?: string;
+    readonly state: Exclude<BackgroundTaskStatus, "running" | "queued">;
+    /** Present when the cancelling principal suppresses the model-facing result. */
+    readonly resultDelivery?: BackgroundTaskResultDelivery;
+    readonly output?: string;
+    readonly error?: string;
+}
+
+declare type BackgroundTaskInspector = () => Promise<string> | string;
+
+declare type BackgroundTaskKind = "bash" | "agent";
+
+declare type BackgroundTaskResultDelivery = "deliver" | "suppress";
+
+declare type BackgroundTaskRun = (ctx: BackgroundTaskRunContext) => Promise<string>;
+
+declare interface BackgroundTaskRunContext {
+    readonly taskId: string;
+    readonly signal: AbortSignal;
+    /** `this: void` — task bodies destructure this reporter off the context. */
+    reportProgress(this: void, text: string, details?: Record<string, unknown>): void;
+}
+
+declare interface BackgroundTaskSnapshot {
+    readonly id: string;
+    readonly taskKind: BackgroundTaskKind;
+    readonly toolCallId?: string;
+    readonly label: string;
+    readonly status: BackgroundTaskStatus;
+    readonly ownerId?: string;
+    /** Agent tasks link to the ordinary child session they are driving. */
+    readonly childSessionId?: string;
+    readonly startedAtMs: number;
+    readonly updatedAtMs: number;
+    readonly meta?: Readonly<Record<string, unknown>>;
+}
+
+declare type BackgroundTaskStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
+
+/** Compatibility settings for Amazon Bedrock models. */
+declare interface BedrockCompat {
+    /** Whether the model supports Bedrock strict tool schemas. Default: false. */
+    supportsStrictMode?: boolean;
+}
+
+declare type CacheRetention = "none" | "short" | "long";
+
+/** One captured `declareApiKeyScheme(serviceId, scheme)` call, verbatim. */
+export declare interface CapturedApiKeyDeclaration {
+    readonly serviceId: string;
+    readonly scheme: PluginApiKeyScheme;
+}
+
+/** One captured `declareDelegatedScheme(serviceId, scheme)` call, verbatim. */
+declare interface CapturedDelegatedDeclaration {
+    readonly serviceId: string;
+    readonly scheme: PluginDelegatedScheme;
+}
+
+/** Everything the auth probe captures from one `activate` run, in call order. */
+export declare interface CapturedKayAgentAuthDeclarations {
+    readonly services: readonly PluginServiceDescriptor[];
+    readonly oauthPkceSchemes: readonly CapturedOAuthPkceDeclaration[];
+    /**
+     * Api-key schemes declared this run — the `displayName`/`inputLabel`/`setup`/`validate`
+     * runtime declaration a manifest's identity-only scheme row cannot carry. Daemon acquisition
+     * composition maps these onto the connect dispatch's api-key roster the same way
+     * `oauthPkceSchemes` maps onto the PKCE arm — see `@kay/agent-runtime`'s `kay/composition/`.
+     * Empty for a plugin that declares none.
+     */
+    readonly apiKeySchemes: readonly CapturedApiKeyDeclaration[];
+    /**
+     * Delegated schemes declared this run. Daemon acquisition composition maps these onto a
+     * delegated connect-roster entry the same way `oauthPkceSchemes` maps onto the PKCE arm — see
+     * `@kay/agent-runtime`'s `kay/composition/`. Empty for a plugin that declares none.
+     */
+    readonly delegatedSchemes: readonly CapturedDelegatedDeclaration[];
+}
+
+/** One captured `declareOAuthPkceScheme(serviceId, scheme)` call, verbatim. */
+export declare interface CapturedOAuthPkceDeclaration {
+    readonly serviceId: string;
+    readonly scheme: PluginOAuthPkceScheme;
+}
+
+declare type ChatTemplateKwargValue = string | number | boolean | null | {
+    $var: "thinking.enabled" | "thinking.effort" | "thinking.budget";
+    omitWhenOff?: boolean;
+};
+
+/**
+ * Runs `activate` once against a fake, capture-only {@link KayAgentPluginApi} and returns every
+ * service it advertised and every OAuth-PKCE, api-key, and delegated scheme it declared, in call
+ * order. Every other call (`uri.registerModule`, `registerTool`, `declareExternalCliScheme`, …) is
+ * a silent no-op: those surfaces are irrelevant to acquisition composition, and a plugin that also
+ * calls them must not throw or leak a side effect from this probe.
+ */
+export declare function collectAuthDeclarationsFromKayAgentActivate(activate: KayAgentActivate): CapturedKayAgentAuthDeclarations;
+
+/**
+ * Runs `activate` once against a fake, capture-only {@link KayAgentPluginApi} and returns
+ * every `UriExtensionModule` it registered, in registration order. Every non-`uri.registerModule`
+ * call (`registerTool`, `registerSearchProvider`, `registerConverter`, `auth.*`) is a silent
+ * no-op: those surfaces are irrelevant to disclosure, and a plugin that also calls them must not
+ * throw or leak a side effect from this probe.
+ */
+export declare function collectUriModulesFromKayAgentActivate(activate: KayAgentActivate): readonly UriExtensionModule[];
+
+/**
+ * A mime-keyed converter. Registered via the ExtensionApi and merged per session.
+ * `matches` is called on every active converter for every binary read, so keep it
+ * cheap and side-effect-free; a throw is isolated by the registry as "no match".
+ */
+declare interface ContentConverter {
+    /** Stable id for diagnostics/ordering (e.g. "app:pdf", "builtin:identity"). */
+    readonly id: string;
+    /**
+     * Optional; surfaced on the read tool's description when this converter is
+     * active. Omit for transparent converters that just improve fidelity without
+     * an agent-facing surface.
+     */
+    readonly description?: string;
+    matches(probe: ContentProbe): boolean;
+    convert(bytes: Uint8Array, probe: ContentProbe, ctx: ConvertContext): Promise<ConversionResult>;
+}
+
+/**
+ * What the converter is asked to convert. `mimeType`/`extension` may be absent if
+ * the transport could not determine them; `bytesHead` lets a `matches` predicate
+ * sniff magic bytes without holding the whole payload.
+ */
+declare interface ContentProbe {
+    readonly mimeType?: string;
+    readonly extension?: string;
+    readonly filename: string;
+    readonly bytesHead?: Uint8Array;
+    /**
+     * The absolute local filesystem path the bytes came from, threaded in from
+     * the transport's {@link RawResource} metadata. Absent for remote sources;
+     * lets a converter reference the on-disk file in agent-facing output (e.g.
+     * an archive converter directing shell tools at it for extraction).
+     */
+    readonly localPath?: string;
+}
+
+/**
+ * The convert return shape. `content` is the agent-facing
+ * {@link import("../shared.ts").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
+ * NOT truncate or line-window; {@link finalize} owns that uniformly.
+ */
+declare interface ConversionResult {
+    readonly content: readonly ModelContent[];
+    /** Reserved metadata; e.g. "text/markdown". */
+    readonly contentType?: string;
+    /** Reserved metadata; files written to the artifact dir (images-to-disk manifest). */
+    readonly artifacts?: readonly ConvertedArtifact[];
+    /** Reserved metadata; pages/outline. */
+    readonly structure?: ConversionStructure;
+    /** Reserved metadata. */
+    readonly notes?: readonly string[];
+    /** Reserved metadata; whether the converter itself elided content before truncation. */
+    readonly truncated?: boolean;
+}
+
+/** Structural summary of the converted document. Reserved metadata. */
+declare interface ConversionStructure {
+    readonly pageCount?: number;
+    readonly outline?: readonly {
+        readonly level: number;
+        readonly title: string;
+        readonly page?: number;
+    }[];
+}
+
+/**
+ * Per-call context. `cwd`/`signal` mirror {@link UriResolveContext}. `artifactDir`
+ * is an app-provided, app-owned directory a converter may write derived files into
+ * (e.g. images extracted from a PDF); absent for core standalone callers, in which
+ * case a converter must degrade to text-only.
+ */
+declare interface ConvertContext {
+    readonly cwd: string;
+    readonly signal?: AbortSignal;
+    readonly artifactDir?: string;
+}
+
+/** A file a converter wrote to {@link ConvertContext.artifactDir}. Reserved metadata. */
+declare interface ConvertedArtifact {
+    readonly id: string;
+    readonly path: string;
+    readonly kind: "image" | "other";
+    readonly page?: number;
+    readonly bbox?: readonly number[];
+    readonly caption?: string;
+}
+
+/** One skill entry from a plugin's manifest (`targets.kay.agent.contributes.skills`). */
+export declare interface DeclaredSkillContribution {
+    readonly localId: string;
+    readonly description: string;
+    /** Package-relative path to the `SKILL.md`, e.g. `"./skills/email-triage/SKILL.md"`. */
+    readonly path: string;
+}
+
+/** The declared-skill shape {@link auditPluginDisclosure}'s cross-link rule needs. */
+export declare interface DeclaredSkillRef {
+    readonly localId: string;
+    readonly description: string;
+}
+
+/**
+ * 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 {@link import("./oauth-pkce.ts").OAuthRedirectTransport}
+ * — both absent when the host has none; the scheme decides whether it needs them.
+ */
+declare interface DelegatedConnectContext {
+    readonly serviceId: string;
+    readonly schemeId: string;
+    /** The freshly-minted accountId the material will be stored under. */
+    readonly accountId: string;
+    readonly signal?: AbortSignal;
+    /** The transport's redirect URI, for building redirect URLs; absent without a transport. */
+    readonly redirectUri?: string;
+    /** Open `authorizeUrl` for the user and resolve with the provider's callback params. */
+    readonly authorize?: (authorizeUrl: string, expectedState: string) => Promise<OAuthRedirectResult>;
+}
+
+/** What a delegated scheme's `connect` resolves with: the material to vault + optional label/provenance. */
+declare interface DelegatedConnectResult {
+    readonly material: DelegatedSecretMaterial;
+    /** Account display label; a caller-supplied `service_connect` label takes precedence. */
+    readonly label?: string;
+    /** Structured provenance the scheme derived during connect; persisted via the vault's write-path. */
+    readonly provenance?: AccountProvenance;
+}
+
+/**
+ * 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.
+ */
+declare interface DelegatedSecretMaterial {
+    readonly kind: "delegated";
+    readonly accessToken: string;
+    /** ISO-8601 access-token expiry; absent means non-expiring. */
+    readonly expiresAt?: string;
+    /** Scheme-owned state persisted verbatim alongside the token; opaque to core. */
+    readonly data?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * The subset of a {@link ToolAction}'s rule-matching fields that a {@link ToolPermissionHint}
+ * 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
+ * call matches, not the paths it touches.
+ */
+declare interface DerivedToolClassification {
+    readonly kind?: ToolActionKind;
+    readonly ruleKey?: string;
+    readonly scheme?: string;
+}
+
+/** One authoring-quality defect found in a plugin's disclosure surfaces. */
+export declare interface DisclosureViolation {
+    /**
+     * The disclosure surface the violation belongs to: a `UriExtensionModule.id` for every
+     * `auditPluginDisclosure` module-shaped rule, or a skill's `localId` for the rules that
+     * inspect a declared skill's own description (there is no module in play there — the
+     * `localId` is the closest thing to that surface's identity).
+     */
+    readonly moduleId: string;
+    /** A stable, kebab-case rule id — grep this in the audit source to see exactly what fired. */
+    readonly rule: PluginDisclosureRule;
+    readonly detail: string;
+}
+
+/**
+ * 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.
+ */
+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
+     * 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.
+     */
+    readonly resolveToken: (input: {
+        readonly serviceId: string;
+        readonly schemeId?: string;
+        readonly accountId?: string;
+        /**
+         * 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
+         * (see {@link CreateExtensionAuthContextInput.callerId}).
+         */
+        readonly requiredScopes?: readonly string[];
+        /** Ordered scope alternatives; mutually exclusive with `requiredScopes`. */
+        readonly scopeRequirement?: ScopeRequirement;
+        /**
+         * The binding's front-door service id (`requiresAuth.connectServiceId`), threaded so a
+         * scope-shortfall failure can name the connect that actually grants the missing scopes
+         * instead of the credential service (whose re-connect cannot). Guidance only.
+         */
+        readonly connectServiceId?: string;
+    }) => Promise<ResolveTokenResult>;
+    /**
+     * The session-active accountId, or `undefined`. Scheme-scoped when `schemeId` is given; with it
+     * absent, the service's most recent selection across all schemes (service-level view).
+     */
+    readonly getActiveAccount: (input: {
+        readonly serviceId: string;
+        readonly schemeId?: string;
+    }) => Promise<string | undefined>;
+    /**
+     * Connected accounts (multi-account discovery). Scheme-scoped when `schemeId` is given; with it
+     * absent, the union across the service's injectable schemes (first scheme wins an id collision).
+     */
+    readonly listAccounts: (input: {
+        readonly serviceId: string;
+        readonly schemeId?: string;
+    }) => Promise<readonly AuthAccount[]>;
+    /**
+     * Resolve a non-injectable external-CLI readiness marker into a protocol runner. No secret
+     * material leaves the auth subsystem; the host runner receives the stored binary plus argv.
+     */
+    readonly resolveExternalCli: (input: {
+        readonly serviceId: string;
+        readonly schemeId: string;
+        readonly accountId?: string;
+    }) => Promise<ResolveExternalCliResult>;
+}
+
+/** Optional extension-facing APIs for background task orchestration. */
+declare interface ExtensionBackgroundTasksApi {
+    adopt(taskKind: BackgroundTaskKind, label: string, run: BackgroundTaskRun, options?: BackgroundTaskAdoptOptions): string;
+    list(): readonly BackgroundTaskSnapshot[];
+    get(taskId: string): BackgroundTaskSnapshot | undefined;
+}
+
+/**
+ * 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
+ * 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
+ * kernel learning any host storage policy.
+ */
+declare interface ExtensionPaths {
+    /** Absolute path to this extension's writable data directory (created before the context is built). */
+    readonly dataDir: string;
+}
+
+/**
+ * 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;
+    mimeType: string;
+}
+
+declare type JsonObject = {
+    [key: string]: JsonValue_3;
+};
+
+declare type JsonPrimitive = string | number | boolean | null;
+
+declare type JsonSchema = Record<string, unknown>;
+
+declare type JsonValue = JsonPrimitive | {
+    readonly [key: string]: JsonValue;
+} | readonly JsonValue[];
+
+declare type JsonValue_2 = string | number | boolean | null | JsonValue_2[] | {
+    [key: string]: JsonValue_2;
+};
+
+declare const JsonValue_2: z.ZodType<JsonValue_2>;
+
+declare type JsonValue_3 = null | boolean | number | string | readonly JsonValue_3[] | JsonObject;
+
+/** A plugin's Kay agent activation — receives only the brokered {@link KayAgentPluginApi}. */
+declare type KayAgentActivate = (api: KayAgentPluginApi) => void;
+
+/**
+ * Publishes the plugin's declared events from agent code. See {@link KayAgentPluginApi.events}.
+ */
+declare interface KayAgentEvents {
+    /**
+     * Publish one event the plugin declares in its `kay.app` `eventDefinitions`, with a payload that
+     * matches that definition's `payloadSchema`.
+     *
+     * The host stamps the publisher (this plugin) and the session this activation belongs to; the
+     * plugin names neither. Fire-and-forget: it returns nothing and never throws. A publish the host
+     * refuses (an undeclared event, an invalid payload, the plugin's `kay.app` target not running)
+     * is reported to the host's diagnostics and dropped, so the work that raised the event never
+     * fails because the event did not go out.
+     */
+    publish(localId: string, payload: unknown): void;
+}
+
+/** Claim-checked filesystem operations. Paths are root-relative; canonical host paths never cross the seam. */
+declare interface KayAgentFilesystem {
+    readText(location: KayAgentFilesystemLocation): Promise<string>;
+    writeText(location: KayAgentFilesystemLocation, content: string): Promise<void>;
+    mkdir(location: KayAgentFilesystemLocation): Promise<void>;
+    readDir(location: KayAgentFilesystemLocation): Promise<readonly KayAgentFilesystemEntry[]>;
+    stat(location: KayAgentFilesystemLocation): Promise<KayAgentFilesystemStat>;
+    rename(from: KayAgentFilesystemLocation, to: KayAgentFilesystemLocation): Promise<void>;
+    /** Returns the canonical path relative to the selected grant root. */
+    realpath(location: KayAgentFilesystemLocation): Promise<string>;
+}
+
+declare interface KayAgentFilesystemEntry {
+    readonly name: string;
+    readonly kind: "file" | "directory" | "symlink" | "other";
+}
+
+declare interface KayAgentFilesystemLocation {
+    /** Exact `root` selector the host bound for this target, plus a path relative to it. */
+    readonly root: string;
+    readonly path: string;
+}
+
+declare interface KayAgentFilesystemStat {
+    readonly kind: "file" | "directory" | "other";
+    readonly size: number;
+    readonly modifiedAtMs: number;
+}
+
+/** 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. */
+    readonly score?: number;
+}
+
+/**
+ * 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
+ * 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
+ * rather than widening it (fail closed), so an all-out-of-scope request resolves an empty result
+ * rather than silently reaching another plugin's address space. Rank order is authoritative; each
+ * hit also carries the source score for display or comparison within that one returned list only.
+ */
+declare type KayAgentKnowledgeSearch = (query: string, opts?: {
+    readonly limit?: number;
+    readonly uriPrefixes?: readonly string[];
+}) => Promise<readonly KayAgentKnowledgeHit[]>;
+
+/**
+ * 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
+ * understanding stays with the knowledge index.
+ */
+declare interface KayAgentKnownResource {
+    /** The module's canonical URI for the resource. */
+    readonly uri: string;
+    /** The resolved credential's account id at recording time; absent for unauthed sightings. */
+    readonly accountId?: string;
+    readonly title?: string;
+    readonly summary?: string;
+    readonly mimeType?: string;
+    /** Most recent provenance; the DURABLE grant fact lives in `grantedVia`, not here. */
+    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
+     * through an explicit user grant.
+     */
+    readonly grantedVia?: string;
+    /** When the `grantedVia` grant was last made. */
+    readonly grantedAt?: string;
+    readonly firstSeen: string;
+    readonly lastSeen: string;
+    /** Last successful full read; absent means seen in listings but never opened. */
+    readonly lastRead?: string;
+    /** Set when the last resolution found the resource gone; cleared by any later successful sighting. */
+    readonly goneAt?: string;
+}
+
+/**
+ * Read back this plugin's own rows from the daemon's known-resources ledger
+ * (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
+ * {@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
+ * was once seen, never that it is still reachable.
+ */
+declare interface KayAgentKnownResources {
+    query(opts?: {
+        /** Restrict to sightings recorded under one account id. */
+        readonly accountId?: string;
+        /** Case-insensitive substring match against uri and title. */
+        readonly text?: string;
+        /** Exact match against the row's most recent `seenVia`. */
+        readonly seenVia?: string;
+        /** True: only rows carrying a durable grant (`grantedVia` set). */
+        readonly grantedOnly?: boolean;
+        /** Default false: rows marked gone are excluded unless asked for. */
+        readonly includeGone?: boolean;
+        readonly limit?: number;
+        readonly cursor?: string;
+    }): Promise<{
+        readonly rows: readonly KayAgentKnownResource[];
+        readonly nextCursor?: string;
+    }>;
+    get(uri: string, opts?: {
+        readonly accountId?: string;
+    }): Promise<KayAgentKnownResource | undefined>;
+}
+
+/**
+ * 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
+ * plain-string widening here would silently admit junk provenance.
+ */
+declare type KayAgentKnownResourceSeenVia = "read" | "list" | "search" | `granted:${string}`;
+
+/**
+ * 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
+ * `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
+ * authority, because that set is live and would be stale the moment it was handed over.
+ */
+declare interface KayAgentNetwork {
+    fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
+}
+
+/**
+ * The API a plugin's `kay.agent` entrypoint receives. Every sensitive operation is brokered
+ * here; the plugin never touches an `ExtensionApi`, `child_process`, credentials, or Electron.
+ */
+declare interface KayAgentPluginApi {
+    readonly uri: {
+        /** Register a whole URI module (a scheme handler that owns its address space, e.g. `drive://`). */
+        registerModule(module: UriExtensionModule): void;
+    };
+    /**
+     * Always present; each call is checked against `filesystem.read {root}` / `filesystem.write
+     * {root}` for the root it touches, and against the host's binding for that root.
+     */
+    readonly filesystem: KayAgentFilesystem;
+    /** Absent unless the `knowledgeSearch` grant is requested and effectively granted. */
+    readonly knowledgeSearch?: KayAgentKnowledgeSearch;
+    /** Absent unless the `knownResources` grant is requested and effectively granted. */
+    readonly knownResources?: KayAgentKnownResources;
+    /**
+     * 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
+     * `network.connect {connect}` for the host it is about to reach.
+     */
+    readonly network: KayAgentNetwork;
+    /**
+     * Always present; each call is checked against `web-session.request {origin, pathPrefix}` or
+     * `web-session.download {origin, pathPrefix}` for the declared row the URL matches.
+     */
+    readonly webSession: KayAgentWebSession;
+    /**
+     * Always present; each run is checked against `process.spawn {command, argvClass}` for the
+     * command it is about to run, and against the host's executable binding.
+     */
+    readonly process: KayAgentProcess;
+    /**
+     * Jev typed-decision inference, as an OPTIONAL accelerator with a REQUIRED fallback. Each call
+     * is checked against `jev.use` — but a refused grant or a missing saved key both
+     * produce the same outcome: your `fallback` runs.
+     *
+     * Always present, on every host. That is the point: with no absent state to feature-detect,
+     * there is no shape of code that reaches Jev without having written the baseline too. Do not
+     * guard it with `if (api.withJev !== undefined)`.
+     */
+    readonly withJev: WithJev;
+    /**
+     * Publish the plugin's declared events, for example so a default notification rule can tell the
+     * user what the agent just did. Always present, like {@link withJev}: there is nothing to
+     * feature-detect, and a host that composed no events lane drops what is published.
+     */
+    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.
+     */
+    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.
+     */
+    registerSearchProvider(provider: SearchProvider): void;
+    /**
+     * Register a content converter (turns raw bytes of a mime type into agent-facing content behind the
+     * read tool's finalize stage). Parallel to the kernel's `registerConverter`. Converters are
+     * auth-free: the injected credential never reaches them, so there is no `requiresAuth` binding here.
+     */
+    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
+     * (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
+     * substitute results, never widen what is callable.
+     */
+    interceptToolCall(interceptor: ToolCallInterceptor): void;
+    readonly auth: {
+        advertiseService(descriptor: PluginServiceDescriptor): void;
+        declareOAuthPkceScheme(serviceId: string, scheme: PluginOAuthPkceScheme): void;
+        declareApiKeyScheme(serviceId: string, scheme: PluginApiKeyScheme): void;
+        declareExternalCliScheme(serviceId: string, scheme: PluginExternalCliScheme): 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`.
+         */
+        declareDelegatedScheme(serviceId: string, scheme: PluginDelegatedScheme): void;
+        /**
+         * Register a synchronous source for delegated services whose membership may change while the
+         * session is running. Each service registry read receives the source's current snapshot. Absent
+         * on compatibility hosts; plugins must fall back to static advertisement when unavailable.
+         */
+        registerDelegatedServiceSource?(source: () => readonly PluginDelegatedServiceEntry[]): void;
+    };
+}
+
+/**
+ * Claim-checked process execution. The handle is always present; each run is decided on its own,
+ * against an exact `process.spawn {command, argvClass}` claim and the host's executable binding.
+ *
+ * `run` only ever RESOLVES for a process the host actually started, so a non-zero
+ * {@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 —
+ * 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
+ * command that forks its own helper (a wrapper script, a build tool) can leave that helper running
+ * after a timeout or an abort, even though the run itself reports it stopped (#6153).
+ */
+declare interface KayAgentProcess {
+    run(request: KayAgentProcessRunRequest): Promise<KayAgentProcessRunResult>;
+}
+
+/**
+ * One process the plugin asks the host to run.
+ *
+ * `argvClass` is required and is NOT decoration: it names the class of argument vector this
+ * invocation belongs to, and it must match a class the plugin declared alongside `command` in its
+ * manifest. Declaring a command alone would authorize `git log` and `git push --force` identically;
+ * the class is what a user can be shown and asked to consent to. The host judges the real `args`
+ * against the named class and refuses with `argv-outside-class` when they do not belong to it.
+ */
+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). */
+    readonly signal?: AbortSignal;
+}
+
+/**
+ * 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".
+ */
+declare interface KayAgentProcessRunResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly stdoutTruncated?: boolean;
+    readonly stderrTruncated?: boolean;
+}
+
+/**
+ * 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
+ * follows a redirect of the call, and injects CSRF material without returning it. Downloads stream
+ * to a host-created temporary file. A malformed call throws `TypeError` before any host round-trip;
+ * everything the session or provider does wrong arrives as {@link KayAgentWebSessionError}.
+ */
+declare interface KayAgentWebSession {
+    request(call: KayAgentWebSessionCall): Promise<KayAgentWebSessionResponse>;
+    download(call: KayAgentWebSessionDownload): Promise<KayAgentWebSessionDownloadResult>;
+}
+
+declare interface KayAgentWebSessionCall {
+    readonly url: string;
+    readonly method: "GET" | "POST";
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly body?: string;
+}
+
+declare interface KayAgentWebSessionDownload extends KayAgentWebSessionCall {
+    /** Suggested basename only. The host sanitizes it and owns the destination directory. */
+    readonly filename?: string;
+}
+
+declare interface KayAgentWebSessionDownloadResult {
+    /** The file on disk; authoritative. Its basename is host-chosen and is not `filename`. */
+    readonly localPath: string;
+    /** The provider-reported name (content-disposition) or the suggested one, sanitized. */
+    readonly filename: string;
+    readonly mimeType?: string;
+    readonly size: number;
+}
+
+declare interface KayAgentWebSessionResponse {
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: string;
+}
+
+declare interface KayAgentWhiteboard {
+    listTypes(): Promise<readonly WhiteboardTypeInfo[]>;
+    forType(typeId: string): KayAgentWhiteboardTypeHandle;
+}
+
+declare interface KayAgentWhiteboardCreateInput {
+    readonly name: string;
+    readonly title: string;
+    readonly value: WhiteboardValue;
+}
+
+declare interface KayAgentWhiteboardListOptions {
+    readonly cursor?: string;
+    readonly limit?: number;
+}
+
+declare interface KayAgentWhiteboardListResult {
+    readonly entries: readonly WhiteboardEntrySummary[];
+    readonly nextCursor?: string;
+}
+
+declare interface KayAgentWhiteboardMutationInput extends KayAgentWhiteboardUpdateInput {
+    readonly mutation: WhiteboardValue;
+}
+
+declare interface KayAgentWhiteboardPayload {
+    /** Reads at most 1 MiB; a supplied revision rejects ranges from a changed payload. */
+    read(name: string, range: {
+        readonly offset: number;
+        readonly maxBytes: number;
+        readonly expectedRevision?: string;
+    }): Promise<{
+        readonly bytes: Uint8Array;
+        readonly offset: number;
+        readonly sizeBytes: number;
+        readonly revision: string;
+    }>;
+    create(input: KayAgentWhiteboardCreateInput & {
+        readonly bytes: Uint8Array;
+    }): Promise<WhiteboardEntrySnapshot>;
+    replace(name: string, input: {
+        readonly expectedRevision: string;
+        readonly title?: string;
+        readonly value: WhiteboardValue;
+        readonly bytes: Uint8Array;
+    }): Promise<WhiteboardEntrySnapshot>;
+}
+
+declare interface KayAgentWhiteboardRemoveInput {
+    readonly expectedRevision: string;
+}
+
+declare interface KayAgentWhiteboardTypeHandle {
+    /** Byte-preserving operations for payload storage; other storage kinds reject them. */
+    readonly payload: KayAgentWhiteboardPayload;
+    /** Includes invalid and unavailable entries without loading their bodies into the inventory. */
+    inventory(options?: KayAgentWhiteboardListOptions): Promise<{
+        readonly entries: readonly WhiteboardEntryInfo[];
+        readonly nextCursor?: string;
+    }>;
+    /** Bounded read-only recovery view; never authorizes typed mutation of an incompatible entry. */
+    inspect(name: string): Promise<WhiteboardEntryInspection | undefined>;
+    list(options?: KayAgentWhiteboardListOptions): Promise<KayAgentWhiteboardListResult>;
+    read(name: string): Promise<WhiteboardEntrySnapshot | undefined>;
+    create(input: KayAgentWhiteboardCreateInput): Promise<WhiteboardEntrySnapshot>;
+    update(name: string, input: KayAgentWhiteboardUpdateInput, transform: (current: WhiteboardEntrySnapshot) => WhiteboardValue | Promise<WhiteboardValue>): Promise<WhiteboardEntrySnapshot>;
+    /** Invokes the registered type's mutation under the host lock and update grant. */
+    mutate(name: string, input: KayAgentWhiteboardMutationInput): Promise<WhiteboardEntrySnapshot>;
+    remove(name: string, input: KayAgentWhiteboardRemoveInput): Promise<void>;
+}
+
+declare interface KayAgentWhiteboardUpdateInput {
+    readonly expectedRevision?: string;
+    readonly title?: string;
+}
+
+declare type KnownApi = "openai-completions" | "mistral-conversations" | "openai-responses" | "azure-openai-responses" | "openai-codex-responses" | "anthropic-messages" | "bedrock-converse-stream" | "google-generative-ai" | "google-vertex" | "pi-messages";
+
+declare type KnownProvider = "amazon-bedrock" | "ant-ling" | "anthropic" | "google" | "google-vertex" | "openai" | "azure-openai-responses" | "openai-codex" | "radius" | "nvidia" | "deepseek" | "github-copilot" | "xai" | "groq" | "cerebras" | "openrouter" | "vercel-ai-gateway" | "zai" | "zai-coding-cn" | "mistral" | "minimax" | "minimax-cn" | "moonshotai" | "moonshotai-cn" | "huggingface" | "fireworks" | "together" | "baseten" | "opencode" | "opencode-go" | "kimi-coding" | "meta" | "cloudflare-workers-ai" | "cloudflare-ai-gateway" | "qwen-token-plan" | "qwen-token-plan-cn" | "qwen-token-plan-individual" | "xiaomi" | "xiaomi-token-plan-cn" | "xiaomi-token-plan-ams" | "xiaomi-token-plan-sgp";
+
+declare interface LineRange {
+    readonly start: number;
+    readonly end: number;
+}
+
+declare interface LineSelector {
+    readonly ranges: readonly LineRange[];
+    readonly raw: boolean;
+}
+
+/**
+ * The execute-time surface a tool sees. These are the only fields a {@link ToolDefinition.execute}
+ * body can read. Runtime-optionals are absent without a live session: a tool invoked from a
+ * session-less inventory/standalone context gets just `cwd` + `model: undefined`, with `auth`,
+ * `backgroundTasks`, `toolExecutionPolicyDefaults`, and `paths` all absent. A tool must treat each
+ * optional as "may be missing" and degrade accordingly (the SDK auth wrappers, for instance,
+ * short-circuit with an actionable message when {@link auth} is undefined).
+ */
+declare type MidTurnCompactionOutcome = {
+    readonly kind: "compacted";
+} | {
+    readonly kind: "failed";
+} | {
+    readonly kind: "cancelled";
+    readonly reason: "run-stopped" | "session-disposed";
+};
+
+declare type MidTurnCompactionRequest = {
+    readonly kind: "scheduled";
+    /**
+     * 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 —
+     * so awaiting it here hangs the run behind itself, which is the exact
+     * deadlock this capability replaced. Attach a callback and return.
+     */
+    readonly settled: Promise<MidTurnCompactionOutcome>;
+} | {
+    readonly kind: "refused";
+    readonly reason: "already-pending" | "maintenance-in-flight";
+};
+
+/** Compatibility settings for the Mistral chat API. */
+declare interface MistralConversationsCompat {
+    /** Whether the exact model accepts system messages after the conversation has started. When false, later system messages are folded into the leading system message. Default: false. */
+    supportsMidConvoSystemMessages?: boolean;
+}
+
+declare interface Model<TApi extends Api> {
+    id: string;
+    name: string;
+    api: TApi;
+    provider: ProviderId;
+    baseUrl: string;
+    reasoning: boolean;
+    /**
+     * Maps pi thinking levels to provider/model-specific values.
+     * Missing keys use provider defaults. null marks a level as unsupported.
+     */
+    thinkingLevelMap?: ThinkingLevelMap;
+    input: ("text" | "image")[];
+    /** Provider input limits and cache-safe preprocessing metadata. */
+    inputLimits?: ModelInputLimits;
+    cost: ModelCost;
+    /** Prompt cache lifetimes per retention tier. Unset when the provider's cache behavior is unknown. */
+    promptCache?: ModelPromptCache;
+    contextWindow: number;
+    maxTokens: number;
+    /** Default sampling parameters for this model. See {@link StreamOptions.samplingParams}; per-request keys override these. */
+    samplingParams?: Record<string, unknown>;
+    headers?: Record<string, string>;
+    /** Compatibility overrides for OpenAI-compatible APIs. If not set, auto-detected from baseUrl. */
+    compat?: TApi extends "openai-completions" ? OpenAICompletionsCompat : TApi extends "openai-responses" | "azure-openai-responses" | "openai-codex-responses" ? OpenAIResponsesCompat : TApi extends "anthropic-messages" ? AnthropicMessagesCompat : TApi extends "bedrock-converse-stream" ? BedrockCompat : TApi extends "mistral-conversations" ? MistralConversationsCompat : never;
+}
+
+/**
+ * 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.
+ */
+declare type ModelContent = TextContent | ImageContent;
+
+declare interface ModelCost extends ModelCostRates {
+    /** Request-wide pricing tiers. The highest matching input threshold applies to the full request. */
+    tiers?: ModelCostTier[];
+}
+
+declare interface ModelCostRates {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+}
+
+declare interface ModelCostTier extends ModelCostRates {
+    /** Use this tier for requests whose total input usage exceeds this token count. */
+    inputTokensAbove: number;
+}
+
+declare interface ModelImageInputLimits {
+    /** Cache-safe resize profile applied before a new image enters conversation history. */
+    resize?: ModelImageResizeOptions;
+    /** Maximum images accepted in one provider message. */
+    maxPerMessage?: number;
+    /** Maximum images accepted across one provider request. */
+    maxPerRequest?: number;
+}
+
+declare interface ModelImageResizeOptions {
+    maxWidth?: number;
+    maxHeight?: number;
+    /** Maximum base64-encoded payload size in bytes. */
+    maxBytes?: number;
+    jpegQuality?: number;
+}
+
+declare interface ModelInputLimits {
+    /** Maximum serialized provider request size in bytes. */
+    maxRequestBytes?: number;
+    images?: ModelImageInputLimits;
+}
+
+/**
+ * Best-effort prompt cache lifetime in seconds for each retention tier a request can ask for.
+ * A missing tier means the lifetime is unknown; pi does not warm such caches.
+ */
+declare type ModelPromptCache = Partial<Record<Exclude<CacheRetention, "none">, number>>;
+
+declare type ModelThinkingLevel = "off" | ThinkingLevel;
+
+/**
+ * Who may supply the OAuth client for a scheme: Kay'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 Kay'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"];
+};
+
+/**
+ * Compatibility settings for OpenAI-compatible completions APIs.
+ * Use this to override URL-based auto-detection for custom providers.
+ */
+declare interface OpenAICompletionsCompat {
+    /** Whether the provider supports the `store` field. Default: auto-detected from URL. */
+    supportsStore?: boolean;
+    /** Whether the provider supports the `developer` role (vs `system`). Default: auto-detected from URL. */
+    supportsDeveloperRole?: boolean;
+    /** Whether the provider supports `reasoning_effort`. Default: auto-detected from URL. */
+    supportsReasoningEffort?: boolean;
+    /** Whether the provider supports `stream_options: { include_usage: true }` for token usage in streaming responses. Default: true. */
+    supportsUsageInStreaming?: boolean;
+    /** Whether streamed responses include `finish_reason`. When false, pi infers `stop` or `toolUse` when the stream ends. Default: true. */
+    supportsFinishReason?: boolean;
+    /** Which field to use for max tokens. Default: auto-detected from URL. */
+    maxTokensField?: "max_completion_tokens" | "max_tokens";
+    /** Whether tool results require the `name` field. Default: auto-detected from URL. */
+    requiresToolResultName?: boolean;
+    /** Whether a user message after tool results requires an assistant message in between. Default: auto-detected from URL. */
+    requiresAssistantAfterToolResult?: boolean;
+    /** Whether thinking blocks must be converted to text blocks with <thinking> delimiters. Default: auto-detected from URL. */
+    requiresThinkingAsText?: boolean;
+    /** Whether all replayed assistant messages must include an empty reasoning_content field when reasoning is enabled. Default: auto-detected from URL. */
+    requiresReasoningContentOnAssistantMessages?: boolean;
+    /** Format for reasoning/thinking parameter. "openai" uses reasoning_effort, "openrouter" uses reasoning: { effort }, "deepseek" uses thinking: { type } plus reasoning_effort when supported, "together" uses reasoning: { enabled } plus reasoning_effort when supported, "baseten" uses configurable chat_template_args plus reasoning_effort when supported, "zai" uses thinking: { type }, "qwen" uses top-level enable_thinking: boolean, "qwen-chat-template" uses chat_template_kwargs.enable_thinking and preserve_thinking, "chat-template" uses configurable chat_template_kwargs, "string-thinking" uses top-level thinking: string, and "ant-ling" uses reasoning: { effort } only when the mapped effort is non-null. Default: "openai". */
+    thinkingFormat?: "openai" | "openrouter" | "deepseek" | "together" | "baseten" | "zai" | "qwen" | "chat-template" | "qwen-chat-template" | "string-thinking" | "ant-ling";
+    /** Kwargs to send as `chat_template_kwargs` when `thinkingFormat` is `chat-template`. Use `{ "$var": "thinking.enabled" }`, `{ "$var": "thinking.effort" }`, or `{ "$var": "thinking.budget" }` for pi-controlled thinking values. */
+    chatTemplateKwargs?: Record<string, ChatTemplateKwargValue>;
+    /** Arguments to send as `chat_template_args` when `thinkingFormat` is `baseten`. Use `{ "$var": "thinking.enabled" }`, `{ "$var": "thinking.effort" }`, or `{ "$var": "thinking.budget" }` for pi-controlled thinking values. */
+    chatTemplateArgs?: Record<string, ChatTemplateKwargValue>;
+    /** OpenRouter-compatible routing preferences sent as the `provider` request field. */
+    openRouterRouting?: OpenRouterRouting;
+    /** Vercel AI Gateway routing preferences. Only used when baseUrl points to Vercel AI Gateway. */
+    vercelGatewayRouting?: VercelGatewayRouting;
+    /** Whether z.ai supports top-level `tool_stream: true` for streaming tool call deltas. Default: false. */
+    zaiToolStream?: boolean;
+    /**
+     * Top-level request field used to cap reasoning tokens from `thinkingBudgets`.
+     * Reasoning and the answer share `max_tokens` on these endpoints, so without a budget a
+     * reasoning-heavy turn can consume the whole response and emit no answer.
+     * `"thinking_token_budget"` is vLLM, `"thinking_budget"` is Qwen/DashScope/SGLang,
+     * `"thinking_budget_tokens"` is llama.cpp. Off by default; not set on the generated catalog.
+     */
+    thinkingTokenBudgetField?: ThinkingTokenBudgetField;
+    /** Alias for `thinkingTokenBudgetField: "thinking_token_budget"` (vLLM). Prefer `thinkingTokenBudgetField`. Default: false. */
+    supportsThinkingTokenBudget?: boolean;
+    /** Whether the provider supports OpenAI custom tools with Lark/regex grammar formats. When false, grammar-constrained tools fall back to normal function tools. Default: false; the generated model catalog enables it for capable models. */
+    supportsOpenAIGrammarTools?: boolean;
+    /** Whether the exact model accepts system or developer messages after the conversation has started. When false, later system messages are folded into the leading system message. Default: false; the generated model catalog enables it for verified models. */
+    supportsMidConvoSystemMessages?: boolean;
+    /** Whether system messages can introduce additional tools mid-conversation. Requires `supportsMidConvoSystemMessages`. Default: false; the generated model catalog enables it for capable models. */
+    supportsMidConvoToolAdditions?: boolean;
+    /** Whether the provider supports the `strict` field in tool definitions. Default: false; generated capable models enable it explicitly. */
+    supportsStrictMode?: boolean;
+    /** Cache control convention for prompt caching. "anthropic" applies Anthropic-style `cache_control` markers to the system prompt, last tool definition, and last user, assistant, or tool-result text content. */
+    cacheControlFormat?: "anthropic";
+    /** Whether to send session-affinity data from `options.sessionId`. Default: true for OpenRouter endpoints, false otherwise. */
+    sendSessionAffinityHeaders?: boolean;
+    /** Session-affinity header format: `openai` sends `session_id`, `x-client-request-id`, and `x-session-affinity`; `openai-nosession` sends `x-client-request-id` and `x-session-affinity`; `openrouter` sends `x-session-id`. Does not affect the `prompt_cache_key` body param, which is governed by cache retention. Default: auto-detected. */
+    sessionAffinityFormat?: SessionAffinityFormat;
+    /** Whether the provider supports long prompt cache retention (`prompt_cache_retention: "24h"` or Anthropic-style `cache_control.ttl: "1h"`, depending on format). Default: true. */
+    supportsLongCacheRetention?: boolean;
+    /**
+     * vLLM scheduler priority sent as the top-level `priority` request field (lower values are
+     * handled earlier; server default 0). Only meaningful when vLLM runs with
+     * `--scheduling-policy priority`; useful for keeping background/batch work from stalling
+     * interactive sessions. Off by default; not set on the generated catalog.
+     */
+    vllmPriority?: number;
+}
+
+/** Compatibility settings for OpenAI Responses APIs. */
+declare interface OpenAIResponsesCompat {
+    /** Whether the provider supports the `developer` role (vs `system`). Default: true. */
+    supportsDeveloperRole?: boolean;
+    /** Whether the exact model accepts developer or system messages after the conversation has started. When false, later system messages are folded into the leading system message. Default: false; the generated model catalog enables it for verified models. */
+    supportsMidConvoSystemMessages?: boolean;
+    /** Session-affinity header format: `openai` sends `session_id` and `x-client-request-id`; `openai-nosession` sends `x-client-request-id`; `openrouter` sends `x-session-id`. Does not affect the `prompt_cache_key` body param, which is governed by cache retention. Default: auto-detected. */
+    sessionAffinityFormat?: SessionAffinityFormat;
+    /** Whether the provider supports long prompt cache retention. This uses `prompt_cache_options.ttl: "30m"` on GPT-5.6+ and `prompt_cache_retention: "24h"` on earlier models. Default: true. */
+    supportsLongCacheRetention?: boolean;
+    /** Whether the provider supports strict JSON-schema function tools. Defaults are API-specific; generated OpenAI models enable it explicitly. */
+    supportsStrictMode?: boolean;
+    /** Whether to emit OpenAI custom tools with Lark/regex grammar formats. When false, grammar-constrained tools fall back to normal function tools. Default: false; the generated model catalog enables it for capable models. */
+    supportsOpenAIGrammarTools?: boolean;
+    /** Whether the model supports message-anchored `additional_tools` input items. Default: false. */
+    supportsAdditionalTools?: boolean;
+    /** Whether the model supports client-executed tool search for transcript-anchored additions. Default: false. */
+    supportsToolSearch?: boolean;
+    /** Whether the model accepts `prompt_cache_options` (OpenAI GPT-5.6+ prompt caching). Older OpenAI models reject the parameter. Default: false. */
+    supportsExplicitPromptCacheMode?: boolean;
+    /** Whether the provider accepts the `max_output_tokens` parameter. Some Codex-protocol gateways reject it. Default: true. */
+    supportsMaxOutputTokens?: boolean;
+}
+
+/**
+ * OpenRouter provider routing preferences.
+ * Controls which upstream providers OpenRouter routes requests to.
+ * Sent as the `provider` field in the OpenRouter API request body.
+ * @see https://openrouter.ai/docs/guides/routing/provider-selection
+ */
+declare interface OpenRouterRouting {
+    /** Whether to allow backup providers to serve requests. Default: true. */
+    allow_fallbacks?: boolean;
+    /** Whether to filter providers to only those that support all parameters in the request. Default: false. */
+    require_parameters?: boolean;
+    /** Data collection setting. "allow" (default): allow providers that may store/train on data. "deny": only use providers that don't collect user data. */
+    data_collection?: "deny" | "allow";
+    /** Whether to restrict routing to only ZDR (Zero Data Retention) endpoints. */
+    zdr?: boolean;
+    /** Whether to restrict routing to only models that allow text distillation. */
+    enforce_distillable_text?: boolean;
+    /** An ordered list of provider names/slugs to try in sequence, falling back to the next if unavailable. */
+    order?: string[];
+    /** List of provider names/slugs to exclusively allow for this request. */
+    only?: string[];
+    /** List of provider names/slugs to skip for this request. */
+    ignore?: string[];
+    /** A list of quantization levels to filter providers by (e.g., ["fp16", "bf16", "fp8", "fp6", "int8", "int4", "fp4", "fp32"]). */
+    quantizations?: string[];
+    /** Sorting strategy. Can be a string (e.g., "price", "throughput", "latency") or an object with `by` and `partition`. */
+    sort?: string | {
+        /** The sorting metric: "price", "throughput", "latency". */
+        by?: string;
+        /** Partitioning strategy: "model" (default) or "none". */
+        partition?: string | null;
+    };
+    /** Maximum price per million tokens (USD). */
+    max_price?: {
+        /** Price per million prompt tokens. */
+        prompt?: number | string;
+        /** Price per million completion tokens. */
+        completion?: number | string;
+        /** Price per image. */
+        image?: number | string;
+        /** Price per audio unit. */
+        audio?: number | string;
+        /** Price per request. */
+        request?: number | string;
+    };
+    /** Preferred minimum throughput (tokens/second). Can be a number (applies to p50) or an object with percentile-specific cutoffs. */
+    preferred_min_throughput?: number | {
+        /** Minimum tokens/second at the 50th percentile. */
+        p50?: number;
+        /** Minimum tokens/second at the 75th percentile. */
+        p75?: number;
+        /** Minimum tokens/second at the 90th percentile. */
+        p90?: number;
+        /** Minimum tokens/second at the 99th percentile. */
+        p99?: number;
+    };
+    /** Preferred maximum latency (seconds). Can be a number (applies to p50) or an object with percentile-specific cutoffs. */
+    preferred_max_latency?: number | {
+        /** Maximum latency in seconds at the 50th percentile. */
+        p50?: number;
+        /** Maximum latency in seconds at the 75th percentile. */
+        p75?: number;
+        /** Maximum latency in seconds at the 90th percentile. */
+        p90?: number;
+        /** Maximum latency in seconds at the 99th percentile. */
+        p99?: number;
+    };
+}
+
+/**
+ * The version of the conformance floor this SDK enforces — bumped whenever
+ * {@link PLUGIN_DISCLOSURE_RULES} changes, and never for anything else.
+ *
+ * Two readers, and the second is why a number beats a changelog entry. A plugin author compares it
+ * against the Kay build they target. The daemon's loader NAMES it in the
+ * `disclosure-conformance-failed` diagnostic, so a plugin that passed its own suite against an
+ * older SDK and then failed at load says "this host enforces contract N, you audited against
+ * something older" instead of leaving the author to guess whether their code or their SDK moved.
+ *
+ * `1` is the floor as published by #3210 — the first release in which an author could run this
+ * audit at all. `2` (#6880) adds the route-contract rules and tightens
+ * `template-operation-docs-missing` from "every verb on a multi-GROUP route" to "every verb on a
+ * multi-verb route": the help renderer now prints a sentence per verb at the route, so a missing
+ * one is a visible hole, not a permission-row ambiguity.
+ */
+export declare const PLUGIN_DISCLOSURE_CONTRACT = 2;
+
+/**
+ * Every rule this audit can fire, as one frozen inventory.
+ *
+ * It exists because this list IS the conformance floor a third-party plugin is held to, and the
+ * daemon enforces it fail-closed. A rule added here retroactively fails plugins that were correct
+ * yesterday, so the set may not grow as a side effect of an edit: the pinned test beside this
+ * module (`test/disclosure/conformance-contract.test.ts`) fails on any change and makes the author
+ * record it against a new {@link PLUGIN_DISCLOSURE_CONTRACT} — which is what forces the SDK release
+ * that carries the new rule to the authors it now judges (#3210).
+ *
+ * Typing {@link DisclosureViolation.rule} as this union is the half that cannot be forgotten: a
+ * rule id emitted but never listed does not compile.
+ */
+export declare const PLUGIN_DISCLOSURE_RULES: readonly ["agent-hint-missing", "agent-hint-summary-empty", "agent-hint-flows-empty", "agent-hint-triggers-missing", "scheme-claim-missing", "help-missing", "help-malformed", "help-throws", "help-uri-malformed", "help-uri-throws", "verb-coverage-missing", "template-operation-docs-missing", "verb-docs-missing", "template-accepts-missing", "template-address-unmatchable", "template-delete-effect-missing", "template-operations-missing", "template-parameter-unknown", "template-scheme-mismatch", "clamp-summary", "clamp-flow-label", "clamp-flow-when", "clamp-flow-example", "clamp-trigger-count", "clamp-trigger-item", "clamp-help-uri", "skill-link-dangling", "skill-link-missing-scheme", "skill-twin-count-mismatch", "skill-twin-missing-declaration", "skill-twin-description-mismatch", "skill-twin-file-unreadable", "skill-twin-frontmatter-name-mismatch", "skill-twin-frontmatter-description-mismatch", "skill-twin-body-mismatch"];
+
+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;
+}
+
+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";
+
+/** The host-supplied connect context a delegated scheme receives, aliased (never copied) for plugins. */
+declare type PluginDelegatedConnectContext = DelegatedConnectContext;
+
+/** What a delegated scheme's `connect` resolves with, aliased (never copied) for plugins. */
+declare type PluginDelegatedConnectResult = DelegatedConnectResult;
+
+/** What a delegated scheme's `revoke` is told: the service and scheme being disconnected. */
+declare interface PluginDelegatedRevokeContext {
+    readonly serviceId: string;
+    readonly schemeId: string;
+}
+
+/**
+ * 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 →
+ * 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
+ * needs them and fails its connect with an actionable message if it does and they are missing.
+ */
+declare interface PluginDelegatedScheme {
+    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;
+    /** Run the connect flow and mint the material to store. Throw to fail the connect. */
+    readonly connect: (ctx: PluginDelegatedConnectContext) => Promise<PluginDelegatedConnectResult>;
+    /**
+     * Mint fresh material from the current (expiring) material. Absent means non-refreshable:
+     * expired material resolves as-is (like an OAuth scheme without a refresh token).
+     */
+    readonly refresh?: (material: PluginDelegatedSecretMaterial) => Promise<PluginDelegatedSecretMaterial>;
+    /**
+     * Make the sign-in unavailable when the user disconnects: drop whatever the plugin's host holds
+     * outside the vault (an MCP host's token, say). Throw to fail the disconnect loudly. Absent
+     * means the vault record was all there was.
+     */
+    readonly revoke?: (ctx: PluginDelegatedRevokeContext) => Promise<void>;
+}
+
+/** Opaque token material a delegated scheme mints, aliased (never copied) for plugins. */
+declare type PluginDelegatedSecretMaterial = DelegatedSecretMaterial;
+
+/** One runtime-discovered service and its delegated auth scheme. */
+declare interface PluginDelegatedServiceEntry {
+    readonly descriptor: PluginServiceDescriptor;
+    readonly scheme: PluginDelegatedScheme;
+}
+
+/** One rule id from {@link PLUGIN_DISCLOSURE_RULES}. */
+export declare type PluginDisclosureRule = (typeof PLUGIN_DISCLOSURE_RULES)[number];
+
+/**
+ * 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;
+}
+
+/**
+ * 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 Kay-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;
+};
+
+/** BYOOC — the herd canonical client-axes union, aliased (never copied) for plugin authors. */
+declare type PluginOAuthSchemeClientAxes = OAuthSchemeClientAxes;
+
+/** What one connection flow unlocks and when an agent should choose it; grants no authority. */
+declare type PluginSchemeAgentHint = string;
+
+/** A capability a service advertises (e.g. a URI module) for discovery / the Integrations page. */
+declare interface PluginServiceCapability {
+    readonly id: string;
+    readonly kind: PluginCapabilityKind;
+    readonly summary: string;
+}
+
+/** A service the plugin owns — advertised for discovery and used to gate auth-backed contributions. */
+declare interface PluginServiceDescriptor {
+    readonly id: string;
+    readonly display: string;
+    readonly summary: string;
+    readonly capabilities: readonly PluginServiceCapability[];
+}
+
+/**
+ * A skill the plugin ships, content included. The manifest *declares* the skill (a
+ * `SkillContribution` naming the in-package SKILL.md); this is the runtime half — bundled
+ * plugins are compiled in with no package directory at runtime, so the package exports the
+ * instructions as data beside the file and an in-package equivalence test pins the two
+ * together (the same pattern as the manifest icon). `name` must equal the contribution's
+ * `localId`; it is the name the agent invokes, unique only within the plugin's own namespaced
+ * skill source (skill identity is `(sourceId, name)`, so same-named skills from other sources
+ * coexist rather than colliding). Still prefix it with the product it teaches
+ * (`gmail-email-triage`, not `triage`) so bare-name invocation stays unambiguous.
+ */
+declare interface PluginSkillDefinition {
+    readonly name: string;
+    /** Model-visible one-liner: when to reach for this skill. */
+    readonly description: string;
+    /** The full instructions — what a filesystem skill carries below its frontmatter. */
+    readonly content: string;
+}
+
+declare type ProviderId = KnownProvider | string;
+
+/**
+ * The call a proxy tool stands in for: the registered tool that will actually run, and the input
+ * it will run with. Returned by {@link ToolPermissionHint.deriveProxiedCall}.
+ */
+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. */
+    readonly input: Record<string, unknown>;
+}
+
+declare interface RawResource {
+    readonly uri: string;
+    readonly content: string | Uint8Array;
+    readonly mimeType: string;
+    readonly metadata?: RawResourceMetadata;
+    readonly selector?: SelectorDisposition;
+}
+
+declare interface RawResourceCacheControl {
+    /** False marks degraded/fallback content that read-through caches must not store. */
+    readonly store?: boolean;
+}
+
+declare interface RawResourceIdentity {
+    readonly id: string;
+    readonly version: string;
+    readonly variantId?: string;
+}
+
+declare interface RawResourceMetadata {
+    readonly size?: number;
+    readonly finalUrl?: string;
+    /** Provider resource MIME type; absent when the source does not report one. */
+    readonly sourceMimeType?: string;
+    readonly notes?: readonly string[];
+    readonly cache?: RawResourceCacheControl;
+    /**
+     * The absolute local filesystem path the resource's bytes were read from,
+     * when the transport read them from local disk. Converter-facing
+     * provenance: finalize threads it into the content probe so a converter
+     * can direct shell tools at the file (e.g. archive extraction). Absent for
+     * remote/synthesized content.
+     */
+    readonly localPath?: string;
+    /**
+     * Opaque source-native revision suitable only for a later equality check.
+     * A host records it as the session's witness for this resource; when a
+     * module reports none, the host records a content digest of `content`
+     * instead (`contentDigest`, prefixed `sha256:`), which the module can
+     * reproduce at mutation time from the same content its read returns.
+     */
+    readonly revision?: string;
+    /**
+     * Opaque immutable identity for the exact resource bytes returned by a
+     * provider. Transport preserves it for observers; it never parses it.
+     */
+    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
+     * (`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
+     * this; consumers that need the exact bytes keep `uri`.
+     */
+    readonly canonicalUri?: string;
+}
+
+/**
+ * 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 {
+    readonly serviceId: string;
+    /**
+     * 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
+     * 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.
+     */
+    readonly schemeId?: string;
+    /**
+     * 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
+     * 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.
+     */
+    readonly requiredScopes?: readonly string[];
+    /**
+     * Ordered any-of/all-of scope requirement for this capability. Mutually exclusive with the
+     * legacy `requiredScopes`; alternatives are evaluated from provider-returned grant truth.
+     */
+    readonly scopeRequirement?: ScopeRequirement;
+    /**
+     * 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
+     * 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.
+     */
+    readonly connectServiceId?: string;
+}
+
+/**
+ * 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.
+ */
+declare interface ResolvedAuth {
+    readonly accessToken: string;
+    readonly account: AuthAccount;
+    readonly identityMode: IdentityMode;
+    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.
+     */
+    readonly fields?: Readonly<Record<string, string>>;
+}
+
+declare type ResolveExternalCliFailureReason = "not-external-cli" | "no-connection" | "account-ambiguous" | "account-not-found" | "not-authorized" | "host-unavailable";
+
+declare type ResolveExternalCliResult = {
+    readonly ok: true;
+    readonly account: AuthAccount;
+    readonly runner: UriExternalCliRunner;
+} | {
+    readonly ok: false;
+    readonly reason: ResolveExternalCliFailureReason;
+    readonly message: string;
+    readonly accounts?: readonly AuthAccount[];
+};
+
+/**
+ * Derive a stable provider account id (and optional label) from a freshly connected access token,
+ * 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
+ * into `label`. Populating `identity` is what lets the agent know the user's handle/email for a
+ * connected service without asking.
+ */
+declare type ResolvePluginAccountId = (accessToken: string) => Promise<{
+    readonly accountId: string;
+    readonly label?: string;
+    readonly identity?: AccountIdentity;
+}>;
+
+/** Enumerate every provider account a fresh OAuth grant powers. */
+declare type ResolvePluginAccounts = (accessToken: string) => Promise<readonly {
+    readonly accountId: string;
+    readonly label?: string;
+    readonly identity?: AccountIdentity;
+}[]>;
+
+declare interface ResolveTokenFailure {
+    readonly ok: false;
+    readonly reason: ResolveTokenFailureReason;
+    /** Actionable text the wrapper surfaces verbatim to the agent. */
+    readonly message: string;
+    /** When ambiguous, the candidate accounts so the agent can pick one. */
+    readonly accounts?: readonly AuthAccount[];
+}
+
+/** Reason a token could not be resolved, with a short agent-facing message. */
+declare type ResolveTokenFailureReason = "no-connection" | "account-ambiguous" | "account-not-found" | "refresh-failed" | "not-authorized";
+
+declare type ResolveTokenResult = ResolveTokenSuccess | ResolveTokenFailure;
+
+declare interface ResolveTokenSuccess {
+    readonly ok: true;
+    readonly auth: ResolvedAuth;
+}
+
+/** One all-of arm in an ordered scope requirement. */
+declare interface ScopeAlternative {
+    readonly allOf: readonly ScopeNeed[];
+}
+
+/** One scope in an authorization requirement; `reason` is presentation metadata only. */
+declare interface ScopeNeed {
+    readonly scope: string;
+    readonly reason?: string;
+}
+
+/**
+ * The minimum OAuth authority for one action.
+ *
+ * Alternatives are ordered by acquisition preference. Evaluation accepts the first covered arm;
+ * when none is covered, callers request only the first arm rather than unioning unrelated grants.
+ */
+declare interface ScopeRequirement {
+    readonly purpose: string;
+    readonly alternatives: readonly ScopeAlternative[];
+}
+
+declare interface SearchCitation {
+    readonly url: string;
+    readonly title?: string;
+    readonly citedText?: string;
+}
+
+/**
+ * Shared request shape passed to every provider. Providers MUST ignore knobs
+ * they do not support rather than approximate them.
+ */
+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,
+     * or ranking (oh-my-pi's Tavily `topic=news` coupling silently dropped docs).
+     * Providers without temporal filtering MUST ignore it silently.
+     */
+    readonly recency?: "day" | "week" | "month" | "year";
+    /** Max results to surface (advisory; providers clamp to their own limits). */
+    readonly limit?: number;
+    /** Provider-specific: max synthesis output tokens (ignored if unsupported). */
+    readonly maxOutputTokens?: number;
+}
+
+/**
+ * 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 —
+ * per-call context (the abort signal and the {@link SearchProviderContext}) is
+ * threaded into {@link search} and {@link isAvailable}.
+ */
+declare abstract class SearchProvider {
+    /** Registry id. Builtins use the reserved `builtin:` namespace. */
+    abstract readonly id: SearchProviderId;
+    /** Human label for diagnostics/UI. */
+    abstract readonly label: string;
+    /**
+     * LLM provider key whose credential this provider reuses (e.g. `anthropic`).
+     * Identifies a builtin's provider preference. Empty for providers with their own key;
+     * it does not create an active-model-first or catch-next execution order.
+     */
+    abstract readonly providerId: string;
+    /**
+     * 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`.
+     */
+    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.
+     */
+    abstract isAvailable(ctx?: SearchProviderContext): Promise<boolean> | boolean;
+    /** Run the search. Throw {@link SearchProviderError} on a provider failure. */
+    abstract search(params: SearchParams, signal?: AbortSignal, ctx?: SearchProviderContext): Promise<SearchResponse>;
+}
+
+/**
+ * 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.
+ */
+declare interface SearchProviderContext {
+    readonly auth?: ExtensionAuthContext;
+}
+
+/** Registry id of a search provider, e.g. `builtin:anthropic`. Open-ended for extensions. */
+declare type SearchProviderId = string;
+
+declare interface SearchResponse {
+    /** Registry id of the provider that produced this response. */
+    readonly provider: SearchProviderId;
+    readonly query: string;
+    /** Requested model. A separately reported response model is not silently substituted here. */
+    readonly modelReference?: string;
+    readonly responseModelReference?: string;
+    readonly usage?: SearchUsageEvidence;
+    /** Synthesized natural-language answer, when the provider returns one. */
+    readonly answer?: string;
+    readonly sources: readonly SearchSource[];
+    readonly citations?: readonly SearchCitation[];
+}
+
+declare interface SearchSource {
+    readonly url: string;
+    readonly title?: string;
+    readonly snippet?: string;
+    readonly publishedDate?: string;
+}
+
+/** Evidence for the terminal native attempt; this is not the logical call's aggregate bill. */
+declare interface SearchUsageEvidence {
+    /** Non-cached input; cached input and reasoning output are reported separately, never counted twice. */
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    readonly cacheReadTokens?: number;
+    readonly cacheWriteTokens?: number;
+    /** Subset of outputTokens, not an additional output charge. */
+    readonly reasoningTokens?: number;
+    readonly nativeSearchRequests?: number;
+    readonly modelUsdEstimate?: number;
+    readonly reportedToolUsd?: number;
+    readonly reportedCredits?: number;
+    readonly complete: boolean;
+}
+
+declare type SelectorDisposition = {
+    readonly kind: "deferred";
+    readonly window?: LineSelector;
+} | {
+    readonly kind: "applied";
+} | {
+    readonly kind: "invalid";
+    readonly message: string;
+};
+
+declare type SessionAffinityFormat = "openai" | "openai-nosession" | "openrouter";
+
+/**
+ * The cheap, closed snapshot of primary session facts a {@link ToolAvailability} predicate reads to
+ * decide whether its tool applies in the current context. The kernel builds one at session start and
+ * rebuilds it on each {@link import("../agent-session/agent-session.ts").AgentSession.reroot} (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
+ * 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,
+ * 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). */
+    readonly cwd: string;
+    /**
+     * The enclosing VCS repository root for {@link cwd}, or `null` when `cwd` is not inside a repo.
+     * Host-resolved via {@link import("../agent-session/agent-session.ts").AgentSessionOptions.resolveRepoRoot};
+     * always `null` when the host injects no resolver (the kernel never computes VCS facts itself).
+     */
+    readonly repoRoot: string | null;
+}
+
+declare interface TextContent {
+    type: "text";
+    text: string;
+    textSignature?: string;
+}
+
+declare type ThinkingLevel = "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+
+declare type ThinkingLevelMap = Partial<Record<ModelThinkingLevel, string | null>>;
+
+/** Top-level request field used to cap reasoning tokens on OpenAI-compatible servers. */
+declare type ThinkingTokenBudgetField = "thinking_token_budget" | "thinking_budget" | "thinking_budget_tokens";
+
+/** What a tool call is about to do, from the host's point of view. */
+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
+ * 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.
+ */
+declare interface ToolAvailability {
+    /** 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;
+}
+
+/**
+ * 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
+ * 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
+ * arity.
+ */
+declare type ToolCallInterceptor = (call: ToolCallInvocation, next: () => Promise<AgentToolResult<unknown>>) => Promise<AgentToolResult<unknown>>;
+
+/** One tool call as an interceptor sees it, before the tool's `execute` has run. */
+declare interface ToolCallInvocation {
+    readonly toolCallId: string;
+    readonly toolName: string;
+    /** The call's arguments, already through `prepareArguments` — the shape `execute` receives. */
+    readonly params: unknown;
+    readonly signal: AbortSignal | undefined;
+    /**
+     * See {@link ToolCallTarget}. `undefined` when the session cannot say: a URI verb whose
+     * address matches no registered module, a builtin non-URI tool, or a wrap built without a
+     * resolver.
+     */
+    readonly target: ToolCallTarget | undefined;
+    /** See {@link ToolCallOrigin}. `"model"` for a wrap built without a resolver. */
+    readonly origin: ToolCallOrigin;
+    /** See {@link ToolCallModel}. Absent for a wrap built without a resolver. */
+    readonly model?: ToolCallModel;
+    /** Register a validation run before each real execute; unavailable on older hosts. */
+    readonly addExecutionGuard?: (guard: () => void | Promise<void>) => void;
+}
+
+/**
+ * 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
+ * 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.
+ */
+declare interface ToolCallModel {
+    readonly provider: string;
+    readonly id: string;
+    readonly input: readonly ("text" | "image")[];
+}
+
+/**
+ * Who issued the call: the model, through the harness loop, or a host through
+ * `AgentSession.invokeTool` (a slash command, an RPC, a host hook). Both run the same chain, so
+ * a policy about the MODEL's behaviour must read this rather than assume every call is its.
+ */
+declare type ToolCallOrigin = "model" | "host";
+
+/**
+ * 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
+ * "which integration is this call about" reads this instead of re-parsing `params`.
+ */
+declare type ToolCallTarget = {
+    readonly kind: "uri";
+    /** The address as the model wrote it (selector and all). */
+    readonly uri: string;
+    readonly moduleId: string;
+    readonly ownerExtensionId?: string;
+} | {
+    readonly kind: "tool";
+    readonly ownerExtensionId?: string;
+};
+
+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 {@link import("./auth/runtime.ts").ExtensionAuthRuntime}; absent in always-on contexts
+     * (the wrapper short-circuits with an actionable message when undefined).
+     */
+    readonly auth?: ExtensionAuthContext;
+    /**
+     * 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 —
+     * use {@link ExtensionContext.runEffect}. Absent when the host wires no background-task manager.
+     */
+    readonly backgroundTasks?: ExtensionBackgroundTasksApi;
+    readonly toolExecutionPolicyDefaults?: ToolExecutionPolicyDefaults;
+    /**
+     * Ask the active run to stop after this tool batch, compact during post-run settlement, then
+     * continue. This is the in-tool counterpart of idle-only `AgentSession.compact()`: it never
+     * waits for the run that currently owns promptability admission and therefore cannot deadlock
+     * behind itself. Present only with a live session. One request may be pending at a time.
+     */
+    readonly requestMidTurnCompaction?: (customInstructions?: string, trigger?: "command" | "suggestion") => MidTurnCompactionRequest;
+    /**
+     * 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
+     * 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.
+     * 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"`).
+     */
+    readonly reroot?: (newCwd: string, reason?: string) => Promise<void>;
+    /**
+     * The host-provided per-extension writable data root (see {@link ExtensionPaths}). Present when the
+     * session was built with a host {@link ExtensionDataDirResolver} AND the context is scoped to an
+     * owning extension (a tool/handler context); absent in session-less inventory/standalone contexts
+     * and in any unowned context, like {@link auth}. When present, `paths.dataDir` already exists on
+     * disk (the runtime creates it before handing back the context), so a consumer can write
+     * immediately.
+     */
+    readonly paths?: ExtensionPaths;
+}
+
+declare interface ToolDefinition<TParams extends ToolParametersWire = ToolParametersWire, TDetails = unknown> {
+    /** Tool name (used in LLM tool calls) */
+    name: string;
+    /** Human-readable label for UI */
+    label: string;
+    /** Description for LLM */
+    description: string;
+    /** Optional one-line snippet for the Available tools section in the default system prompt. Custom tools are omitted from that section when this is not provided. */
+    promptSnippet?: string;
+    /** Optional guideline bullets appended to the default system prompt Guidelines section when this tool is active. */
+    promptGuidelines?: string[];
+    /** Parameter schema as a plain JSON Schema wire object (see {@link ToolParametersWire}). */
+    parameters: TParams;
+    /** Optional compatibility shim to prepare raw tool call arguments before schema validation. Must return an object conforming to TParams. */
+    prepareArguments?: (args: unknown) => TParams;
+    /**
+     * Per-tool execution mode override.
+     * - "sequential": this tool must execute one at a time with other tool calls.
+     * - "parallel": this tool can execute concurrently with other tool calls.
+     *
+     * If omitted, the default execution mode applies.
+     */
+    executionMode?: ToolExecutionMode;
+    /**
+     * How long a single execution may legitimately stay silent (#3785).
+     * - `"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
+     *   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
+     * of the tool's contract; a wedged `"long"` tool is only recoverable by an
+     * explicit Stop.
+     */
+    durationClass?: "fast" | "long";
+    /**
+     * Optional capability⇄scheme binding. When present this tool is auth-gated: discoverable when
+     * unauthed, callable once the binding is satisfied. The SDK's {@link withResolvedAuth}
+     * stamps this; absent means an ordinary always-on tool (additive — nothing changes for existing
+     * tools that omit it).
+     */
+    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
+     * 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`),
+     * 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
+     * scheme)**.
+     */
+    permission?: ToolPermissionHint;
+    /** Run policies this tool supports. Defaults to ["inline"] when omitted. */
+    supportedRunPolicies?: readonly ToolRunPolicy[];
+    /** Tool-level default execution policy when caller/session do not override. Defaults to inline semantics when omitted. */
+    defaultRunPolicy?: ToolExecutionPolicyDefaults;
+    /** Execute the tool. */
+    execute(toolCallId: string, params: ToolExecutionAwareParams<TParams>, signal: AbortSignal | undefined, onUpdate: AgentToolUpdateCallback<TDetails> | undefined, ctx: ToolContext): Promise<AgentToolResult<TDetails>>;
+}
+
+/** Runtime execute input shape that always allows reserved execution directives. */
+declare type ToolExecutionAwareParams<T> = T & {
+    readonly _execution?: ToolExecutionDirective;
+};
+
+/** Shared per-call execution directive accepted by ToolDefinition inputs. */
+declare interface ToolExecutionDirective {
+    /** Explicit execution mode override for this specific tool call. */
+    readonly mode?: ToolRunPolicy;
+    /** Preferred background task id when mode resolves to background. */
+    readonly preferredTaskId?: string;
+    /** Per-call auto-background threshold override in milliseconds. */
+    readonly autoBackgroundAfterMs?: number;
+}
+
+/**
+ * Configuration for how tool calls from a single assistant message are executed.
+ *
+ * - "sequential": each tool call is prepared, executed, and finalized before the next one starts.
+ * - "parallel": tool calls are prepared sequentially, then allowed tools execute concurrently.
+ *   `tool_execution_end` is emitted in tool completion order after each tool is finalized,
+ *   while tool-result message artifacts are emitted later in assistant source order.
+ */
+declare type ToolExecutionMode = "sequential" | "parallel";
+
+/** Optional host/session defaults used when a call does not provide an explicit execution directive. */
+declare interface ToolExecutionPolicyDefaults {
+    readonly mode?: ToolRunPolicy;
+    readonly autoBackgroundAfterMs?: number;
+}
+
+/**
+ * A tool's parameters as a plain JSON Schema wire object, opaque (`unknown`) so
+ * the tool seam stays decoupled from any one schema library.
+ */
+declare type ToolParametersWire = unknown;
+
+/**
+ * A tool's own declaration of how a call to it should classify, supplied on the tool
+ * 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
+ * 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.
+ *
+ * The host is trusted to supply honest values; a declared `kind` of `read` moves a call below
+ * the protected-path hard-deny (which only fires for non-read kinds), so a tool that could
+ * touch protected config must NOT declare `read`. Kay's embedded-experience tools never touch
+ * `configDir`, so this is safe for them. `read` is also what every capability surface reports as
+ * "read-only" (Kay'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
+ * declares {@link ToolPermissionHint.quiet} and keeps its honest `kind`.
+ */
+declare interface ToolPermissionHint {
+    readonly kind?: ToolActionKind;
+    readonly scheme?: string;
+    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 —
+     * 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
+     * stay inside the warm prompt-cache window) rather than the default window sized for a
+     * human who may be away. Undeclared keeps the ask rail's own default.
+     */
+    readonly askTimeoutMs?: number;
+    /**
+     * 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).
+     */
+    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
+     * 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).
+     *
+     * 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 — Kay'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>" }`
+     * rule gates one of its tools.
+     */
+    readonly deriveClassification?: (input: Record<string, unknown>) => DerivedToolClassification | undefined;
+    /**
+     * Declares that this call is really a call to ANOTHER registered tool, so the gate classifies
+     * the call that will actually run rather than the tool that carries it. Returns the target's
+     * name and the input it will be executed with; `undefined` means "not a proxied call", and the
+     * static hint / fail-closed default applies to the carrier itself.
+     *
+     * This is the parity seam a proxy tool needs and {@link deriveClassification} cannot provide: a
+     * 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.
+     *
+     * A hop ADDS the target's rules; it never SUBTRACTS the carrier's. The carrier's own
+     * classification rides along ({@link ToolActionPreflight.carrier}) and the controller takes the
+     * STRICTEST verdict of the two, so a deny on the proxy tool, its scheme, or its declared
+     * defaults still blocks, and a proxied call is never more permitted than calling the proxy
+     * directly. Routing a call through a proxy therefore cannot reach anything either identity
+     * 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
+     * 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
+     * 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
+     * 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 (Kay'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
+     * 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
+     * CLASSIFICATION rule and nothing carries it to an executor.
+     */
+    readonly deriveProxiedCall?: (input: Record<string, unknown>) => ProxiedToolCall | undefined;
+    /**
+     * 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".
+     *
+     * 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
+     * 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
+     * have raised. Kay'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
+     * for why a carrier must therefore refuse a carrier as a target.
+     */
+    readonly quiet?: boolean;
+    /**
+     * Plugin-declared default permission for this tool, compiled into a defaults-level rule.
+     *
+     * `"ask"` prompts by default and elevates over EVERY mode, `allow` included. `"never"`
+     * compiles to a deny. `"allow"` declares the capability safe and satisfies the conservative
+     * modes, so `default` and `ask` stop prompting for it. Undeclared leaves the mode deciding,
+     * which for anything not classified `read` means a prompt.
+     *
+     * `"allow"` used to compile to nothing, which made declaring it a no-op and left the mode's
+     * blanket ask in charge of tools their own plugin had called safe (fixed 2026-08-20). This
+     * is a floor, never a ceiling: a user or learned setting still shadows it by level
+     * precedence, and no declaration here can lift the protected-path deny.
+     */
+    readonly defaultPermission?: "allow" | "ask" | "never";
+}
+
+/** Controls whether a tool is expected to complete inline or via background adoption. */
+declare type ToolRunPolicy = "inline" | "background";
+
+declare interface UriAgentHint {
+    readonly summary: string;
+    readonly commonFlows?: readonly UriCommonFlow[];
+    readonly helpUri?: string;
+    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
+     * 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.
+ */
+declare interface UriAuthActionPolicy {
+    readonly actions: Readonly<Record<string, ScopeRequirement>>;
+    classifyOperation(request: {
+        readonly operation: UriOperation;
+        readonly uri: string;
+    }): UriAuthActionClassification | undefined;
+}
+
+declare interface UriAuthRef {
+    readonly serviceId: string;
+    readonly schemeId: string;
+    readonly accountId?: string;
+}
+
+declare interface UriAuthRequirement {
+    readonly serviceId: string;
+    /**
+     * Optional scheme preference. Absent binds service-level: any injectable scheme of the
+     * service satisfies the module, and an explicit account resolves against its own backing
+     * scheme. Present, it names the scheme resolution tries first.
+     */
+    readonly schemeId?: string;
+    /**
+     * The scopes this module needs its resolved credential to carry. Threaded by
+     * the host's dispatch into every credential load, so a grant-enforcing vault
+     * can refuse the module per call. Absent declares no scope requirement.
+     */
+    readonly requiredScopes?: readonly string[];
+    /**
+     * 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`.
+     */
+    readonly connectServiceId?: string;
+}
+
+declare type UriBackingCandidate = {
+    readonly path: string;
+    readonly root: string;
+    readonly relativePath?: never;
+    /** Optional display label for where the content canonically comes from (e.g. its source repository), rendered beside the path in projection metadata. Opaque display text; never parsed. */
+    readonly sourceRepositoryLabel?: string;
+} | {
+    /** Path relative to the sole host-protected root owned by this module. */
+    readonly relativePath: string;
+    readonly path?: never;
+    readonly root?: never;
+    /** Optional display label for where the content canonically comes from (e.g. its source repository), rendered beside the path in projection metadata. Opaque display text; never parsed. */
+    readonly sourceRepositoryLabel?: string;
+};
+
+declare interface UriCacheInvalidation {
+    /** Drop cached entries whose cache URI starts with this prefix. */
+    readonly prefix?: string;
+    /** Drop the exact cache URI. */
+    readonly uri?: string;
+}
+
+declare interface UriCachePolicy {
+    /** Read-family cache TTL in milliseconds; absent or zero means not cached. */
+    readonly ttlMs?: number;
+    /** Mutation directive applied after a successful write/edit/delete. */
+    readonly invalidate?: readonly UriCacheInvalidation[];
+}
+
+/**
+ * Resolve cache policy for a concrete URI operation. User-specific modules that
+ * return a policy must declare `requiresAuth` or `requiresConnection` so hosts
+ * can partition cache keys by identity.
+ */
+declare type UriCachePolicyResolver = (operation: UriOperation, cacheUri: string, ctx: UriResolveContext) => UriCachePolicy | undefined;
+
+declare type UriClaim = UriSchemeClaim | UriPatternClaim | UrlPatternClaim;
+
+declare interface UriCommonFlow {
+    readonly label: string;
+    readonly when?: string;
+    readonly example: string;
+}
+
+declare interface UriConnection {
+    readonly id: string;
+    readonly moduleId: string;
+    readonly adapterId: string;
+    readonly displayName: string;
+    readonly authRef?: UriAuthRef;
+    readonly metadata?: Record<string, unknown>;
+    /**
+     * Carries the vault's default flag for the account behind this row. A
+     * selector-less address resolves to the single flagged row; the flag is per
+     * service + scheme, so a module that accepts two schemes (GitHub OAuth and
+     * PAT) can see two, which resolves as ambiguous rather than guessing.
+     */
+    readonly isDefault?: boolean;
+}
+
+/**
+ * The typed answer to "can this be undone?" for a route's `delete` verb.
+ *
+ * - `trash`: moved somewhere recoverable; `restore` names the address or payload that
+ *   brings it back ("edit with {addLabels:['INBOX']}").
+ * - `permanent`: gone on success.
+ * - `conditional`: depends on the address or payload; `how` states the rule
+ *   ("trash by default; ?permanent=true deletes permanently").
+ */
+declare type UriDeleteEffect = {
+    readonly kind: "trash";
+    readonly restore?: string;
+} | {
+    readonly kind: "permanent";
+} | {
+    readonly kind: "conditional";
+    readonly how: string;
+};
+
+declare type UriDescribeContext = Pick<UriResolveContext, "cwd" | "sessionId">;
+
+declare interface UriExample {
+    readonly task: string;
+    readonly uri: string;
+    readonly operation?: UriOperation;
+}
+
+declare interface UriExtensionModule extends Omit<UriModule, "verbs"> {
+    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
+     * 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; may only strengthen the verb default. */
+    readonly permission?: UriExtensionOperationPermissionPolicy;
+    /** False rejects generic write-tool `source` copies before source fetch. */
+    readonly acceptsSourceCopy?: boolean;
+}
+
+declare interface UriExtensionOperationPermissionPolicy {
+    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>;
+}
+
+declare interface UriExternalCliRunRequest {
+    readonly args: readonly string[];
+    readonly cwd?: string;
+    readonly timeoutMs?: number;
+    readonly maxOutputChars?: number;
+    readonly signal?: AbortSignal;
+}
+
+declare interface UriExternalCliRunResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly stdoutTruncated?: boolean;
+    readonly stderrTruncated?: boolean;
+}
+
+declare interface UriHelp {
+    readonly uri: string;
+    readonly title: string;
+    readonly summary: string;
+    readonly capabilities?: readonly UriNodeCapability[];
+    readonly templates?: readonly UriTemplate[];
+    readonly examples?: readonly UriExample[];
+    readonly notes?: readonly string[];
+}
+
+declare interface UriHintTriggers {
+    readonly keywords?: readonly string[];
+    readonly patterns?: readonly string[];
+}
+
+declare interface UriListItem {
+    readonly uri: string;
+    readonly title?: string;
+    readonly summary?: string;
+    /** Provider resource MIME type; absent when the source does not report one. */
+    readonly sourceMimeType?: string;
+    readonly operations?: readonly UriOperation[];
+}
+
+declare interface UriListMetadata {
+    readonly totalCount?: number;
+    readonly totalCountLabel?: string;
+    readonly returnedCount?: number;
+    /**
+     * True when the provider could not search/enumerate the whole corpus for this
+     * page, so the result may be missing matches (e.g. a federated query that spans
+     * multiple stores and timed out part way). The caller should treat the result as
+     * partial and, where possible, narrow the scope. Omit when results are complete.
+     */
+    readonly incompleteSearch?: boolean;
+}
+
+declare interface UriListParams {
+    readonly cursor?: string;
+    readonly limit?: number;
+}
+
+declare interface UriListResult {
+    readonly uri: string;
+    readonly items: readonly UriListItem[];
+    readonly nextCursor?: string;
+    readonly metadata?: UriListMetadata;
+}
+
+declare type UriLocateContext = Pick<UriResolveContext, "cwd" | "signal" | "connection" | "sessionId" | "paths"> & {
+    /** Exact resource returned by the read whose supplemental backing is being located. */
+    readonly readResource?: RawResource;
+};
+
+declare type UriLocateResult = {
+    readonly kind: "candidate";
+    readonly candidate: UriBackingCandidate;
+} | {
+    readonly kind: "malformed";
+    readonly message: string;
+} | {
+    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
+     * `uriCatalogTitle`.
+     */
+    readonly title?: string;
+    readonly fallback?: boolean;
+    readonly claims?: readonly UriClaim[];
+    /** 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;
+    /**
+     * 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>;
+    readonly getCachePolicy?: UriCachePolicyResolver;
+    /** Retained matching escape hatch; future dispatch should prefer compiled claims. */
+    matches(input: string, ctx: UriResolveContext): boolean;
+    normalize?(input: string, ctx: UriResolveContext): UriNormalizeResult | undefined;
+    describe?(input: string, ctx: UriDescribeContext): UriResourceDescription | undefined;
+    locate?(input: string, ctx: UriLocateContext): Promise<UriLocateResult>;
+    read(input: string, ctx: UriResolveContext): Promise<RawResource>;
+    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.
+     */
+    writeBytes?(input: string, bytes: Uint8Array, source: UriSourceDescriptor, ctx: UriResolveContext): Promise<UriMutationResult | void>;
+    edit?(input: string, patch: UriPayload, ctx: UriResolveContext): Promise<UriMutationResult>;
+    list?(input: string, params: UriListParams, ctx: UriResolveContext): Promise<UriListResult>;
+    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. */
+declare interface UriMutationReceipt {
+    readonly uri: string;
+    readonly operation: "create" | "update" | "trash" | "restore" | "delete";
+    readonly state: "active" | "trashed" | "deleted";
+    readonly revision?: string;
+    readonly changedFields?: readonly string[];
+    readonly recoverable: boolean;
+    readonly recoveryUri?: string;
+    readonly originalUri?: string;
+    readonly restoreTarget?: string;
+}
+
+declare interface UriMutationResult {
+    readonly uri: string;
+    readonly summary?: string;
+    readonly resource?: RawResource | JsonValue;
+    readonly validation?: readonly UriValidationMessage[];
+    readonly metadata?: Record<string, unknown>;
+    /** Typed state/recovery evidence; successful callers may trust it without a proof read. */
+    readonly receipt?: UriMutationReceipt;
+    /** Opaque source-native revision after this successful mutation. */
+    readonly revision?: string;
+}
+
+declare interface UriNodeCapability {
+    readonly rel: string;
+    readonly operation: UriOperation;
+    readonly uri: string;
+    readonly title: string;
+    readonly description?: string;
+    readonly parameters?: readonly UriParameter[];
+    readonly accepts?: UriPayloadContract;
+    readonly returns?: UriPayloadContract;
+}
+
+declare interface UriNormalizeResult {
+    readonly uri: string;
+    readonly source: string;
+}
+
+declare type UriOperation = "help" | "read" | "write" | "edit" | "list" | "search" | "delete";
+
+/**
+ * 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";
+    readonly required: boolean;
+    readonly description?: string;
+    readonly schema: JsonSchema;
+    readonly examples?: readonly unknown[];
+}
+
+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
+     * 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 examples?: readonly string[];
+}
+
+declare interface UriPatternInit {
+    readonly protocol?: string;
+    readonly hostname?: string;
+    /**
+     * Slash-delimited path pattern. A final capture may use `:name*` to consume
+     * the remaining path segments, preserving `/` in the captured value.
+     */
+    readonly pathname?: string;
+    readonly search?: string;
+}
+
+declare type UriPayload = string | JsonValue;
+
+declare interface UriPayloadContract {
+    readonly name: string;
+    readonly mediaType?: string;
+    readonly description?: string;
+    /** Omitted when the node accepts or returns an unstructured payload. */
+    readonly schema?: JsonSchema;
+    /** Cross-value invariants the module enforces but plain JSON Schema cannot express. */
+    readonly semanticConstraints?: readonly string[];
+    readonly examples?: readonly unknown[];
+}
+
+/**
+ * The three-state permission vocabulary a plugin declares for its default permissions.
+ * Maps to `PermissionRule.effect`: `allow` → allow, `ask` → ask, `never` → deny.
+ */
+declare type UriPermissionDefault = "allow" | "ask" | "never";
+
+/**
+ * Plugin-declared default permission for each verb group (read/write/edit/delete).
+ * Undeclared verb groups default to `"allow"` (fail-open, same optionality as
+ * {@link UriVerbDocs}). Lives here in the protocol layer (beside `UriVerbDocs`)
+ * so both `@herd/uri-extensions`' `UriExtensionModule` and herd-agent's kernel
+ * `UriModule` can carry it.
+ */
+declare interface UriPermissionDefaults {
+    readonly read?: UriPermissionDefault;
+    readonly write?: UriPermissionDefault;
+    readonly edit?: UriPermissionDefault;
+    readonly delete?: UriPermissionDefault;
+}
+
+/** The read shape a caller may request via {@link UriResolveContext.format}. */
+declare type UriReadFormat = "observation";
+
+declare interface UriResolveContext {
+    readonly cwd: string;
+    readonly signal?: AbortSignal;
+    readonly connection?: UriConnection;
+    /** Host-populated execution auth for verb handlers; always absent during matching. */
+    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.
+     *
+     * Absent when no session owns the dispatch: registry matching and permission pre-checks
+     * resolve a URI outside any verb call.
+     */
+    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
+     * 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 (Kay'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
+     * 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.
+     */
+    readonly actor?: string;
+    /**
+     * Identity of the tool invocation that owns this dispatch, stamped by the host from its
+     * execution frame. Like `sessionId`, this is never accepted from URI arguments or payloads.
+     * Absent for dispatches that do not run inside a session-owned tool invocation.
+     */
+    readonly invocation?: {
+        readonly toolCallId: string;
+        readonly sessionId: string;
+        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
+         * module recording this onto a durable artifact must treat absence as unresolved provenance,
+         * not as "no run was active".
+         */
+        readonly runId?: string;
+        /** The registered name of the tool making this call, when the host's frame carried one. */
+        readonly toolName?: string;
+    };
+    /**
+     * 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
+     * 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
+     * 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. 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 —
+     * 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
+     * absence on read.
+     */
+    readonly paths?: {
+        readonly dataDir: string;
+    };
+    /**
+     * What this session last saw of the resource, handed to every mutation: the
+     * module's own `RawResourceMetadata.revision` from the last read, else the
+     * host's content digest of what that read returned. Never model input. A
+     * module holding the current content compares with `assertResourceUnchanged`;
+     * absent means the host requires no witness for this call and the module
+     * proceeds as before.
+     */
+    readonly expectedRevision?: 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. */
+    readonly writeSource?: UriSourceDescriptor;
+}
+
+declare interface UriResolvedAuth {
+    readonly connection?: UriConnection;
+    /** Present only for verb handlers of a module declaring `requiresAuth`; absent during matching. */
+    readonly credential?: UriResolvedCredential;
+    /** 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. */
+    readonly title?: string;
+    /** Provider-owned public URL when the resource also has a web address. */
+    readonly sourceUrl?: string;
+}
+
+declare interface UriSchemeClaim {
+    readonly kind: "scheme";
+    readonly scheme: string;
+}
+
+declare interface UriSearchItem {
+    readonly uri: string;
+    readonly title?: string;
+    readonly summary?: string;
+    /** Provider resource MIME type; absent when the source does not report one. */
+    readonly sourceMimeType?: string;
+    readonly score?: number;
+    readonly reason?: string;
+    readonly operations?: readonly UriOperation[];
+}
+
+declare interface UriSearchParams {
+    readonly query: string;
+    readonly limit?: number;
+    readonly cursor?: string;
+}
+
+declare interface UriSearchResult {
+    readonly uri: string;
+    readonly query: string;
+    readonly items: readonly UriSearchItem[];
+    readonly nextCursor?: string;
+    /**
+     * Optional result-set metadata, mirroring {@link UriListResult.metadata}. Lets a
+     * search surface completeness signals such as {@link UriListMetadata.incompleteSearch}
+     * so the caller knows the matches may be partial.
+     */
+    readonly metadata?: UriListMetadata;
+}
+
+/**
+ * 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.
+ */
+declare interface UriSourceDescriptor {
+    readonly uri: string;
+    readonly filename: string;
+    readonly mimeType?: string;
+}
+
+declare interface UriTemplate {
+    readonly uri: string;
+    readonly description: string;
+    readonly operations?: readonly UriOperation[];
+    /**
+     * 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
+     * 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.
+     */
+    readonly operationDocs?: Partial<Record<UriOperation, string>>;
+    /**
+     * Per-operation default permission for this route, keyed by operation.
+     * When present, overrides the module-level {@link UriPermissionDefaults}
+     * for the named operations at this specific route (resource-glob scoped).
+     * Undeclared operations fall back to the module-level default, then to
+     * `"allow"` (fail-open).
+     */
+    readonly operationDefaults?: Partial<Record<UriOperation, UriPermissionDefault>>;
+    /**
+     * Parameters are DERIVED from the address pattern by `deriveTemplateParameters`
+     * (`template-route.ts`): every `<placeholder>` path segment and every `?key=<value>`
+     * query key becomes one. Author an entry only to add a description, a tighter schema,
+     * or examples; it overrides the derived entry with the same name. An authored name
+     * that is not a placeholder in `uri` is a lint failure, not a hidden extra.
+     */
+    readonly parameters?: readonly UriParameter[];
+    /**
+     * The payload contract for each mutating verb at THIS route, built with `payload()`
+     * from the same Zod validator the handler parses with. A contract without a `schema`
+     * is the typed "unstructured" declaration (raw text, YAML, a file body) and must be
+     * true of the handler. This is the only place a route's write or edit shape is
+     * disclosed; `help` renders it at the route and the tool catalog derives its facets
+     * from it.
+     */
+    readonly accepts?: Partial<Record<"write" | "edit", UriPayloadContract>>;
+    /** What `delete` does at this route and whether it can be undone. Required by lint on
+     *  every route that lists `delete`. */
+    readonly deleteEffect?: UriDeleteEffect;
+}
+
+declare interface UriValidationMessage {
+    readonly path?: string;
+    readonly message: string;
+}
+
+/**
+ * Author-declared, human-facing documentation of what each supported verb
+ * 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
+ * `kay.agent` URI modules, `auditPluginDisclosure` (`@kay/plugin-sdk/
+ * disclosure`) enforces coverage of every supported verb at authoring/load
+ * time.
+ *
+ * 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.
+ */
+declare interface UriVerbDocs {
+    /** What a `read` of this address space returns (also covers `help`). */
+    readonly read?: string;
+    /** What `list` enumerates, when it differs meaningfully from `read`. */
+    readonly list?: string;
+    /** What `search` queries, when it differs meaningfully from `read`. */
+    readonly search?: string;
+    /** What a `write` creates or overwrites at the provider. */
+    readonly write?: string;
+    /** What an `edit` changes in place at the provider. */
+    readonly edit?: string;
+    /** What a `delete` destroys or removes at the provider (and how recoverable it is). */
+    readonly delete?: string;
+}
+
+declare interface UriVerbSupport {
+    readonly readable: boolean;
+    readonly writable: boolean;
+    readonly editable: boolean;
+    readonly deletable?: boolean;
+    readonly listable: boolean;
+}
+
+/** A mediated resource supplied beside structured write content without entering model context. */
+declare interface UriWriteSource extends UriSourceDescriptor {
+    readonly content: string | Uint8Array;
+}
+
+declare interface UrlPatternClaim {
+    readonly kind: "urlPattern";
+    readonly pattern: UriPatternInit;
+    readonly normalizeTo?: string;
+    readonly examples?: readonly string[];
+}
+
+declare interface Usage {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    /** Subset of `cacheWrite` written with 1h retention. Only Anthropic reports this split. */
+    cacheWrite1h?: number;
+    /**
+     * Reasoning/thinking tokens, when the provider reports them. This is a subset of
+     * `output`: `output` already includes these tokens. Set to a number (possibly 0) by
+     * providers that expose a reasoning breakdown; left undefined by providers that don't.
+     */
+    reasoning?: number;
+    totalTokens: number;
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        total: number;
+    };
+}
+
+/** Validate freshly-entered material and resolve the provider account before persistence. */
+declare type ValidateApiKeyCredential = (input: ValidateApiKeyCredentialInput) => Promise<ValidateApiKeyCredentialResult>;
+
+declare interface ValidateApiKeyCredentialInput {
+    readonly accessToken: string;
+    /** Every declared field; empty for a classic single-secret scheme. */
+    readonly fields: Readonly<Record<string, string>>;
+    readonly signal: AbortSignal;
+}
+
+declare interface ValidateApiKeyCredentialResult {
+    readonly accountId: string;
+    readonly label?: string;
+    readonly identity?: AccountIdentity;
+    /** Non-secret observations the host may surface without retaining credential material. */
+    readonly capabilityChecks?: readonly ApiKeyCapabilityCheck[];
+}
+
+declare type ValidatePluginApiKeyCredential = ValidateApiKeyCredential;
+
+/**
+ * Vercel AI Gateway routing preferences.
+ * Controls which upstream providers the gateway routes requests to.
+ * @see https://vercel.com/docs/ai-gateway/models-and-providers/provider-options
+ */
+declare interface VercelGatewayRouting {
+    /** List of provider slugs to exclusively use for this request (e.g., ["bedrock", "anthropic"]). */
+    only?: string[];
+    /** List of provider slugs to try in order (e.g., ["anthropic", "openai"]). */
+    order?: string[];
+}
+
+declare const WhiteboardEntryEnvelope: z.ZodObject<{
+    id: z.ZodString;
+    typeId: z.ZodString;
+    schemaVersion: z.ZodNumber;
+    title: z.ZodString;
+    authorSessionId: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+
+declare type WhiteboardEntryEnvelope = Readonly<z.infer<typeof WhiteboardEntryEnvelope>>;
+
+declare const WhiteboardEntryInfo: z.ZodObject<{
+    name: z.ZodString;
+    revision: z.ZodString;
+    entry: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        typeId: z.ZodString;
+        schemaVersion: z.ZodNumber;
+        title: z.ZodString;
+        authorSessionId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    state: z.ZodEnum<{
+        available: "available";
+        unavailable: "unavailable";
+        "unsupported-version": "unsupported-version";
+        invalid: "invalid";
+    }>;
+    mutable: z.ZodBoolean;
+    diagnostics: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+
+declare type WhiteboardEntryInfo = Readonly<z.infer<typeof WhiteboardEntryInfo>>;
+
+declare const WhiteboardEntryInspection: z.ZodObject<{
+    name: z.ZodString;
+    revision: z.ZodString;
+    entry: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        typeId: z.ZodString;
+        schemaVersion: z.ZodNumber;
+        title: z.ZodString;
+        authorSessionId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    state: z.ZodEnum<{
+        available: "available";
+        unavailable: "unavailable";
+        "unsupported-version": "unsupported-version";
+        invalid: "invalid";
+    }>;
+    mutable: z.ZodBoolean;
+    diagnostics: z.ZodArray<z.ZodString>;
+    value: z.ZodOptional<z.ZodType<JsonValue_2, unknown, z.core.$ZodTypeInternals<JsonValue_2, unknown>>>;
+    text: z.ZodString;
+    truncated: z.ZodBoolean;
+}, z.core.$strict>;
+
+declare type WhiteboardEntryInspection = Readonly<z.infer<typeof WhiteboardEntryInspection>>;
+
+declare const WhiteboardEntrySnapshot: z.ZodObject<{
+    name: z.ZodString;
+    entry: z.ZodObject<{
+        id: z.ZodString;
+        typeId: z.ZodString;
+        schemaVersion: z.ZodNumber;
+        title: z.ZodString;
+        authorSessionId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    revision: z.ZodString;
+    value: z.ZodType<JsonValue_2, unknown, z.core.$ZodTypeInternals<JsonValue_2, unknown>>;
+}, z.core.$strict>;
+
+declare type WhiteboardEntrySnapshot = Readonly<Omit<z.infer<typeof WhiteboardEntrySnapshot>, "entry"> & {
+    readonly entry: WhiteboardEntryEnvelope;
+}>;
+
+declare const WhiteboardEntrySummary: z.ZodObject<{
+    name: z.ZodString;
+    entry: z.ZodObject<{
+        id: z.ZodString;
+        typeId: z.ZodString;
+        schemaVersion: z.ZodNumber;
+        title: z.ZodString;
+        authorSessionId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    revision: z.ZodString;
+}, z.core.$strict>;
+
+declare type WhiteboardEntrySummary = Readonly<Omit<z.infer<typeof WhiteboardEntrySummary>, "entry"> & {
+    readonly entry: WhiteboardEntryEnvelope;
+}>;
+
+declare const WhiteboardTypeInfo: z.ZodObject<{
+    typeId: z.ZodString;
+    displayName: z.ZodString;
+    schemaVersion: z.ZodNumber;
+    available: z.ZodBoolean;
+    presentation: z.ZodOptional<z.ZodObject<{
+        app: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+
+declare type WhiteboardTypeInfo = Readonly<z.infer<typeof WhiteboardTypeInfo>>;
+
+/** The logical plugin-defined JSON payload stored inside a host-owned entry envelope. */
+declare const WhiteboardValue: z.ZodType<JsonValue_2, unknown, z.core.$ZodTypeInternals<JsonValue_2, unknown>>;
+
+declare type WhiteboardValue = z.infer<typeof WhiteboardValue>;
+
+/**
+ * Run `use` against a live Jev client, falling back to `fallback` whenever Jev cannot serve the
+ * call. The wrapper exists so a feature can ASK for a typed decision without ever depending on
+ * one: `fallback` is required, and it runs whenever no host-managed key is saved,
+ * the user has not granted `jev.use`, the branch exceeds its budget, `use` throws, or
+ * `use` declines by returning `undefined`. With valid options, this rejects on an explicit
+ * `signal` abort, reaching `deadlineAt`, or `fallback` itself throwing.
+ *
+ * ALWAYS PRESENT on the plugin API, on every host. A host that composed no Jev lane binds
+ * {@link createFallbackOnlyWithJev}, so a caller never branches on availability — branching is
+ * exactly how a fallback gets skipped.
+ *
+ * `jev` is the vendor's own `TypeSafeClient`, configured with the host's default model and base
+ * URL. Native `request.model` overrides remain supported. It
+ * is valid only for the duration of the callback: a reference retained past `use`'s scope is
+ * refused at the transport, and an in-flight request is aborted when the call stops waiting.
+ * The callback itself is ABANDONED, not interrupted — a host cannot stop arbitrary JavaScript
+ * that is already running, so `use` must not perform side effects it would mind completing
+ * unobserved. The same applies to a running fallback: abort/deadline stops waiting for it but
+ * cannot interrupt its JavaScript.
+ */
+declare type WithJev = <T>(
+/** Return `undefined` to decline (the fallback runs). A feature whose real result can itself be
+ *  `undefined` should return `null` or its own wrapper type instead. */
+use: (jev: TypeSafeClient) => T | undefined | PromiseLike<T | undefined>, 
+/** Required. The behaviour the feature has without Jev. */
+fallback: () => T | PromiseLike<T>, options?: WithJevOptions) => Promise<T>;
+
+/** Per-call knobs for {@link WithJev}. Every field is optional; the host applies its own default
+ *  budget when none is given, so the Jev branch is never unbounded. */
+declare interface WithJevOptions {
+    /**
+     * Explicit cancellation. Always propagates as a rejection; never substituted with `fallback`,
+     * because an aborted call means "stop", not "use the cheaper path".
+     */
+    readonly signal?: AbortSignal;
+    /** Bounds the Jev branch alone, measured from the call. */
+    readonly timeoutMs?: number;
+    /**
+     * Absolute epoch-ms hard deadline for the WHOLE call, `fallback` included. A deadline already
+     * passed rejects (like `signal`); one still ahead derives the Jev branch's budget from it and
+     * keeps a small reserve so `fallback` has a window to run.
+     */
+    readonly deadlineAt?: number;
+    /** Attribution slug for host usage accounting. Never sent to Jev. */
+    readonly purpose?: string;
+}
+
+export { }