@yaklabs-ai/plugin-sdk 0.13.6 → 0.13.8

package/dist/vendored-mcp.d.ts

@@ -0,0 +1,1217 @@
+/**
+ * The URI module for one vendored-MCP integration plugin.
+ *
+ * What this module is FOR is worth stating plainly, because it is not what Linear's module does.
+ * A vendored-MCP plugin's value is three things: the vendor's MCP server (the whole action
+ * surface), recognition of the vendor's public links, and a branded, openable pill for them. This
+ * module is the second and third. It projects a pasted vendor URL onto a canonical `<ns>://` URI
+ * and back, and it answers `read` from the URI alone.
+ *
+ * ## Why `read` does not call MCP
+ *
+ * It could, and V1 deliberately does not. These servers have no uniform read: several expose only
+ * tools, and PostHog's is a single `exec` tool over a CLI-style DSL. There is no shape to project
+ * generically, so a generic MCP read would be a guess per vendor wearing one function's clothes.
+ * Instead `read` returns a reference card — what the resource is, its captured ids, the URL that
+ * opens it, and the server to call for anything deeper. When a vendor earns a real projection, it
+ * attaches as a per-vendor `read` beside this one; the shared card stays the floor.
+ *
+ * ## Why there is no `requiresAuth`
+ *
+ * Linear's module declares one because its `read` calls MCP and genuinely needs a credential.
+ * This module's `read` is a pure projection of the URI it was handed — no network, no credential.
+ * Declaring `requiresAuth` anyway would not be a harmless formality: an auth-gated module whose
+ * binding is unsatisfied has its public-web `urlPattern` claims suppressed and its `matches()`
+ * wrapped to decline `http(s)` (`agent-session.ts` `_suppressPublicUrlClaims`, and
+ * `authSuppressedCatalogModule` for discovery). A pasted Supabase link would therefore stay
+ * unbranded for every user who has not yet connected Supabase — which is exactly the user the
+ * branded pill is for. The vendor's MCP tools remain gated on their own, by the MCP host.
+ */
+export declare function createVendoredMcpUriModule(descriptor: VendoredMcpDescriptor): UriExtensionModule;
+
+declare type JsonPrimitive = string | number | boolean | null;
+
+declare type JsonSchema = Record<string, unknown>;
+
+declare type JsonValue = JsonPrimitive | {
+    readonly [key: string]: JsonValue;
+} | readonly JsonValue[];
+
+declare interface LineRange {
+    readonly start: number;
+    readonly end: number;
+}
+
+declare interface LineSelector {
+    readonly ranges: readonly LineRange[];
+    readonly raw: boolean;
+}
+
+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;
+}
+
+/** 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 type SelectorDisposition = {
+    readonly kind: "deferred";
+    readonly window?: LineSelector;
+} | {
+    readonly kind: "applied";
+} | {
+    readonly kind: "invalid";
+    readonly message: string;
+};
+
+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; see {@link UriExtensionOperationPermissionPolicy}. */
+    readonly permission?: UriExtensionOperationPermissionPolicy;
+    /** False rejects generic write-tool `source` copies before source fetch. */
+    readonly acceptsSourceCopy?: boolean;
+}
+
+declare interface UriExtensionOperationPermissionPolicy {
+    /**
+     * Classify one canonical route, purely. `write`/`edit`/`delete` may only be made stricter
+     * than the verb default; `help`/`read`/`list`/`search` must stay `"read"` (a `ruleKey` is
+     * allowed), because the kernel reruns a crash-interrupted read without asking again. Any
+     * other answer, or a throw, fails the call closed.
+     */
+    classifyOperation(request: {
+        readonly operation: UriOperation;
+        readonly uri: string;
+    }): {
+        readonly kind: "read" | "mutate" | "destructive" | "execute";
+        readonly ruleKey?: string;
+    } | undefined;
+}
+
+declare interface UriExternalCliRunner {
+    readonly run: (request: UriExternalCliRunRequest) => Promise<UriExternalCliRunResult>;
+}
+
+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[];
+    /**
+     * Set when this help, for the address it was asked about, carries text a third party wrote and
+     * the module relays as it received it (an MCP server's own tool names and descriptions), rather
+     * than text the module's author wrote. Absent: the module's own text.
+     */
+    readonly thirdPartyContent?: true;
+}
+
+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;
+    /**
+     * Whether this module parses the read tool's trailing line selector out of its own addresses.
+     * Absent or false: the host owns the explicit forms (`:50-200`, `:50-`, `:50+10`, `:raw`). The
+     * read tool strips one before dispatch, hands `read` the bare address, and applies the window
+     * to what comes back, so a module never has to know the grammar for the read tool's own
+     * `Continue with '<address>:N-M'` banner to work on its addresses (#10754). A bare trailing
+     * `:<digits>` is never taken from such a module: it is too common inside real ids (a Figma
+     * node `1:2`), so it reaches the module as written.
+     *
+     * Declare `true` only when the module must see the raw address: its grammar can end in an
+     * explicit-range shape, it wants the bare `:50` form too, or it windows the content itself
+     * (streaming a large file, skipping a cap it applies to an unwindowed read). Such a module
+     * calls `parseLineSelector` itself and reports what it did through `RawResource.selector`.
+     */
+    readonly ownsLineSelectors?: 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;
+    /**
+     * Structured facts for approval surfaces, or `undefined` when unavailable.
+     * A one-line description must name the whole consequence; `preview` instead
+     * supplies expanded, literal-text detail, and without a `quote` it suppresses one-line
+     * approval (a module that quotes the whole message keeps its line beside it). The module
+     * owns the static action phrase, target resolution, payload decoding and declaration
+     * of covered payload fields and query parameters. Unknown fields cost the summary.
+     * The host owns framing, the whole-quote fit (no elision) and display-safety admission.
+     *
+     * Unlike preflight, this hook is async and may do I/O. Resolve names through `ctx`,
+     * the same dispatch context used by execution, never an ambient or cached account. A name
+     * the module resolved under that account may be cached for a bounded time, keyed by that
+     * account's identity and never answered to another account or after a failed lookup.
+     * The host calls it once before raising the ask, enforces the short `ctx.signal`
+     * deadline and discards late answers. A throw yields no summary and a module-attributed
+     * diagnostic; declining costs a click into the app, never an under-described approval.
+     */
+    describeOperation?(request: {
+        readonly operation: UriOperation;
+        readonly uri: string;
+        readonly payload: unknown;
+    }, ctx: UriResolveContext): Promise<UriOperationDescription | undefined>;
+    /**
+     * Rebuild a call from the person's "Allow with edits" answer: the same payload
+     * {@link describeOperation} was given, with the values the person typed into the preview's
+     * `editable` fields put in their place. Implement it beside any preview that marks a field
+     * `editable`; without it the host drops every editable marker from that module's previews, so
+     * a field is never offered for editing that cannot be honoured.
+     *
+     * Pure and fast: it must not send, write or otherwise act, and it should not do I/O (it gets
+     * the dispatch context `ctx` only so a name can be resolved the way `describeOperation` does).
+     * Return the COMPLETE amended payload in the shape the module's own handler reads. Validate it
+     * with the handler's own schema, so an amended call is exactly as valid as one the model made.
+     * Decline by returning `undefined` or throwing; either denies the call with nothing done.
+     *
+     * The host calls it once, after the person allowed the call, never for a denial, and only for
+     * a `write` whose payload this module described. The kernel passes the `edits` through
+     * unchanged. Bonsai's daemon has already refused, before the ask settled, a key that is not an
+     * `editable` field of the preview it showed, a repeated key, a blank value and a value past the
+     * field's `maxLength`, but another host may not, so refuse each of those here yourself (return
+     * `undefined`).
+     *
+     * The host then holds the amended call to what the person was shown, in two steps, and runs it
+     * only if both pass. It classifies the amended call again and requires the same tool, rule key,
+     * kind, resources, scheme and target address, so an edit cannot reach a different route. It then
+     * calls {@link describeOperation} on the amended call and requires that preview to read exactly
+     * as the one the person saw, apart from the values of the fields they edited: the same title, the
+     * same fields in the same order, each with the same label, key, `editable` marker and
+     * `maxLength`, and every read-only field with the same value. Anything else refuses the call
+     * with nothing done: a mismatch, and also a describer that is missing, declines, throws or
+     * overruns its deadline. The `description` line is not compared.
+     *
+     * So rebuild from the original payload and change only the fields you offered. A recipient, a
+     * thread or an attachment list that an amendment changed is caught by the second step, but only
+     * where the preview shows it: put whatever says where a call goes, or what it does beyond its
+     * editable fields, in the preview's `title` or a field, never only in its `description`, and
+     * keep recipients, destinations and thread bindings out of `editable` fields.
+     */
+    amendOperation?(request: {
+        readonly operation: UriOperation;
+        readonly uri: string;
+        readonly payload: unknown;
+        readonly edits: readonly UriPreviewEdit[];
+    }, ctx: UriResolveContext): Promise<UriOperationAmendment | undefined>;
+    /**
+     * A short, render-only name for the resource a settled call on `request.uri` touched, which the
+     * host stamps on the tool result's `details` so a transcript row can name it where it would
+     * otherwise print the address (`#lane-analytics` and `thread`, not a channel id). Answer
+     * `undefined` for any address you cannot honestly name.
+     *
+     * Called once per successful URI verb call, AFTER the verb handler has returned, with the same
+     * dispatch context. Resolve names through `ctx` and nothing else, and prefer a cache your own
+     * verb handlers warm, keyed by the executing account: a name one account saw is never answered
+     * to another, and a failed, blank or aborted lookup is never cached. The host bounds the wait
+     * (a finished result is held at most a quarter of a second), gives `ctx.signal` a hard deadline,
+     * and drops a late, thrown or refused answer without failing the call; a throw is reported as a
+     * module-attributed diagnostic. The label is a label, never an identity: the address remains the
+     * click target, hover text and accessible name. It is UI-only, so it never enters the tool
+     * result's content and no telemetry reads it.
+     *
+     * Unlike `describeOperation` this is not an approval surface: it carries no consequence, no
+     * quote and no coverage claim, and nothing may gate a permission on it.
+     */
+    labelResource?(request: UriResourceLabelRequest, ctx: UriResolveContext): Promise<UriResourceLabel | undefined>;
+    /**
+     * Per-resource observability: does a `format: "observation"` read of THIS
+     * uri render source-native material ({@link UriResolveContext.format})?
+     * Route-parse only — cheap, side-effect-free, no I/O, no auth (the same
+     * discipline as `matches`); a throw is treated as `false`. Returning true
+     * is the resource's contract that its observation read returns an
+     * observation render and that failures under that format throw typed,
+     * status-bearing errors rather than resolving a friendly fallback page.
+     * The kernel stamps the answer onto the resource's access events, which is
+     * what ambient index consumers replay on — so "PRs are observable" is
+     * declared here, route by route, never module-wide. Absent means no read
+     * of this module is observable. A vendor's own gone-vocabulary (HTTP 410,
+     * a 200-body "ok:false"/"archived:true"/"status:cancelled", or a
+     * 403/404-ambiguous lost-access response) is this module's job to
+     * translate into `UriNotFoundError` or a `status: 404` error under the
+     * observation format — the fold that retires a doc never learns vendor
+     * vocabulary (see `ObservationMaterial`'s doc comment).
+     */
+    observes?(uri: string): boolean;
+    /**
+     * Head-only revision probe: the resource's CURRENT source-native revision
+     * without fetching its body, or `undefined` when that cannot be known
+     * cheaply. The host calls it before a repeat `read` of an address the
+     * session already holds, with `ctx.expectedRevision` set to the revision
+     * that read reported (`RawResourceMetadata.revision`); a value equal to it
+     * means "unchanged" and the fetch is skipped, anything else falls through
+     * to the ordinary read. A module whose read revision embeds more than the
+     * head can know (a content digest beside a stat stamp) may answer relative
+     * to `expectedRevision` — return it when the cheap part matches, `undefined`
+     * when it does not — but must never return a value it has not verified.
+     * `undefined` is always safe: it costs one fetch, never a wrong answer.
+     * Must be cheaper than the read (a metadata request, a `stat`); a throw is
+     * treated as `undefined`.
+     */
+    revision?(uri: string, ctx: UriResolveContext): Promise<string | undefined>;
+    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`, `help`, `list` and `search` observe; they never change the resource or anything
+     * outside the host. Repeating one with the same input must be harmless: the kernel reruns a
+     * call of these verbs that a crash cut off, with the same input, without asking the user
+     * again. Idempotent bookkeeping (a cache fill, an index of what was read, a usage count) is
+     * fine; a send, a mark-as-read or a create is not, and belongs on a mutating verb.
+     */
+    read(input: string, ctx: UriResolveContext): Promise<RawResource>;
+    /** Observes only; see {@link read}. */
+    help?(input: string, ctx: UriResolveContext): Promise<UriHelp>;
+    write?(input: string, content: UriPayload, ctx: UriResolveContext): Promise<UriMutationResult | void>;
+    /** Opt-in structured write with one or more host-resolved resources delivered beside the content. */
+    writeWithSources?(input: string, content: UriPayload, sources: readonly UriWriteSource[], ctx: UriResolveContext): Promise<UriMutationResult | void>;
+    /**
+     * Opt-in byte sink: write RAW BYTES to this address, no UTF-8 round trip.
+     * `UriPayload` is text/JSON by contract, so a module that can store bytes
+     * declares it here instead of stretching `write`. The only caller today is
+     * the `write` tool's `source` copy leg, which is how a provider's binary
+     * resource — a Gmail attachment, an image, a PDF, a zip — reaches a
+     * byte-capable destination without ever being decoded into the model's
+     * context. A module that omits it is text-only, and a binary copy targeting
+     * it is refused with an error naming a byte-capable destination.
+     *
+     * `source` describes what the bytes are: a filesystem-backed sink can ignore
+     * it (the target path already carries the name), while a remote provider
+     * sink needs it to name and type the stored file. It sits before `ctx` so a
+     * forwarding wrapper that fails to thread it is a compile error, not a
+     * silent drop.
+     */
+    writeBytes?(input: string, bytes: Uint8Array, source: UriSourceDescriptor, ctx: UriResolveContext): Promise<UriMutationResult | void>;
+    edit?(input: string, patch: UriPayload, ctx: UriResolveContext): Promise<UriMutationResult>;
+    /** Observes only; see {@link read}. */
+    list?(input: string, params: UriListParams, ctx: UriResolveContext): Promise<UriListResult>;
+    /** Observes only; see {@link read}. */
+    search?(input: string, params: UriSearchParams, ctx: UriResolveContext): Promise<UriSearchResult>;
+    delete?(input: string, ctx: UriResolveContext): Promise<UriMutationResult>;
+    toMarkdown?(input: UriMarkdownRenderInput, ctx: UriResolveContext): string | undefined;
+}
+
+/** Authoritative lifecycle facts for a successful record-like URI mutation. */
+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";
+
+/** The call {@link UriModule.amendOperation} rebuilt: the whole payload, in the shape the module reads. */
+declare interface UriOperationAmendment {
+    readonly payload: unknown;
+}
+
+declare interface UriOperationDescription {
+    /** Static verb phrase authored by the module. Never interpolated from input. */
+    readonly action: string;
+    /** Human name resolved through the connection that will execute the call. */
+    readonly target: string;
+    /** Model-authored content; the host flattens, budgets, elides and bounds it. */
+    readonly quote?: string;
+    /** Full, render-only detail. Hosts must not turn a rich preview into one-line approval. */
+    readonly preview?: {
+        readonly title: string;
+        readonly description?: string;
+        readonly fields?: readonly {
+            readonly label: string;
+            readonly value: string;
+            readonly oldValue?: string;
+            /**
+             * A stable, module-defined id for this field, unique within the preview (`subject`,
+             * `body`, `text`). It names the field in an "Allow with edits" answer, so it never
+             * depends on the displayed label. Required for an `editable` field.
+             */
+            readonly key?: string;
+            /**
+             * `true` offers this field to the person for editing on the approval card. Offer it only
+             * when the module implements {@link UriModule.amendOperation} for this call and can honour
+             * any value within `maxLength`; the host drops the offer otherwise. Absent means read-only.
+             */
+            readonly editable?: true;
+            /** Longest edited value, in UTF-16 code units. Meaningful only with `editable`. */
+            readonly maxLength?: number;
+        }[];
+    };
+    /** True only when every displayed fact comes from the input, independent of the executing account. */
+    readonly accountIndependent?: true;
+    /** What this description accounts for; the host refuses undeclared input. */
+    readonly accounts: {
+        /** The payload actually read by the module, after its own decoding. */
+        readonly payload: unknown;
+        readonly payloadFields: readonly string[];
+        readonly queryParams?: readonly string[];
+    };
+}
+
+/**
+ * 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;
+}
+
+/**
+ * One change a person made to an `editable` field of a call's action preview ("Allow with
+ * edits"): the field's `key` and the value they want it to hold. Values are message content, so
+ * a module must not log or persist them.
+ */
+declare interface UriPreviewEdit {
+    readonly key: string;
+    readonly value: string;
+}
+
+/** The read shape a caller may request via {@link UriResolveContext.format}. */
+declare type UriReadFormat = "observation";
+
+declare interface UriResolveContext {
+    readonly cwd: string;
+    readonly signal?: AbortSignal;
+    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 (Bonsai's form is `user`, `subagent`,
+     * `system/<surface>`, `followup/<surface>`) rather than a closed union: the surface half is the
+     * host's vocabulary, and a second enumeration of it here would drift from the first.
+     *
+     * Absent whenever the host has nothing to say — no session owns the dispatch, or the session
+     * 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;
+}
+
+/**
+ * What a settled call touched, as a person would name it.
+ *
+ * `name` is the resource itself (`#lane-analytics`). `section` is the part of it the address
+ * reaches into (`thread`), and is absent when the address is the resource.
+ */
+declare interface UriResourceLabel {
+    readonly name: string;
+    readonly section?: string;
+}
+
+/** The call a module is asked to label. */
+declare interface UriResourceLabelRequest {
+    readonly operation: UriOperation;
+    /** The dispatch address: selector-stripped, the exact form the module's verb handler received. */
+    readonly uri: string;
+}
+
+declare 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` (`@bonsai/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[];
+}
+
+/** The claim shape a module declares, sourced from the module contract rather than re-declared. */
+export declare type VendoredMcpClaim = NonNullable<UriExtensionModule["claims"]>[number];
+
+/**
+ * Everything a vendored-MCP plugin's URI module is, expressed as data.
+ *
+ * The plugin package supplies one of these and gets back a conformant {@link UriExtensionModule};
+ * it writes no read projection, no help document, and no route parsing. That is deliberate — this
+ * kit exists because five pilot plugins were about to become five copies of one 460-line module,
+ * and ~40 more are queued behind them.
+ */
+export declare interface VendoredMcpDescriptor {
+    /** Global module id, e.g. `supabase.resources`. Matches the manifest's resolved uriModule id. */
+    readonly moduleId: string;
+    /** The plugin namespace and canonical scheme, e.g. `supabase`. */
+    readonly namespace: string;
+    /** The vendor's display name, e.g. `Supabase`. */
+    readonly displayName: string;
+    /**
+     * What one of these resources IS, in the user's words, e.g. `Supabase project`. Keep it equal
+     * to the manifest's `referencePresentations[].resourceKind` so the pill and the card agree.
+     */
+    readonly resourceKind: string;
+    /** One sentence for the module description and the agent hint. Clamped at 220 chars upstream. */
+    readonly summary: string;
+    /**
+     * The public-web `urlPattern` claims that recognise this vendor's links. The scheme claim for
+     * {@link namespace} is added by the factory, so a descriptor can never forget the one claim the
+     * disclosure floor requires.
+     */
+    readonly claims: readonly VendoredMcpClaim[];
+    /** The canonical shapes this module addresses. At least one. */
+    readonly routes: readonly VendoredMcpRoute[];
+    /** Up to 8 keywords that should surface this module. */
+    readonly triggerKeywords: readonly string[];
+    /** The vendored MCP server's flat name, exactly as keyed in the manifest's `mcpServers`. */
+    readonly mcpServerName: string;
+    /** One line naming what the vendor's MCP tools cover, shown on every read card. */
+    readonly mcpSummary: string;
+    /** The plugin's own skill local ids, primer first. */
+    readonly skills: readonly string[];
+}
+
+/**
+ * One addressable resource shape, as the PAIR that makes the whole pattern work: the canonical
+ * `<ns>://…` URI Bonsai stores, and the public web URL that URI came from and opens back to.
+ *
+ * Both templates use the same `:name` capture syntax and MUST name exactly the same captures —
+ * {@link createVendoredMcpUriModule} throws otherwise. That symmetry is the point: a canonical
+ * URI carrying an id the web URL drops is a pill that cannot be opened, and a web URL naming a
+ * capture the canonical URI never captured renders a literal `:pageId` into the user's browser.
+ * Both are silent in a type system and loud here.
+ */
+export declare interface VendoredMcpRoute {
+    /** Canonical URI template, e.g. `supabase://project/:projectRef`. Needs at least one path segment. */
+    readonly uri: string;
+    /** Public web URL template over the same captures, e.g. `https://supabase.com/dashboard/project/:projectRef`. */
+    readonly webUrl: string;
+    /** One line naming what this address is, for `help()` templates and the read card. */
+    readonly description: string;
+    /** A concrete canonical URI for `help()`'s examples. Must match {@link uri}. */
+    readonly example: string;
+}
+
+export { }